4.4. Squish for JavaFX Tutorials

4.4.1. Tutorial: Starting to Test Java™FX Applications
4.4.2. Tutorial: Designing Behavior Driven Development (BDD) Tests
4.4.3. Tutorial: Migration of existing tests to BDD

Learn how to test JavaFX applications.

4.4.1. Tutorial: Starting to Test Java™FX Applications

This tutorial will show you how to create, run, and modify tests for an example JavaFX application. In the process you will learn about Squish's most frequently used features so that by the end of the tutorial you will be able to start writing your own tests for your own applications. (If you want to test Java AWT/Swing/SWT applications, you might prefer to read Tutorial: Starting to Test Java™ AWT/Swing Applications (Section 4.2.1) or Tutorial: Starting to Test Java™ SWT Applications (Section 4.3.1).)

This chapter presents most of the major concepts behind Squish and provides the information you need to get started using Squish for testing your own applications. This tutorial does not discuss all of Squish's features, and those that it does cover are not covered in full detail. After reading this tutorial we recommend reading the User Guide (Chapter 5), and at least skimming the API Reference Manual (Chapter 6) and the Tools Reference Manual (Chapter 7), so that you are familiar with all the features that Squish has to offer, even if you don't need to use them all straight away.

This tutorial is divided into several sections. If you are new to Squish (or to the new IDE introduced in Squish 4), it is best to read all of them. If you are already using Squish you might want to just skim the tutorial, stopping only to read those sections that cover any new features that you haven't used before—or you could just skip straight to the User Guide (Chapter 5).

Whenever we show how to achieve something using the IDE we will always follow with an explanation of how to do the same thing using the command line tools. Using an IDE is the easiest and best way to start, but once you build up lots of tests you will want to automate them, (e.g., doing nightly runs of your regression test suite), so it is worth knowing how to use the command line tools since they can be run from batch files or shell scripts.

The application we will test is a very simple Address Book application. Users can add new addresses via a dialog and remove addresses. They can also open and save address book data files. Although the application is very simple it has all the standard features that you are likely to want to use in your own tests, including menus, a table, and a pop-up dialog with line edits and buttons. Once you know how to test any of these user interface elements you will be able to apply the same principles to testing elements present in your own applications that are not used in the tutorial, such as tree views and number and date/time editors. (The User Guide (Chapter 5) has more comprehensive examples that show how to test lists, tables, and trees, and also the most common widgets, including date/time editors.)

The screenshot shows the application in action with a user adding a new name and address.

The JavaFX addressbook_javafx example.

The application (i.e., the AUT—Application Under Test) can be found with Squish's examples in squish/examples/java/addressbook_fx/AddressBook.jar. The tests that we will discuss in the following sections are in sub-folders, for example, the versions of the tests using the Python language are in squish/examples/java/addressbook_fx/suite_fx, with the tests written in other languages in similarly named sub-folders.

In principle, testing JavaFX and Java AWT/Swing/SWT applications works the same, so all the practices described in this tutorial can be applied to either. The only significant differences are that all of these toolkits use their own distinct set of widgets with different APIs (Application Programming Interfaces), and so our tests must of course access the toolkit-specific widgets and use the toolkit-specific APIs when we want to interact with them—for example, when checking that a particular widget's property holds a particular value.

[Note]Using the Examples

The first time you try running a test for one of the example AUTs you might get a fatal error that begins “Squish couldn't find the AUT to start...”. If this occurs, click the Test Suite Settings toolbar button, and in the Application Under Test (AUT) section choose the wrapper described above from the combobox if it is available, or click the Browse... button and choose the wrapper via the file open dialog that pops up. This only needs to be done once per example AUT. (This doesn't arise when testing your own AUTs.)

In the following sections we will create a test suite and then create some tests, but first we will very briefly review some key Squish concepts.

4.4.1.1. Squish Concepts

To perform testing, two things are required:

  1. an application to test—known as the Application Under Test (AUT), and

  2. a test script that exercises the AUT.

One fundamental aspect of Squish's approach is that the AUT and the test script that exercises it are always executed in two separate processes. This ensures that even if the AUT crashes, it should not crash Squish. (In such cases the test script will fail gracefully and log an error message.) In addition to insulating Squish and test scripts from AUT crashes, running the AUT and the test script in separate processes brings other benefits. For example, it makes it easier to store the test scripts in a central location, and it also makes it possible to perform remote testing on different machines and platforms. The ability to do remote testing is particularly useful for testing AUTs that run on multiple platforms, and also when testing AUTs that run on embedded devices.

Squish runs a small server (squishserver) that handles the communication between the AUT and the test script. The test script is executed by the squishrunner tool, which in turn connects to the squishserver. The squishserver starts the AUT and injects the Squish hook into it. The hook is a small library that makes the AUT's live running objects accessible and that can communicate with the squishserver. With the hook in place, the squishserver can query AUT objects regarding their state and can execute commands—all on behalf of the squishrunner. And the squishrunner itself requests that the AUT performs whatever actions the test script specifies. All the communication takes place using network sockets which means that everything can be done on a single machine, or the test script can be executed on one machine and the AUT can be tested over the network on another machine.

The following diagram illustrates how the individual Squish tools work together.

From the test engineer's perspective this separation is not noticeable, since all the communication is handled transparently behind the scenes.

Tests can be written and executed using the Squish IDE, in which case the squishserver is started and stopped automatically, and the test results are displayed in the Squish IDE's Test Results view (Section 8.2.15). The following diagram illustrates what happens behind the scenes when the Squish IDE is used.

The Squish tools can also be used from the command line without the Squish IDE—this is useful for those testers who prefer to use their own tools (for example, their favorite editor), and also for performing automatic batch testing (for example, when running regression tests overnight). In these cases, the squishserver must be started manually, and stopped when all the testing is complete (or, if preferred, started and stopped for each test).

For Squish to make it possible for test scripts to be able to query and control an AUT, Squish must be able to access the AUT's internals, and this is made possible by the use of bindings. Bindings are in effect libraries that provide access to the objects—and in turn to the objects' properties and methods—that are available from a GUI toolkit, or from the AUT itself.

When Squish automatically creates bindings to AUT classes, this means that objects of custom classes are automatically available in test scripts, without needing to be registered. The registration happens automatically when a class of an object is first time seen by Squish.

[Note]Terminology

The Squish documentation mostly uses the term widget when referring to GUI objects (i.e., buttons, menus, menu items, labels, table controls, etc). Windows users might be more familiar with the terms control and container, but here we use the term widget for both. Similarly, Mac OS X users may be used to the term view; again, we use the term widget for this concept.

4.4.1.1.1. Making an Application Testable

In most cases, nothing special needs to be done to make an application testable, since the toolkit's API (e.g., Qt) provides enough functionality to implement and record test scripts. The connection to the squishserver is also established automatically, when the Squish IDE starts the AUT.

[Note]The Squish Directory

Throughout the manual, we often refer to the SQUISH directory. This means the directory where Squish is installed, which might be C:\Squish, /usr/local/squish, /opt/local/squish, or somewhere else, depending on where you installed it. The exact location doesn't matter, so long as you mentally translate the SQUISH directory to whatever the directory really is when you see paths and filenames in this manual.

4.4.1.2. Creating a Test Suite

A test suite is a collection of one or more test cases (tests). Using a test suite is convenient since it makes it easy to share tests scripts and test data between a group of related tests.

Here, and throughout the tutorial, we will start by describing how to do things using the IDE, with the information for command line users following.

To begin with start up the Squish IDE, either by clicking or double-clicking the squishide icon, or by launching squishide from the taskbar menu or by executing squishide on the command line—whichever you prefer and that is suitable for the platform you are using. Once Squish starts up you might be greeted with a Welcome Page in case you're starting the squishide for the first time. Click the Workbench button in the upper right to dismiss it. Then, the squishide will look similar to the screenshot—but probably slightly different depending on the windowing system, colors, fonts, and theme that you use, and so on.

The Squish IDE with no Test Suites

Once Squish has started click File|New Test Suite... to pop-up the New Test Suite wizard shown below.

The New Test Suite wizard's Name & Directory page

Enter a name for your test suite and choose the folder where you want the test suite to be stored. In the screenshot we have called the test suite suite_py and will put it inside the addressbook_fx folder. (For your own tests you might use a more meaningful name such as "suite_addressbook"; we chose "suite_py" because for the sake of the tutorial we will create several suites, one for each scripting language that Squish supports.) Naturally, you can choose whatever name and folder you prefer. Once the details are complete, click Next to go on to the Toolkit (or Scripting Language) page.

[Note]Toolkits

Different versions of Squish support different toolkits—if your version only supports one toolkit, this page may not appear, and you may be taken directly to the Scripting Language page instead. And if you do get this page, the toolkits listed on it might be different from those shown here, depending on what options you built Squish with.

The New Test Suite wizard's Toolkit page

If you get this wizard page, click the toolkit your AUT uses. For this example, we must click Java since we are testing a Java application—it doesn't matter whether the AUT is JavaFX or AWT/Swing/SWT-based, the Java option covers all of them. Then click Next to go to the Scripting Language page.

