6.1. Tester-Created Special Functions

When Squish executes a test script it treats three functions in a special way. Of these functions, main must be present in every test, while the other two, init and cleanup, are optional. Squish does not specially treat any other functions, so you are free to include as many supporting functions as you need inside your tests, and they can be called by the main function (or by one of the other two special functions) as required.

Since Squish treats functions called main, init, and cleanup, specially, these names should only be used for functions that serve the purposes that Squish expects, as described below.

cleanup();

If we create a function called cleanup, Squish will call this function after the main function has finished (whether it terminated normally or not—even if the main function is aborted, for example, due to an uncaught exception), as the last action taken before the test execution finishes. (Functions for this purpose are often called "teardown" in unit testing frameworks.)

This function might be useful for deleting any files that the AUT has created as part of the test run.

init();

When a test is recorded Squish puts a call to the startApplication function as the first statement in the main function. If we need to execute some code before the AUT is started, we can simply insert the code at the start of the main function, before the call to the startApplication function. This is the recommended approach for executing code before the AUT is started, and makes the use of the init function redundant. (Functions for this purpose are often called "setup" in unit testing frameworks.)

It is possible to have Squish start an AUT without any explicit call to the startApplication function: simply check the Automatically start the AUT checkbox in the Settings view (Section 8.2.16). If you do this, you will not be able to execute code before the AUT is started by Squish.

In some situations we might wish to do our initialization before the AUT is started, and in fact to start the AUT at a time of our own choosing. This can be done by setting the Application in the Settings view (Section 8.2.16) to “<No Application>”. This means that when the test is run, Squish won't be able to start the AUT since it won't know the AUT's name, so Squish will begin by executing our init function. In such cases, it is our responsibility to start the AUT ourselves at some point within the init function, using the startApplication function.

waitUntilObjectReady(object);

waitUntilObjectItemReady(itemOrIndex);

These are callback functions used for object synchronization. See waitUntilObjectReady(anObject) and waitUntilObjectItemReady(item) for details. These functions, when defined in your test script, can be used to generally slow things down while interacting with certain AUT objects or items.

main();

You must create a function called main in every test script. (If you record a test, Squish will automatically record it into a function called main.) When Squish is told to run a test, if the Settings view (Section 8.2.16)'s Automatically start the AUT checkbox is unchecked (the default), Squish will begin by executing the test's main function. For recorded tests that haven't been hand-edited, the first statement in the main function is a call to the startApplication function.

In many cases creating a main function, possibly with some supporting functions, is perfectly sufficient. But in some situations we may want to run some separate initialization, or cleanup, or both. For initialization, we can insert the code we want directly in main just before the call to the startApplication function; or we can create an initializing function (not called init!) and put a call to it in main just before the call to the startApplication function. For cleanup, we can define a function called cleanup which Squish will call when the AUT terminates (whether normally or not).

If the Settings view (Section 8.2.16)'s Automatically start the AUT checkbox is checked, Squish will begin by starting the AUT (unless the Settings view (Section 8.2.16)'s Application is set to “<No Application>”), then our init function (which should exist—and which should start the AUT with a call to the startApplication function if Application is set to “<No Application>”) is called, and once the AUT is running, Squish will call the main function.