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. Other functions do not get special treatment, so you can 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 you 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 ApplicationContext startApplication(autName) function as the first statement in the main function. If you need to execute some code before the AUT is started, you can simply insert the code at the start of the main function, before the call to the ApplicationContext startApplication(autName) 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 ApplicationContext startApplication(autName) function: simply check the Automatically start the AUT checkbox in the Test Suite Settings view. If you do this, you will not be able to execute code before the AUT is started by Squish.

In some situations you might wish to do the initialization before the AUT is started, and in fact to start the AUT at a time of your own choosing. This can be done by setting the Application in the Test Suite Settings view 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 the init function. In such cases, it is your responsibility to start the AUT at some point within the init function, using the ApplicationContext startApplication(autName) function.

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 Test Suite Settings view'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 ApplicationContext startApplication(autName) function.

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

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

waitUntilObjectItemReady(item)

waitForObjectItem() can perform additional custom actions if required. This is achieved by defining a callback function called waitUntilObjectItemReady(item) that takes a single argument which it may use or ignore. If a waitUntilObjectItemReady(item) function is defined, whenever waitForObjectItem is called, in addition to its normal actions, it will also call the custom waitUntilObjectItemReady() function, with the item it is about to return as the argument.

waitUntilObjectReady(anObject)

waitForObject can perform additional custom actions if required. This is achieved by defining a callback function called waitUntilObjectReady(anObject) that takes a single argument (an object), which it may use or ignore. If waitUntilObjectReady is defined, whenever the waitForObject is called, in addition to its normal actions, it will also call waitUntilObjectReady(), with the object being waited for as argument. For an example of use, see the AJAX loading example in How to Synchronize Web Page Loading for Testing.