[Note]Scripting Languages

Squish supports several different scripting languages, and different installations may include support for some or all of these—so the scripting languages shown in the screenshot may be different from those shown by your version of Squish.

The New Test Suite wizard's Scripting Language page

Choose whichever scripting language you want—the only constraint is that you can only use one scripting language per test suite. (So if you want to use multiple scripting languages, just create multiple test suites, one for each scripting language you want to use.) The functionality offered by Squish is the same for all languages. Having chosen a scripting language, click Next once more to get to the wizard's last page.

The New Test Suite wizard's AUT page

If you are creating a new test suite for an AUT that Squish already knows about, simply click the combobox to pop-down the list of AUTs and choose the one you want. If the combobox is empty or your AUT isn't listed, click the Browse button to the right of the combobox—this will pop-up a file open dialog from which you can choose your AUT. The AUT for the address book example is SQUISH/examples/java/addressbook_fx/AddressBook.jar. Once you have chosen the AUT, click Finish and Squish will create a sub-folder with the same name as the test suite, and will create a file inside that folder called suite.conf that contains the test suite's configuration details. Squish will also register the AUT with the squishserver. The wizard will then close and Squish's IDE will look similar to the screenshot below.

The Squish IDE with the suite_py test suite

We are now ready to start creating tests. Read on to learn how to create test suites without using the IDE, or skip ahead to Recording Tests and Verification Points (Section 4.4.1.3) if you prefer.

[Note]For command-line users

To create a new test suite from the command line, three steps are necessary: first, create a directory for the test suite; second, create a test suite configuration file; and third, register the AUT with squishserver.

  1. Create a new directory to hold the test suite—the directory's name should begin with suite. In this example we have created the squish/examples/java/addressbook_fx/suite_py directory for Python tests. (We also have similar subdirectories for other languages but this is purely for the sake of example, since normally we only use one language for all our tests.)

  2. Create a plain text file (ASCII or UTF-8 encoding) called suite.conf in the suite subdirectory. This is the test suite's configuration file, and at the minimum it must identify the AUT, the scripting language used for the tests, and the wrappers (i.e., the GUI toolkit or library) that the AUT uses. The format of the file is key = value, with one key–value pair per line. For example:

    AUT      = AddressBook.jar
    LANGUAGE = Python
    WRAPPERS = Java
    

    The AUT for JavaFX programs is the .jar file that contains the application. The LANGUAGE can be set to whichever one you prefer—currently Squish is capable of supporting JavaScript, Python 2, Perl, Ruby, and Tcl, but the precise availability may be different depending on how Squish was installed. For JavaFX and AWT/Swing/SWT programs, setting WRAPPERS to Java is sufficient.

  3. Register the AUT with the squishserver. [7] This is done by executing the squishserver on the command line with the --config option and the addAUT command. For example, assuming we are in the squish directory on Linux:

    squishserver --config addAUT AddressBook.jar \
    squish/examples/java/addressbook_fx
    

    Naturally Windows users would use \ instead of / as their directory separator.

    We must give the addAUT command the name of the AUT's executable and—separately—the AUT's path. In this case the path is to the .class file that was added as the AUT in the test suite configuration file. (For more information about application paths, see AUTs and Settings (Section 7.3) in the User Guide (Chapter 5).)

We are now ready to record our first test.

4.4.1.3. Recording Tests and Verification Points

Squish records tests using the scripting language that was specified for the test suite, rather than using a proprietary language. Once a test has been recorded we can run the test and Squish will faithfully repeat all the actions that we performed when recording the test, but without all the pauses that humans are prone to but which computers don't need. It is also possible—and very common—to edit recorded tests, or to copy parts of recorded tests into manually created tests, as we will see later on in the tutorial.

Recordings are always made into existing tests, so we must begin by creating a new "empty" test. There are two ways we can do this. One way is to click File|New Test Case.... This will pop up the New Squish Test Case wizard (Section 8.3.6)—simply enter the name for the test case and then click Finish. Another way is to click the New Test Case toolbar button (to the right of the "Test Cases" label in the Test Suites view); this will create a new test case with a default name (which you can easily change). Use one of these methods and give the new test case the name “tst_general”. Squish automatically creates a sub-folder inside the test suite's folder with this name and also a test file, in this case test.py. (If we had chosen JavaScript as our scripting language the file would be called test.js, and correspondingly for Perl, Ruby, or Tcl.)

The Squish IDE with the tst_general test case
[Note]Note

If you get a sample feature file instead of an empty script file, then click on the arrow left to the Run Test Suite button and select New Script Test Case.

To make the test script file (e.g., test.py) appear in an Editor view (Section 8.2.6), click—or double-click the test case. (Incidentally, the checkboxes are used to control which test cases are run when the Run Test Suite toolbar button is clicked; we can always run a single test case by clicking its Run Test button.) Initially, the script is empty. If we were to create a test manually (as we will do later on in the tutorial), we must create a main function. The name "main" is special to Squish—tests may contain as many functions and other code as we like (providing it is legal for the scripting language), but when the test is executed (i.e., run), Squish always executes the main function. This is actually very convenient since it means we are free to create other functions, import libraries, and so on, without problems. It is also possible to share commonly used code between test scripts—this is covered in the User Guide (Chapter 5). (In fact, two other function names are special to Squish, cleanup and init; see Tester-Created Special Functions (Section 6.1) for details.)

Once the new empty test case has been created we are now free to write test code manually, or to record a test. If we choose to record we can either replace all the test's code with the recorded code, or insert recorded code into the middle of some existing test code. We will only concern ourselves with recording and replacing in the tutorial.

[Note]For command-line users

Creating a new test case from the command line is an easy two-step process: first, create a test case directory; and second, create an empty test case script.

  1. Create a new subdirectory inside the test suite directory. For example, inside the squish/examples/java/addressbook_fx/suite_py directory, create the tst_general directory.

  2. Inside the test case's directory create an empty file called test.py (or test.js if you are using the JavaScript scripting language, and similarly for the other languages).

Before we dive into recording let's briefly review our very simple (and far from thorough) test case:

  1. Open the MyAddresses.adr address file.

  2. Navigate to the second address and then add a new name and address.

  3. Navigate to the first address and remove it.

  4. Verify that the first address is now the new one that was added.

We are now ready to record our first test. Click the Record Test Case toolbar button () that's to the right of the tst_general test case shown in the Test Suites view (Section 8.2.16)'s Test Cases list. This will cause Squish to run the AUT so that we can interact with it. Once the AUT is running perform the following actions—and don't worry about how long it takes since Squish doesn't record idle time:

  1. Click File|Open, and once the file dialog appears, open the file MyAddresses.adr.

  2. Click the second row, then click Edit|Add..., then click the first line edit in the Add dialog and type in "Jane". Now click (or tab to) the second line edit and type in "Doe". Continue similarly, to set an email address of "jane.doe@nowhere.com" and a phone number of "555 123 4567". Don't worry about typing mistakes—just backspace delete as normal and fix them. Finally, click the OK button. There should now be a new second address with the details you typed in.

  3. Now click the first row, then click Edit|Remove..., and then click the Yes button in the message box. The first row should be gone, so your "Jane Doe" entry should now be the first one.

  4. Click the Insert Verifications toolbar button in the Squish Control Bar and choose Properties from drop down list.

    This will make the Squish IDE appear. In the Application Objects view expand the Stage object, then the Scene, Root and TableView objects. Now expand the TableRow0 object. Click on each of its sub-objects to make its properties appear in the Properties view (Section 8.2.11). For each of them, check the text property. Finally, click the Save and Insert Verifications button (at the bottom of the Verification Point Creator view (Section 8.2.19)) to have the forename and surname verifications for the first row inserted into the recorded test script. (See the screenshot below.) Once the verification points are inserted the Squish IDE's window will be hidden again and the Control Bar window and the AUT will be back in view.

  5. We've now completed the test plan, so in the AUT click File|Quit, then click No in the message box, since we don't want to save any changes.

The Squish IDE showing two verification points about to be inserted

Once we quit the AUT, the recorded test will appear in Squish's IDE as the screenshot illustrates. (Note that the exact code that is recorded will vary depending on how you interact. For example, you might invoke menu options by clicking them or by using key sequences—it doesn't matter which you use, but since they are different, Squish will record them differently.)

The Squish IDE showing the recorded tst_general test

If the recorded test doesn't appear, click (or double-click depending on your platform and settings) the tst_general test case; this will make Squish show the test's test.py file in an editor window as shown in the screenshot.

The JavaFX-specific chooseFile function returns a filename as if the user had interacted with a standard windowing-system supplied file open dialog. Squish records the absolute path of the file to ensure reliability when running tests, but for this tutorial we have used scripting language facilities to provide a filename that will work wherever the example is installed.

Now that we've recorded the test we are able to play it back, i.e., run it. This in itself is useful in that if the play back failed it might mean that the application has been broken. Furthermore, the two verifications we put in will be checked on play back as the screenshot shows.

Inserting verification points during test recording is very convenient. Here we inserted two in one go, but we can insert as many as we like as often as we like during the test recording process. However, sometimes we might forget to insert a verification, or later on we might want to insert a new verification. We can easily insert additional verifications into a recorded test script as we will see in the next section, Inserting Additional Verification Points (Section 4.2.1.4).

Before going further we will look at how to record a test from the command line. Then we will see how to run a test, and we will also look at some of the code that Squish generated to record the test and discuss some of its features.

[Note]For command-line users

First and foremost, the squishserver must always be running when recording or running a test. This is handled automatically by the Squish IDE, but for command line users the squishserver must be started manually. (See squishserver (Section 7.4.4) for further details.)

To record a test from the command line we execute the squishrunner program and specify the test suite we want to record inside and the name we want to give to the test case. For example (assuming we are in the directory that contains the test suite's directory):

squishrunner --testsuite suite_py --record tst_general --useWaitFor

It is always best to record using the --useWaitFor option since this records calls to the waitForObject function which is more reliable than using the snooze function which for historical reasons is the default. (Note that the Squish IDE automatically uses the waitForObject function.)

To run a test case in the IDE just click the Run Test Case toolbar button (the green right-pointing triangle that appears when the test case is selected in the Test Suites view (Section 8.2.16)). This will cause Squish to run the AUT and replay every action (omitting human idle time, but allowing just enough time for the GUI toolkit to keep up). It is worth trying out since it has quite an impressive effect, especially if you haven't seen it in action before.

When we have two or more test cases we can run them individually by clicking the test case we want to run to select it and then clicking the Run Test button, or we can run them all (one after the other) by clicking the Run Test Suite toolbar button (which is above and slightly to the left of the Run Test button. (Actually, only those test cases that are checked are run by clicking the Run Test Suite toolbar button, so we can easily run a particular group of tests.)

[Note]For command-line users

As noted earlier, the squishserver must always be running when recording or running a test. (See squishserver (Section 7.4.4) for further details.)

To play back a recorded test from the command line we execute the squishrunner program and specify the test suite our recorded script is in and the test case we want to play. For example (assuming we are in the directory that contains the test suite's directory):

squishrunner --testsuite suite_py --testcase tst_general

In some cases it is possible that running the test will fail with an error message similar to this:

ERROR     	Mon Mar 23 15:41:12 2009	test.py:31: Script Error
    Error in closeWindow() invocation: null object

This sometimes happens if a dialog is dispose()d too quickly. Simply go to the offending line and comment out the closeWindow() call (which is on line 18 in this case) and re-run the test. The test should now work fine.

If you look at the code in the screenshot (or the code snippet shown below) you will see that it consists of lots of waitForObject calls as parameters to various other calls such as activateItem, clickButton, mouseClick, and type. The waitForObject function waits until a GUI object is ready to be interacted with (i.e., becomes visible and enabled), and is then followed by some function that interacts with the object. The typical interactions are activate (pop-up) a menu, click a menu option or a button, or type in some text. (For a complete overview of Squish's script commands see the User Guide (Chapter 5), the API Reference Manual (Chapter 6), and the Tools Reference Manual (Chapter 7). Objects are identified by names that Squish generates. (See How to Identify and Access Objects (Section 5.1) for full details.)

The generated code is about 30 lines of code. Here's an extract that just shows how Squish records clicking the Edit menu's Add option, typing in Jane Doe's details into the Add dialog, and clicking OK at the end to close the dialog and update the table.

[Note]Scripting Language Support

Although the screenshots only show the Python test suite in action, for the code snippets quoted here and throughout the tutorial, we show the code for all the scripting languages that Squish supports. In practice you would normally only use one of them of course, so feel free to just look at the snippets in the language you are interested in and skip the others. (In the HTML version of this manual you can use the combobox at the top of the page to select the language you use—this will hide the code snippets in other languages.)

Python

    mouseClick(waitForObject(":editAddButton_button"), 23, 17, 0, Button.Button1)
    type(waitForObject(":Address Book - Add.forenameText_text-input text-field"), "jane")
    type(waitForObject(":Address Book - Add.forenameText_text-input text-field"), "<Tab>")
    type(waitForObject(":Address Book - Add.surnameText_text-input text-field"), "smith")
    type(waitForObject(":Address Book - Add.surnameText_text-input text-field"), "<Tab>")
    type(waitForObject(":Address Book - Add.emailText_text-input text-field"), "jane@smith.com")
    type(waitForObject(":Address Book - Add.emailText_text-input text-field"), "<Tab>")
    type(waitForObject(":Address Book - Add.phoneText_text-input text-field"), "1231231234")
    mouseClick(waitForObject(":Address Book - Add._OK_button"), 15, 5, 0, Button.Button1)
JavaScript

    mouseClick(waitForObject(":editAddButton_button"), 23, 17, 0, Button.Button1);
    type(waitForObject(":Address Book - Add.forenameText_text-input text-field"), "jane");
    type(waitForObject(":Address Book - Add.forenameText_text-input text-field"), "<Tab>");
    type(waitForObject(":Address Book - Add.surnameText_text-input text-field"), "smith");
    type(waitForObject(":Address Book - Add.surnameText_text-input text-field"), "<Tab>");
    type(waitForObject(":Address Book - Add.emailText_text-input text-field"), "jane@smith.com");
    type(waitForObject(":Address Book - Add.emailText_text-input text-field"), "<Tab>");
    type(waitForObject(":Address Book - Add.phoneText_text-input text-field"), "1231231234");
    mouseClick(waitForObject(":Address Book - Add._OK_button"), 15, 5, 0, Button.Button1);
Perl

    mouseClick(waitForObject(":editAddButton_button"), 23, 17, 0, Button::Button1);
    type(waitForObject(":Address Book - Add.forenameText_text-input text-field"), "jane");
    type(waitForObject(":Address Book - Add.forenameText_text-input text-field"), "<Tab>");
    type(waitForObject(":Address Book - Add.surnameText_text-input text-field"), "smith");
    type(waitForObject(":Address Book - Add.surnameText_text-input text-field"), "<Tab>");
    type(waitForObject(":Address Book - Add.emailText_text-input text-field"), "jane\@smith.com");
    type(waitForObject(":Address Book - Add.emailText_text-input text-field"), "<Tab>");
    type(waitForObject(":Address Book - Add.phoneText_text-input text-field"), "1231231234");
    mouseClick(waitForObject(":Address Book - Add._OK_button"), 15, 5, 0, Button::Button1);
Ruby

  mouseClick(waitForObject(":editAddButton_button"), 23, 17, 0, Button::BUTTON1)
  type(waitForObject(":Address Book - Add.forenameText_text-input text-field"), "jane")
  type(waitForObject(":Address Book - Add.forenameText_text-input text-field"), "<Tab>")
  type(waitForObject(":Address Book - Add.surnameText_text-input text-field"), "smith")
  type(waitForObject(":Address Book - Add.surnameText_text-input text-field"), "<Tab>")
  type(waitForObject(":Address Book - Add.emailText_text-input text-field"), "jane@smith.com")
  type(waitForObject(":Address Book - Add.emailText_text-input text-field"), "<Tab>")
  type(waitForObject(":Address Book - Add.phoneText_text-input text-field"), "1231231234")
  mouseClick(waitForObject(":Address Book - Add._OK_button"), 31, 17, 0, Button::BUTTON1)
Tcl

    invoke mouseClick [waitForObject ":editAddButton_button"] 23 17 0 [enum Button Button1]
    invoke type [waitForObject ":Address Book - Add.forenameText_text-input text-field"] "jane"
    invoke type [waitForObject ":Address Book - Add.forenameText_text-input text-field"] "<Tab>" 
    invoke type [waitForObject ":Address Book - Add.surnameText_text-input text-field"] "smith"
    invoke type [waitForObject ":Address Book - Add.surnameText_text-input text-field"] "<Tab>"
    invoke type [waitForObject ":Address Book - Add.emailText_text-input text-field"] "jane@smith.com"
    invoke type [waitForObject ":Address Book - Add.emailText_text-input text-field"] "<Tab>"
    invoke type [waitForObject ":Address Book - Add.phoneText_text-input text-field"] "1231231234"
    invoke mouseClick [waitForObject ":Address Book - Add._OK_button"] 15 5 0 [enum Button Button1]

As you can see the tester used the keyboard to tab from one text field to another and clicked the OK button with the mouse. If the tester had moved the focus by clicking the mouse and clicked the OK button by tabbing to it and pressing Spacebar, or any other combination of interactions, the outcome would be the same, but of course Squish will have recorded the actual actions that were taken.

[Note]Note

Notice in the code snippet that there are no explicit delays. (It is possible to force a delay using Squish's snooze function.) This is because the waitForObject function delays until the object it is given is ready—thus allowing Squish to run as fast as the GUI toolkit can cope with, but no faster.

Another point to notice is that all the object names begin with a colon. This identifies them as symbolic names. Squish supports several naming schemes, all of which can be used—and mixed—in scripts. The advantage of using symbolic names is that if the application changes in a way that results in different names being generated, we can simply update Squish's Object Map (which relates symbolic names to real names), and thereby avoid the need to change our test scripts. (See the Object Map (Section 7.11) and the Object Map view (Section 8.2.9) for more about the Object Map.)

Now that we have seen how to record and play back a test and have seen the code that Squish generates, let's go a step further and make sure that at particular points in the test's execution certain conditions hold.

4.4.2. Tutorial: Designing Behavior Driven Development (BDD) Tests

This tutorial will show you how to create, run, and modify Behavior Driven Development (BDD) tests for an example application. You will learn about Squish's most frequently used features. By the end of the tutorial you will be able to write your own tests for your own applications.

For this chapter we will use a simple Address Book application written in JavaFX as our Application Under Test (AUT). This is a very basic application that allows users to load an existing address book or create a new one, add, edit, and remove entries. The screenshot shows the application in action with a user adding a new name and address.

The JavaFX addressbook example.

4.4.2.1. Introduction to Behavior Driven Development

Behavior-Driven Development (BDD) is an extension of the Test-Driven Development approach which puts the definition of acceptance criteria at the beginning of the development process as opposed to writing tests after the software has been developed. With possible cycles of code changes done after testing.

BDD process

Behavior Driven Tests are built out of a set of Feature files, which describe product features through the expected application behavior in one or many Scenarios. Each Scenario is built out of a sequence of Steps which represent actions or verifications that need to be tested for that Scenario.

BDD focuses on expected application behavior, not on implementation details. Therefore BDD tests are described in a human-readable Domain Specific Language (DSL). As this language is not technical, such tests can be created not only by programmers, but also by product owners, testers or business analysts. Additionally, during the product development, such tests serve as living product documentation. For Squish usage, BDD tests shall be created using Gherkin syntax. The previously written product specification (BDD tests) can be turned into executable tests. This step by step tutorial presents automating BDD tests with Squish IDE support.

4.4.2.2. Gherkin syntax

Gherkin files describe product features through the expected application behavior in one or many Scenarios. An example showing the "Filling of addressbook" feature of the addressbook example application.

Feature: Filling of addressbook
    As a user I want to fill the addressbook with entries

    Scenario: Initial state of created address book
        Given addressbook application is running
        When I create a new addressbook
        Then addressbook should have zero entries

    Scenario: State after adding one entry
        Given addressbook application is running
        When I create a new addressbook
        And I add a new person 'John','Doe','john@m.com','500600700' to address book
        Then '1' entries should be present

    Scenario: State after adding two entries
        Given addressbook application is running
        When I create a new addressbook
        And I add new persons to address book
            | forename  | surname  | email        | phone  |
            | John      | Smith    | john@m.com   | 123123 |
            | Alice     | Thomson  | alice@m.com  | 234234 |
        Then '2' entries should be present

    Scenario: Forename and surname is added to table
        Given addressbook application is running
        When I create a new addressbook
        When I add a new person 'Bob','Doe','Bob@m.com','123321231' to address book
        Then previously entered forename and surname shall be at the top

Most of the above is free form text (does not have to be English). It's just the Feature/Scenario structure and the leading keywords like "Given", "And", "When" and "Then" that are fixed. Each of those keywords marks a step defining preconditions, user actions and expected results. Above application behavior description can be passed to software developers to implement this features and at the same time the same description can be passed to software testers to implement automated tests.

4.4.2.3. Test implementation

4.4.2.3.1. Creating Test Suite

First, we need to create a Test Suite, which is a container for all Test Cases. Start the squishide and select File|New Test Suite.... Please follow the New Test Suite wizard, provide a Test Suite name, choose the Java Toolkit and scripting language of your choice and finally register Address Book application as AUT. Please refer to Creating a Test Suite (Section 4.4.1.2) for more details about creating new Test Suite.

4.4.2.3.2. Creating Test Case

Squish offers two types of Test Cases: "Script Test Case" and "BDD Test Case". As "Script Test Case" is the default one, in order to create new "BDD Test Case" we need to use the context menu by clicking on the expander next to New Test Case button and choosing the option "New BDD Test Case". The Squish IDE will remember your choice and the "BDD Test Case" will become the default when clicking on the button in the future.

Creating new BDD Test Case

The newly created BDD Test Case consists of a test.feature file (filled with a Gherkin template while creating a new BDD test case), a file named test.(py|js|pl|rb|tcl) which will drive the execution (there is no need to edit this file), and a Test Suite Resource file named steps/steps.(py|js|pl|rb|tcl) where Step implementation code will be placed.

We need to replace the Gherkin template with a Feature for the addressbook example application. To do this, copy the Feature description below and paste it into the Feature file.

Feature: Filling of addressbook
    As a user I want to fill the addressbook with entries

    Scenario: Initial state of created address book
        Given addressbook application is running
        When I create a new addressbook
        Then addressbook should have zero entries

After saving the test.feature file, a Feature file warning "No implementation found" is displayed for each Step. This means that no Step implementation was found in the steps subdirectory, in Test Case Resources, or in Test Suite Resources. Running our Feature test now will currently fail at the first step with a "No Matching Step Definition" error and the following Steps will be skipped.

4.4.2.3.3. Recording Step implementation

In order to record the Scenario, press the Record button next to the respective Scenario that is listed in the Scenarios tab in Test Case Resources view.

Record Scenario

This will cause Squish to run the AUT so that we can interact with it. Additionally, the Control Bar is displayed with a list of all Steps that need to be recorded. Now all interaction with the AUT or any verification points added to the script will be recorded under the first step Given addressbook application is running (which is bolded in the Step list on the Control Bar). In order to verify that this precondition is met, we will add a Verification Point. To do this, click on Insert Verifications on the Control Bar and select Properties.

Control Bar

As a result the Squish IDE is put into Spy mode which displays all Application Objects and their properties. Select the checkbox in front of the property showing in the Properties View. Finally, click on the button Save and Insert Verifications. The Squish IDE disappears and the Control Bar is shown again.

Inserting Verification Point

When we are done with the first step, we can move to the next Step in the sequence by clicking on the finish recording button in the Control Bar that is located in front of the current Step ().

Next, for the Step "When I create a new addressbook" click on the New button on the toolbar of the AddressBook application. Again, click finish recording for advancing to the last step.

Finally, for the step "Then addressbook should have zero entries" verify that the table containing the address entries is empty. To record this verification, click on Insert Verifications on the Squish control bar, select Properties and use the Picker tool to point at the table containing the address book entries (in our case this table is empty). Click inside the table area, then after the Squish IDE appears, press the 'Up' button in the Application Objects view, to go from the internal JavaFX javafx.scene.layout.StackPane to it's parent javafx.scene.control.TableView.

Up and Picker tool Buttons

Expand the Choose items property from Object Properties list. Then select empty and press Save and Insert Verifications. As a result, Squish will generate the following Step definitions:

Python
@Given("addressbook application is running")
def step(context):
    startApplication("AddressBook.jar");
    test.compare(waitForObjectExists(":Address Book_Stage").showing, True)

@Step("I create a new addressbook")
def step(context):
    mouseClick(waitForObject(":fileNewButton_button"), 22, 27, 0, Button.Button1)

@Then("addressbook should have zero entries")
def step(context):
    test.compare(waitForObjectExists(":Address Book - Unnamed.itemTbl_table-view").items.empty, True)
JavaScript
Given("addressbook application is running", function(context) {
        startApplication("AddressBook.jar");
        test.compare(waitForObjectExists(":Address Book_Stage").showing, true);
    });

When("I create a new addressbook", function(context) {
        mouseClick(waitForObject(":fileNewButton_button"), 22, 27, 0, Button.Button1);
    });

Then("addressbook should have zero entries", function(context) {
        test.compare(waitForObjectExists(":Address Book - Unnamed.itemTbl_table-view").items.empty, true);
    });

Perl
Given("addressbook application is running", sub {
    my $context = shift;
    startApplication("AddressBook.jar");
    test::compare(waitForObjectExists(":Address Book_Stage")->showing, 1);
});

When("I create a new addressbook", sub {
    my $context = shift;
    mouseClick(waitForObject(":fileNewButton_button"), 21, 20, 0, Button::Button1);
});

Then("addressbook should have zero entries", sub {
    my $context = shift;
    test::compare(waitForObjectExists(":Address Book - Unnamed.itemTbl_table-view")->items->empty, 1);
});
Ruby
Given("addressbook application is running") do |context|
  startApplication("AddressBook.jar")
  Test.compare(waitForObjectExists(":Address Book_Stage").showing, true)
end

When("I create a new addressbook") do |context|
  mouseClick(waitForObject(":fileNewButton_button"), 22, 27, 0, Button::BUTTON1 );
end

Then("addressbook should have zero entries") do |context|
  Test.compare(waitForObjectExists(":Address Book - Unnamed.itemTbl_table-view").items.empty, true)
end
Tcl
Given "addressbook application is running" {context} {
    startApplication "AddressBook.jar"
    test compare [property get [waitForObjectExists ":Address Book_Stage"] showing] true
}

When "I create a new addressbook" {context} {
    invoke mouseClick [waitForObject ":fileNewButton_button]" 22 27 0 [enum Button Button1]
}

Then "addressbook should have zero entries" {context} {
    test compare [property get [property get [waitForObjectExists ":Address Book - Unnamed.itemTbl_table-view"] items] empty] true
}

The application is automatically started at the beginning of the first step due to the recorded startApplication call. At the end of each Step, Squish detaches from the application, but leaves it running. Detaching is done in function called OnScenarioEnd. This function is a so-called hook and you can find it in the file bdd_hooks.(py|js|pl|rb|tcl), which is located in the Scripts tab of the Test Suite Resources view. You can define additional hooks. For a list of all available hooks please refer to Performing Actions During Test Execution Via Hooks (Section 6.19.9).

Python
@OnScenarioEnd
def hook(context):
    for ctx in applicationContextList():
        ctx.detach()
JavaScript
OnScenarioEnd(function(context) {
    applicationContextList().forEach(function(ctx) { ctx.detach(); });
});
Perl
OnScenarioEnd(sub {
    foreach (applicationContextList()) {
        $_->detach();
    }
});
Ruby
OnScenarioEnd do |context|
  applicationContextList().each { |ctx| ctx.detach() }
end
Tcl
OnScenarioEnd { context } {
    foreach ctx [applicationContextList] {
        applicationContext $ctx detach
    }
}
4.4.2.3.4. Manual Step implementation

An alternative approach to recording Step implementations is to manually implement them. This gives us the opportunity to modularize our test scripts (i.e. put common code into shared functions, keep test data separate from test scripts). Squish can help with that by creating skeletons of step definitions. To generate a Step implementation, right-click on the given Scenario in the Feature file and choose the option Create Missing Step Implementations from context menu.

Python
@Given("addressbook application is running")
def step(context):
    test.warning("TODO implement addressbook application is running")

@When("I create a new addressbook")
def step(context):
    test.warning("TODO implement I create a new addressbook")

@Then("addressbook should have zero entries")
def step(context):
    test.warning("TODO implement addressbook should have zero entries")
JavaScript
Given("addressbook application is running", function(context) {
    test.warning("TODO implement addressbook application is running");
});

When("I create a new addressbook", function(context) {
    test.warning("TODO implement I create a new addressbook");
});

Then("addressbook should have zero entries", function(context) {
    test.warning("TODO implement addressbook should have zero entries");
});
Perl
Given("addressbook application is running", sub {
    my $context = shift;
    test::warning("TODO implement addressbook application is running");
});

When("I create a new addressbook", sub {
    my $context = shift;
    test::warning("TODO implement I create a new addressbook");
});

Then("addressbook should have zero entries", sub {
    my $context = shift;
    test::warning("TODO implement addressbook should have zero entries");
});
Ruby
Given("addressbook application is running") do |context|
  Test.warning "TODO implement addressbook application is running"
end

When("I create a new addressbook") do |context|
  Test.warning "TODO implement I create a new addressbook"
end

Then("addressbook should have zero entries") do |context|
  Test.warning "TODO implement addressbook should have zero entries"
end
Tcl
Given "addressbook application is running" {context} {
    test warning "TODO implement addressbook application is running"
}

When "I create a new addressbook" {context} {
    test warning "TODO implement I create a new addressbook"
}

Then "addressbook should have zero entries" {context} {
    test warning "TODO implement addressbook should have zero entries"
}

Next implement Steps definition taking full advantage of Squish API (API Reference Manual (Chapter 6)) and remove the generated test.warning calls when you are done.

4.4.2.3.5. Step parameterization

So far, our Steps did not use any parameters and all values were hardcoded. Squish has different types of parameters like any, integer or word, allowing our Step definitions to be more reusable. Let us add a new Scenario to our Feature file which will provide Step parameters for both the Test Data and the expected results. Copy the below section into your Feature file.

Scenario: State after adding one entry
    Given addressbook application is running
    When I create a new addressbook
    And I add a new person 'John','Doe','john@m.com','500600700' to address book
    Then '1' entries should be present

After auto-saving the Feature file, the Squish IDE provides a hint that only 2 Steps need to be implemented: When I add a new person 'John', 'Doe','john@m.com','500600700' to address book and Then '1' entries should be present. The remaining Steps already have a matching Step implementation.

To record the missing Steps, hit the record button next to the test case name in the Test Suites view. The script will play until it gets to the missing Step and then prompt you to implement it. If you select the Add button, then you can type in the information for a new entry. Click on the button to move to the next step. For the second missing step, we could record an object property verification like we did with the Step Then addressbook should have zero entries. Or we could copy that step's implmentation in the steps.(py|js|pl|rb|tcl) file and increment the number at the end of the test.compare line. Instead of testing for zero items, we are testing for one item.

Now we paramaterize the generated step implementation by replacing the values with parameter types. Since we want to be able to add different names, replace 'John' with '|word|'. Note that each parameter will be passed to the step implementation function in the order of appearance in the descriptive name of the step. Finish paramaterizing by editing the typed values into keywords, to look like this example Step When I add a new person 'John', 'Doe','john@m.com','500600700' to address book:

Python
@When("I add a new person '|word|','|word|','|any|','|integer|' to address book")
def step(context, forename, lastname, email, phone):
    mouseClick(waitForObject(":editAddButton_button"))
    type(waitForObject(":Address Book - Add.forenameText_text-input text-field"), forename)
    mouseClick(waitForObject(":Address Book - Add.surnameText_text-input text-field"))
    type(waitForObject(":Address Book - Add.surnameText_text-input text-field"), lastname)
    mouseClick(waitForObject(":Address Book - Add.emailText_text-input text-field"))
    type(waitForObject(":Address Book - Add.emailText_text-input text-field"), email)
    mouseClick(waitForObject(":Address Book - Add.phoneText_text-input text-field"))
    type(waitForObject(":Address Book - Add.phoneText_text-input text-field"), phone)
    mouseClick(waitForObject(":Address Book - Add._OK_button"))
JavaScript
When("I add a new person '|word|','|word|','|any|','|integer|' to address book",
    function (context, forename, surname, email, phone){
        mouseClick(waitForObject(":editAddButton_button"));
        mouseClick(waitForObject(":Address Book - Add.forenameText_text-input text-field"));
        type(waitForObject(":Address Book - Add.forenameText_text-input text-field"), forename);
        mouseClick(waitForObject(":Address Book - Add.surnameText_text-input text-field"));
        type(waitForObject(":Address Book - Add.surnameText_text-input text-field"), lastname);
        mouseClick(waitForObject(":Address Book - Add.emailText_text-input text-field"));
        type(waitForObject(":Address Book - Add.emailText_text-input text-field"), email);
        mouseClick(waitForObject(":Address Book - Add.phoneText_text-input text-field"));
        type(waitForObject(":Address Book - Add.phoneText_text-input text-field"), phone);
        mouseClick(waitForObject(":Address Book - Add._OK_button"));
});
Perl
When("I add a new person '|word|','|word|','|any|','|integer|' to address book", sub {
    my ($context, $forename, $surname, $email, $phone) = @_;
    mouseClick(waitForObject(":editAddButton_button"));
    type(waitForObject(":Address Book - Add.forenameText_text-input text-field"), $forename);
    mouseClick(waitForObject(":Address Book - Add.surnameText_text-input text-field"));
    type(waitForObject(":Address Book - Add.surnameText_text-input text-field"), $surname);
    mouseClick(waitForObject(":Address Book - Add.emailText_text-input text-field"));
    type(waitForObject(":Address Book - Add.emailText_text-input text-field"), $email);
    mouseClick(waitForObject(":Address Book - Add.phoneText_text-input text-field"));
    type(waitForObject(":Address Book - Add.phoneText_text-input text-field"), $phone);
    mouseClick(waitForObject(":Address Book - Add._OK_button"));
});
Ruby
When("I add a new person '|word|','|word|','|any|','|integer|' to address book") do |context, forename, surname, email, phone|
  mouseClick(waitForObject(":editAddButton_button"))
  type(waitForObject(":Address Book - Add.forenameText_text-input text-field"), forename)
  mouseClick(waitForObject(":Address Book - Add.surnameText_text-input text-field"))
  type(waitForObject(":Address Book - Add.surnameText_text-input text-field"), surname)
  mouseClick(waitForObject(":Address Book - Add.emailText_text-input text-field"))
  type(waitForObject(":Address Book - Add.emailText_text-input text-field"), email)
  mouseClick(waitForObject(":Address Book - Add.phoneText_text-input text-field"))
  type(waitForObject(":Address Book - Add.phoneText_text-input text-field"), phone)
  mouseClick(waitForObject(":Address Book - Add._OK_button"))
end
Tcl
When "I add a new person '|word|','|word|','|any|','|integer|' to address book" {context forename surname email phone} {
    invoke mouseClick [waitForObject ":editAddButton_button"]
    invoke type [waitForObject ":Address Book - Add.forenameText_text-input text-field"] $forename
    invoke mouseClick [waitForObject ":Address Book - Add.surnameText_text-input text-field"]
    invoke type [waitForObject ":Address Book - Add.surnameText_text-input text-field"] $surname
    invoke mouseClick [waitForObject ":Address Book - Add.emailText_text-input text-field"]
    invoke type [waitForObject ":Address Book - Add.emailText_text-input text-field"] $email
    invoke mouseClick [waitForObject ":Address Book - Add.phoneText_text-input text-field"]
    invoke type [waitForObject ":Address Book - Add.phoneText_text-input text-field"] $phone
    invoke mouseClick [waitForObject ":Address Book - Add._OK_button"]
}
4.4.2.3.6. Provide parameters for Step in table

The next Scenario will test adding multiple entries to the address book. We could use step When I add a new person John','Doe','john@m.com','500600700' to address book multiple times just with different data. But lets instead define a new Step called When I add a new person to address book which will handle data from a table.

Scenario: State after adding two entries
    Given addressbook application is running
    When I create a new addressbook
    And I add new persons to address book
        | forename  | surname  | email        | phone  |
        | John      | Smith    | john@m.com   | 123123 |
        | Alice     | Thomson  | alice@m.com  | 234234 |
    Then '2' entries should be present

The Step implementation to handle such tables looks like this:

Python
@When("I add new persons to address book")
def step(context):
    table = context.table

    # Drop initial row with column headers
    table.pop(0)

    for (forename, surname, email, phone) in table:
        mouseClick(waitForObject(":editAddButton_button"))
        type(waitForObject(":Address Book - Add.forenameText_text-input text-field"), forename)
        mouseClick(waitForObject(":Address Book - Add.surnameText_text-input text-field"))
        type(waitForObject(":Address Book - Add.surnameText_text-input text-field"), surname)
        mouseClick(waitForObject(":Address Book - Add.emailText_text-input text-field"))
        type(waitForObject(":Address Book - Add.emailText_text-input text-field"), email)
        mouseClick(waitForObject(":Address Book - Add.phoneText_text-input text-field"))
        type(waitForObject(":Address Book - Add.phoneText_text-input text-field"), phone)
        mouseClick(waitForObject(":Address Book - Add._OK_button"))
JavaScript

When("I add new persons to address book", function(context) {
    var table = context.table;

    // Skip initial row with column headers by starting at index 1
    for (var i = 1; i < table.length; ++i) {
        var row = table[i];
        mouseClick(waitForObject(":editAddButton_button"));
        mouseClick(waitForObject(":Address Book - Add.forenameText_text-input text-field"));
        type(waitForObject(":Address Book - Add.forenameText_text-input text-field"), row[0]);
        mouseClick(waitForObject(":Address Book - Add.surnameText_text-input text-field"));
        type(waitForObject(":Address Book - Add.surnameText_text-input text-field"), row[1]);
        mouseClick(waitForObject(":Address Book - Add.emailText_text-input text-field"));
        type(waitForObject(":Address Book - Add.emailText_text-input text-field"), row[2]);
        mouseClick(waitForObject(":Address Book - Add.phoneText_text-input text-field"));
        type(waitForObject(":Address Book - Add.phoneText_text-input text-field"), row[3]);
        mouseClick(waitForObject(":Address Book - Add._OK_button"));
    }
});

Perl
When("I add new persons to address book", sub {
    my $context = shift;
    my $table = $context->{'table'};

    # Drop initial row with column headers
    shift(@{$table});

    for my $row (@{$table}) {
        my ($forename, $surname, $email, $phone) = @{$row};
        mouseClick(waitForObject(":editAddButton_button"));
        type(waitForObject(":Address Book - Add.forenameText_text-input text-field"), $forename);
        mouseClick(waitForObject(":Address Book - Add.surnameText_text-input text-field"));
        type(waitForObject(":Address Book - Add.surnameText_text-input text-field"), $surname);
        mouseClick(waitForObject(":Address Book - Add.emailText_text-input text-field"));
        type(waitForObject(":Address Book - Add.emailText_text-input text-field"), $email);
        mouseClick(waitForObject(":Address Book - Add.phoneText_text-input text-field"));
        type(waitForObject(":Address Book - Add.phoneText_text-input text-field"), $phone);
        mouseClick(waitForObject(":Address Book - Add._OK_button"));
    }
});
Ruby
When("I add new persons to address book") do |context|
  table = context.table

  # Drop initial row with column headers
  table.shift

  for forename, surname, email, phone in table do
      mouseClick(waitForObject(":editAddButton_button"))
      type(waitForObject(":Address Book - Add.forenameText_text-input text-field"), forename)
      mouseClick(waitForObject(":Address Book - Add.surnameText_text-input text-field"))
      type(waitForObject(":Address Book - Add.surnameText_text-input text-field"), surname)
      mouseClick(waitForObject(":Address Book - Add.emailText_text-input text-field"))
      type(waitForObject(":Address Book - Add.emailText_text-input text-field"), email)
      mouseClick(waitForObject(":Address Book - Add.phoneText_text-input text-field"))
      type(waitForObject(":Address Book - Add.phoneText_text-input text-field"), phone)
      mouseClick(waitForObject(":Address Book - Add._OK_button"))
  end
end
Tcl
When "I add new persons to address book" {context} {
    set table [$context table]

    # Drop initial row with column headers
    foreach row [lreplace $table 0 0] {
        foreach {forename surname email phone} $row break
        invoke mouseClick [waitForObject ":editAddButton_button"]
        invoke type [waitForObject ":Address Book - Add.forenameText_text-input text-field"] $forename
        invoke mouseClick [waitForObject ":Address Book - Add.surnameText_text-input text-field"]
        invoke type [waitForObject ":Address Book - Add.surnameText_text-input text-field"] $surname
        invoke mouseClick [waitForObject ":Address Book - Add.emailText_text-input text-field"]
        invoke type [waitForObject ":Address Book - Add.emailText_text-input text-field"] $email
        invoke mouseClick [waitForObject ":Address Book - Add.phoneText_text-input text-field"]
        invoke type [waitForObject ":Address Book - Add.phoneText_text-input text-field"] $phone
        invoke mouseClick [waitForObject ":Address Book - Add._OK_button"]
    }
}
4.4.2.3.7. Sharing data between Steps and Scenarios

Lets add a new Scenario to the Feature file. This time we would like to check not the number of entries in address book list, but if this list contains proper data. Because we enter data into the address book in one Step and verify them in another, we must share information about entered data among those Steps in order to perform a verification.

Scenario: Forename and surname is added to table
    Given addressbook application is running
    When I create a new addressbook
    When I add a new person 'Bob','Doe','Bob@m.com','123321231' to address book
    Then previously entered forename and surname shall be at the top

To share this data, the userData property of context object can be used.

Python
@When("I add a new person '|word|','|word|','|any|','|integer|' to address book")
def step(context, forename, lastname, email, phone):
    mouseClick(waitForObject(":editAddButton_button"))
    type(waitForObject(":Address Book - Add.forenameText_text-input text-field"), forename)
    mouseClick(waitForObject(":Address Book - Add.surnameText_text-input text-field"))
    type(waitForObject(":Address Book - Add.surnameText_text-input text-field"), lastname)
    mouseClick(waitForObject(":Address Book - Add.emailText_text-input text-field"))
    type(waitForObject(":Address Book - Add.emailText_text-input text-field"), email)
    mouseClick(waitForObject(":Address Book - Add.phoneText_text-input text-field"))
    type(waitForObject(":Address Book - Add.phoneText_text-input text-field"), phone)
    mouseClick(waitForObject(":Address Book - Add._OK_button"))
    context.userData = { 'forename': forename, 'lastname': lastname }
JavaScript
When("I add a new person '|word|','|word|','|any|','|integer|' to address book",
    function (context, forename, surname, email, phone){
        mouseClick(waitForObject(":editAddButton_button"));
        mouseClick(waitForObject(":Address Book - Add.forenameText_text-input text-field"));
        type(waitForObject(":Address Book - Add.forenameText_text-input text-field"), forename);
        mouseClick(waitForObject(":Address Book - Add.surnameText_text-input text-field"));
        type(waitForObject(":Address Book - Add.surnameText_text-input text-field"), lastname);
        mouseClick(waitForObject(":Address Book - Add.emailText_text-input text-field"));
        type(waitForObject(":Address Book - Add.emailText_text-input text-field"), email);
        mouseClick(waitForObject(":Address Book - Add.phoneText_text-input text-field"));
        type(waitForObject(":Address Book - Add.phoneText_text-input text-field"), phone);
        mouseClick(waitForObject(":Address Book - Add._OK_button"));
        context.userData = {};
        context.userData['forename'] = forename;
        context.userData['lastname'] = lastname;
});
Perl
When("I add a new person '|word|','|word|','|any|','|integer|' to address book", sub {
    my ($context, $forename, $surname, $email, $phone) = @_;
    mouseClick(waitForObject(":editAddButton_button"));
    type(waitForObject(":Address Book - Add.forenameText_text-input text-field"), $forename);
    mouseClick(waitForObject(":Address Book - Add.surnameText_text-input text-field"));
    type(waitForObject(":Address Book - Add.surnameText_text-input text-field"), $surname);
    mouseClick(waitForObject(":Address Book - Add.emailText_text-input text-field"));
    type(waitForObject(":Address Book - Add.emailText_text-input text-field"), $email);
    mouseClick(waitForObject(":Address Book - Add.phoneText_text-input text-field"));
    type(waitForObject(":Address Book - Add.phoneText_text-input text-field"), $phone);
    mouseClick(waitForObject(":Address Book - Add._OK_button"));
    $context->{userData}{'forename'} = $forename;
    $context->{userData}{'surname'} = $surname;
});
Ruby
When("I add a new person '|word|','|word|','|any|','|integer|' to address book") do |context, forename, surname, email, phone|
  mouseClick(waitForObject(":editAddButton_button"))
  type(waitForObject(":Address Book - Add.forenameText_text-input text-field"), forename)
  mouseClick(waitForObject(":Address Book - Add.surnameText_text-input text-field"))
  type(waitForObject(":Address Book - Add.surnameText_text-input text-field"), surname)
  mouseClick(waitForObject(":Address Book - Add.emailText_text-input text-field"))
  type(waitForObject(":Address Book - Add.emailText_text-input text-field"), email)
  mouseClick(waitForObject(":Address Book - Add.phoneText_text-input text-field"))
  type(waitForObject(":Address Book - Add.phoneText_text-input text-field"), phone)
  mouseClick(waitForObject(":Address Book - Add._OK_button"))
  context.userData = Hash.new
  context.userData[:forename] = forename
  context.userData[:surname] = surname
end
Tcl
When "I add a new person '|word|','|word|','|any|','|integer|' to address book" {context forename surname email phone} {
    invoke mouseClick [waitForObject ":editAddButton_button"]
    invoke type [waitForObject ":Address Book - Add.forenameText_text-input text-field"] $forename
    invoke mouseClick [waitForObject ":Address Book - Add.surnameText_text-input text-field"]
    invoke type [waitForObject ":Address Book - Add.surnameText_text-input text-field"] $surname
    invoke mouseClick [waitForObject ":Address Book - Add.emailText_text-input text-field"]
    invoke type [waitForObject ":Address Book - Add.emailText_text-input text-field"] $email
    invoke mouseClick [waitForObject ":Address Book - Add.phoneText_text-input text-field"]
    invoke type [waitForObject ":Address Book - Add.phoneText_text-input text-field"] $phone
    invoke mouseClick [waitForObject ":Address Book - Add._OK_button"]
    invoke clickButton [waitForObject ":Address Book - Unnamed.Add_QToolButton"]
    $context userData [dict create forename $forename surname $surname]
}

All data stored in context.userData can be accessed in all Steps and Hooks in all Scenarios of the given Feature. Finally, we need to implement the Step Then previously entered forename and lastname shall be at the top.

Python
@Then("previously entered forename and surname shall be at the top")
def step(context):
    test.compare(waitForObjectItem(':Address Book - Unnamed.itemTbl_table-view', '0/0').text, context.userData['forename'], "forename")
    test.compare(waitForObjectItem(':Address Book - Unnamed.itemTbl_table-view', '0/1').text, context.userData['lastname'], "lastname")

JavaScript
Then("previously entered forename and surname shall be at the top", function(context){
    test.compare(waitForObjectItem(':Address Book - Unnamed.itemTbl_table-view', '0/0').text, context.userData['forename'], "forename");
    test.compare(waitForObjectItem(':Address Book - Unnamed.itemTbl_table-view', '0/1').text, context.userData['lastname'], "lastname");
});
Perl
Then("previously entered forename and surname shall be at the top", sub {
    my $context = shift;
    test::compare(waitForObjectItem(':Address Book - Unnamed.itemTbl_table-view', '0/0')->text, $context->{userData}{'forename'}, "forename?");
    test::compare(waitForObjectItem(':Address Book - Unnamed.itemTbl_table-view', '0/1')->text, $context->{userData}{'surname'}, "surname?");
});
Ruby
Then("previously entered forename and surname shall be at the top") do |context|
  Test.compare(waitForObject(":File.0_0_QModelIndex").text, context.userData[:forename], "forename?")
  Test.compare(waitForObject(":File.0_1_QModelIndex").text, context.userData[:surname], "surname?")
end

Tcl
Then "previously entered forename and surname shall be at the top" {context} {
    test compare [property get [waitForObjectItem ":Address Book - Unnamed.itemTbl_table-view" "0/0"] text] [dict get [$context userData] forename]
    test compare [property get [waitForObjectItem ":Address Book - Unnamed.itemTbl_table-view" "0/1"] text] [dict get [$context userData] surname]
}
4.4.2.3.8. Scenario Outline

Assume our Feature contains the following two Scenarios:

Scenario: State after adding one entry
    Given addressbook application is running
    When I create a new addressbook
    And I add a new person 'John','Doe','john@m.com','500600700' to address book
    Then "1" entries should be present

Scenario: State after adding one entry
    Given addressbook application is running
    When I create a new addressbook
    And I add a new person 'Bob','Koo','bob@m.com','500600800' to address book
    Then "1" entries should be present

As we can see, those Scenarios perform the same actions using different test data. The same can be achieved by using a Scenario Outline (a Scenario template with placeholders) and Examples (a table with parameters).

Scenario Outline: Adding single entries multiple time
    Given addressbook application is running
    When I create a new addressbook
    And I add a new person '<forename>','<lastname>','<email>','<phone>' to address book
    Then '1' entries should be present
    Examples:
        | forename | lastname | email       | phone     |
        | John     | Doe      | john@m.com  | 500600700 |
        | Bob      | Koo      | bob@m.com   | 500600800 |

Please note that the OnScenarioEnd hook will be executed at the end of each loop iteration in a Scenario Outline.

4.4.2.4. Test execution

In the Squish IDE, users can execute all Scenarios in a Feature, or execute only one selected Scenario. In order to execute all Scenarios, the proper Test Case has to be executed by clicking on the Play button in the Test Suites view.

Execute all Scenarios from Feature

In order to execute only one Scenario, you need to open the Feature file, right-click on the given Scenario and choose Run Scenario. An alternative approach is to click on the Play button next to the respective Scenario in the Scenarios tab in Test Case Resources.

Execute one Scenario from Feature

After a Scenario is executed, the Feature file is colored according to the execution results. More detailed information (like logs) can be found in the Test Results View.

Execution results in Feature file

4.4.2.5. Test debugging

Squish offers the possibility to pause an execution of a Test Case at any point in order to check script variables, spy application objects or run custom code in the Squish script console. To do this, a breakpoint has to be placed before starting the execution, either in the Feature file at any line containing a Step or at any line of executed code (i.e. in middle of step definition code).

Breakpoint in Feature file

After the breakpoint is reached, you can inspect all application objects and their properties. If a breakpoint is placed at a Step definition or a hook is reached, then you can additionally add Verification Points or record code snippets.

4.4.2.6. Re-using Step definitions

BDD test maintainability can be increased by reusing Step definitions. For example, the following line imports all Step definitions first from the step directories in the Test Case Resources and Test Suite Resources.

Python
collectStepDefinitions('./steps', '../shared/steps')
JavaScript
collectStepDefinitions('./steps', '../shared/steps');
Perl
use Squish::BDD;
collectStepDefinitions("./steps", "../shared/steps");
Ruby
include Squish::BDD
collectStepDefinitions "./steps", "../shared/steps"
Tcl
source [findFile "scripts" "tcl/bdd.tcl"]
Squish::BDD::collectStepDefinitions "./steps" "../shared/steps"

If the same Step definition is provided in multiple directories, then the first Step definition occurrence is used. Hence in above example, the definition from the Test Case Resources will be used. If no definition is found in that directory, the definition from the Test Suite Resources will be used.

4.4.3. Tutorial: Migration of existing tests to BDD

This chapter is aimed for users that have existing standard Squish tests and who would like to introduce Behavior Driven Testing. The first section describes how to keep the existing tests and just create new tests with the BDD approach. The second section describes how to convert existing standard tests to BDD tests.

4.4.3.1. Extend existing tests to BDD

The first option is to keep any existing Squish standard tests and extend them by adding new BDD tests. It's possible to have a Test Suite containing both standard Test Cases and BDD Test Cases. Simply open existing Test Suite with standard Test Cases and choose "New BDD Test Case" option from drop down list.

Creating new BDD Test Case

Assuming your existing standard Test Cases make use of a library and you are calling hared functions to interact with the AUT, those functions can still be used in both, existing standard Test Cases and newly created BDD Test Cases. In the example below, a function is used in multiple standard Test Cases:

Python
def createNewAddressBook():
    mouseClick(waitForObject(":fileNewButton_button"))
JavaScript
function createNewAddressBook(){
    mouseClick(waitForObject(":editAddButton_button"));
}
Perl
sub createNewAddressBook{
    mouseClick(waitForObject(":editAddButton_button"));
}
Ruby
def createNewAddressBook
  mouseClick(waitForObject(":editAddButton_button"))
end
Tcl
proc createNewAddressBook {} {
    invoke mouseClick [waitForObject ":editAddButton_button"]
}

New BDD Test Cases can easily use the same function:

Python
@When("I create a new addressbook")
def step(context):
    createNewAddressBook()
JavaScript
When("I create a new addressbook", function(context){
    createNewAddressBook()
});
Perl
When("I create a new addressbook", sub {
    createNewAddressBook();
});
Ruby
When("I create a new addressbook") do |context|
  createNewAddressBook
end
Tcl
When "I create a new addressbook" {context} {
	createNewAddressBook
}

4.4.3.2. Convert existing tests to BDD

The second option is to convert an existing Test Suite that contains standard Test Cases into behavior driven tests. Since a Test Suite can contain both, standard Test Cases and BDD Test Cases, migration can be done gradually. A Test Suite containing a mix of both Test Case types can be executed and results analyzed without any extra effort required.

The first step is to review all Test Cases of the existing Test Suite and group them by the Feature they test. Each standard Test Case will be transformed into a Scenario, which is a part of a Feature. For example, assume we have 5 standard Test Cases. After review, we realize that those standard Test Cases examine two Features. Therefore, when migration is completed, our Test Suite will contain two BDD Test Cases, each of them containing one Feature. Each Feature will contain multiple Scenarios. In our example the first Feature contains three Scenarios and the second Feature contains two Scenarios.

Conversion Chart

At the beginning, open a Test Suite in the Squish IDE that contains standard Squish tests that are planned to be migrated to BDD tests. Next, create a new Test Case by choosing New BDD Test Case option from the context menu. Each BDD Test Case contains a test.feature file that can be filled with maximum one Feature. Next, open the test.feature file to describe the Features using the Gherkin language. Following the syntax from the template, edit the Feature name and optionally provide a short description. Next, analyze which actions and verifications are performed in the standard Test Case that is going to be migrated. This is how an example Test Case for the addressbook application could look like:

Python
def main():
    startApplication("AddressBook.jar")
    test.log("Create new addressbook")
    mouseClick(waitForObject(":fileNewButton_button"))
    test.compare(waitForObjectExists(":Address Book - Unnamed.itemTbl_table-view").items.empty, True)
JavaScript
function main(){
    startApplication("AddressBook.jar");
    test.log("Create new addressbook");
    mouseClick(waitForObject(":fileNewButton_button"));
    test.compare(waitForObjectExists(":Address Book - Unnamed.itemTbl_table-view").items.empty, true, "Addressbok is empty?");
}
Perl
sub main {
    startApplication("AddressBook.jar");
    test::log("Create new addressbook");
    mouseClick(waitForObject(":fileNewButton_button"));
    test::compare(waitForObjectExists(":Address Book - Unnamed.itemTbl_table-view")->items->empty, 1, "Addressbok is empty?");
}
Ruby
def main
  startApplication("AddressBook.jar")
  Test.log("Create new addressbook")
  mouseClick(waitForObject(":fileNewButton_button"))
  Test.compare(waitForObjectExists(":Address Book - Unnamed.itemTbl_table-view").items.empty, true, "Addressbok is empty?")
end
Tcl
proc main {} {
    startApplication "AddressBook.jar"
    test log "Create new addressbook"
    invoke mouseClick [waitForObject ":fileNewButton_button"]
    test compare [property get [property get [waitForObjectExists ":Address Book - Unnamed.itemTbl_table-view"] items] empty] true
}

After analyzing the above standard Test Case we can create the following Scenario and add it to test.feature file:

Scenario: Initial state of created address book
      Given addressbook application is running
      When I create a new addressbook
      Then addressbook should be empty

Next, right-click on the Scenario and choose the option Create Missing Step Implementations from the context menu. This will create a skeleton of Steps definitions:

Python
@Given("addressbook application is running")
def step(context):
    test.warning("TODO implement addressbook application is running")

@When("I create a new addressbook")
def step(context):
    test.warning("TODO implement I create a new addressbook")

@Then("addressbook should be empty")
def step(context):
    test.warning("TODO implement addressbook should be empty")
JavaScript
Given("addressbook application is running", function(context) {
    test.warning("TODO implement addressbook application is running");
});

When("I create a new addressbook", function(context) {
    test.warning("TODO implement I create a new addressbook");
});

Then("addressbook should be empty", function(context) {
    test.warning("TODO implement addressbook should be empty");
});
Perl
Given("addressbook application is running", sub {
    my $context = shift;
    test::warning("TODO implement addressbook application is running");
});

When("I create a new addressbook", sub {
    my $context = shift;
    test::warning("TODO implement I create a new addressbook");
});

Then("addressbook should be empty", sub {
    my $context = shift;
    test::warning("TODO implement addressbook should be empty");
});
Ruby
Given("addressbook application is running") do |context|
  Test.warning "TODO implement addressbook application is running"
end

When("I create a new addressbook") do |context|
  Test.warning "TODO implement I create a new addressbook"
end

Then("addressbook should be empty") do |context|
  Test.warning "TODO implement addressbook should be empty"
end
Tcl
Given "addressbook application is running" {context} {
    test warning "TODO implement addressbook application is running"
}

When "I create a new addressbook" {context} {
    test warning "TODO implement I create a new addressbook"
}

Then "addressbook should be empty" {context} {
    test warning "TODO implement addressbook should be empty"
}

Now we put code snippets from the standard Test Case into respective Step definitions and remove the lines containing test.warning. If your standard Test Cases make use of shared scripts, you can call those functions inside of the Step definition as well. For example, the final result could look like this:

Python
@Given("addressbook application is running")
def step(context):
    startApplication("AddressBook.jar")

@When("I create a new addressbook")
def step(context):
    clickButton(waitForObject(":Address Book.New_QToolButton"))

@Then("addressbook should be empty")
def step(context):
    test.compare(waitForObjectExists(":Address Book - Unnamed.File_QTableWidget").rowCount, 0,  "Addressbok is empty?")
JavaScript
Given("addressbook application is running", function(context) {
    startApplication("AddressBook.jar");
    });

When("I create a new addressbook", function(context) {
        mouseClick(waitForObject(":fileNewButton_button"));
    });

Then("addressbook should be empty", function(context) {
        test.compare(waitForObjectExists(":Address Book - Unnamed.itemTbl_table-view").items.empty, true);
    });
Perl
Given("addressbook application is running", sub {
    my $context = shift;
    startApplication("AddressBook.jar");
});

When("I create a new addressbook", sub {
    my $context = shift;
	clickButton( waitForObject(":Address Book.New_QToolButton") );
});

Then("addressbook should be empty", sub {
    my $context = shift;
    test::compare(waitForObjectExists(":Address Book - Unnamed.File_QTableWidget")->rowCount,0);
});
Ruby
Given("addressbook application is running") do |context|
  startApplication("AddressBook.jar")
end

When("I create a new addressbook") do |context|
  mouseClick(waitForObject(":fileNewButton_button"))
end

Then("addressbook should be empty") do |context|
  Test.compare(waitForObjectExists(":Address Book - Unnamed.itemTbl_table-view").items.empty, true, "Addressbok is empty?")
end
Tcl
Given "addressbook application is running" {context} {
    startApplication "AddressBook.jar"
}

When "I create a new addressbook" {context} {
    invoke mouseClick [waitForObject ":fileNewButton_button"]
}

Then "addressbook should be empty" {context} {
    test compare [property get [property get [waitForObjectExists ":Address Book - Unnamed.itemTbl_table-view"] items] empty] true
}

Note that the test.log("Create new addressbook") got removed while migrating this standard Test Case to BDD Test Case. When the Step I create a new addressbook is executed, the Step name will be logged into Test Results, so the test.log call would have been redundant.

Additionally, when the Test Case execution ends, Squish terminates the AUT. After converting standard Test Cases into Scenarios, we must ensure that the AUT is terminated at the end of Scenario as well. This can be done by implementing an OnScenarioEnd hook.

Python
@OnScenarioEnd
def hook(context):
    currentApplicationContext().detach()
JavaScript
OnScenarioEnd(function(context) {
    currentApplicationContext().detach();
});
Perl
OnScenarioEnd(sub {
    currentApplicationContext()->detach();
});
Ruby
OnScenarioEnd do |context|
  currentApplicationContext().detach()
end
Tcl
OnScenarioEnd { context } {
    applicationContext [currentApplicationContext] detach
}

The above example was simplified for this tutorial. In order to take full advantage of Behavior Driven Testing in Squish, please familiarize yourself with the section Behavior Driven Testing (Section 6.19) in API Reference Manual (Chapter 6).




[7] Each AUT must be registered with the squishserver so that test scripts do not need to include the AUT's path, thus making the tests platform-independent. Another benefit of registering is that AUTs can be tested without the Squish IDE—for example, when doing regression testing.