Squish objects blend in seamlessly with the scripting language's native objects. This means that you can use standard language features to construct objects of the wrapped types, invoke member functions, and get, set, and iterate over properties on these objects.

Here are some simple examples; many more examples are shown in the User Guide (Chapter 17).

# create an object of type QPoint
point = QPoint(10, 20)

# read a widget's width property
width = widget.width

# set widget's y-coordinate property
widget.y = 240

# call a member function
widget.setWindowTitle("My Widget")

# call a static function
QApplication.setOverrideCursor(Qt.WaitCursor)

// create an object of type QPoint
var point = new QPoint(10, 20);

// read a widget's width property
var width = widget.width;

// set widget's y-coordinate property
widget.y = 240;

// call a member function
widget.setWindowTitle("My Widget");

// call a static function
QApplication.setOverrideCursor(Qt.WaitCursor);

# create an object of type QPoint
my $point = new QPoint(10, 20);

# read a widget's width property
my $width = widget->width;

# set widget's y-coordinate property
$widget->y(240);

# call a member function
$widget->setWindowTitle("My Widget");

# call a static function
QApplication::setOverrideCursor(Qt::WaitCursor);

# create an object of type QPoint
point = QPoint.new(10, 20)

# read a widget's width property
width = widget.width

# set widget's y-coordinate property
widget.y = 240

# call a member function
widget.setWindowTitle("My Widget")

# call a static function
QApplication.setOverrideCursor(Qt::WAIT_CURSOR)

# create an object of type QPoint
set point [construct QPoint 10 20]

# read a widget's width property
set width [property get $widget width]

# set widget's y-coordinate property
property set $widget y 240

# call a member function
invoke $widget setWindowTitle "My Widget"

# call a static function
invoke QApplication setOverrideCursor [enum Qt WaitCursor]

For Tcl we must use the enum function to get enum values. (See Tcl Notes (Section 18.15).)

The function names in the scripting language API use the following convention: each colon (:) in the selector name is replaced by an underscore (_). So, for example, the +stringWithCString:encoding: selector becomes the script function stringWithCString_encoding_ (note the underscore at the end of the function).

Here are some examples to illustrate the usage.

# create an object of type NSString and initialize it with a value
s = NSString.stringWithUTF8String_("Ambient")

# read an object's intValue property
n = acontrol.intValue

# set an object's intValue property
acontrol.intValue = 33

# call an instance method
s.characterAtIndex_(1)

# call a class method
s = NSString.stringWithCString_encoding_("Zenith", 4)

// create an object of type NSString and initialize it with a value
var s = NSString.stringWithUTF8String_("Ambient");

// read an object's intValue property
var n = acontrol.intValue;

// set an object's intValue property
acontrol.intValue = 33;

// call an instance method
s.characterAtIndex_(1);

// call a class method
s = NSString.stringWithCString_encoding_("Zenith", 4);

# create an object of type NSString and initialize it with a value
my $s = NSString::stringWithUTF8String_("Ambient");

# read an object's intValue property
my $n = $acontrol->intValue;

# set an object's intValue property
$acontrol->intValue(33);

# call an instance method
$s->characterAtIndex_(1);

# call a class method
$s = NSString::stringWithCString_encoding_("Zenith", 4);

# create an object of type NSString and initialize it with a value
s = NSString.stringWithUTF8String_("Ambient");

# read an object's intValue property
n = acontrol.intValue

# set an object's intValue property
acontrol.intValue = 33

# call an instance method
s.characterAtIndex_(1)

# call a class method
s = NSString.stringWithCString_encoding_("Zenith", 4)

# create an object of type NSString and initialize it with a value
set s [invoke NSString stringWithUTF8String_ "Ambient"]

# read an object's intValue property
set n [property get $acontrol intValue]

# set an object's intValue property
property set $acontrol intValue 33

# call an instance method
invoke $s characterAtIndex_ 1

# call a class method
set s [invoke NSString stringWithCString_encoding_ "Zenith" 4]

This function finds and returns (a reference to) the object identified by the symbolic or real (multi-property) name objectName or raises a LookupError exception if no such object can be found. This function is best used for non-visible objects. For visible objects it is much better to use the waitForObject function instead.

This function takes an object reference (as returned by the findObject function or by the waitForObject function), and returns a list of the object's child objects. The return type is scripting language-specific, e.g., a tuple in Python, and an array in the other languages. Examples are given below.

obj = waitForObject(":MyWidget")
children = object.children(obj)
# iterate over tuple
for child in children:
    ...

var obj = waitForObject(":MyWidget");
var children = object.children(obj);
// iterate over array
for (var i = 0; i < children.length; ++i) {
    var child = children[i];
    ...
}

my $obj = waitForObject(":MyWidget");
my @children = object::children($obj);
# iterate over array
foreach $child (@children) {
    ...
}

obj = waitForObject(":MyWidget")
children = Squish::Object.children(obj)
# iterate over array
for child in children
    # ...
end

set obj [waitForObject ":MyWidget"]
set children [object children $obj]
foreach child $children {
    ...
}

This function converts the given object to an object of the type specified by the typeName string. (A suitable object can be obtained using the waitForObject function or the findObject function.) For example:

font = object.convertTo(variant, "QFont")

In this example, if variant is a variable of type QVariant and it holds a QFont object, the underlying QFont object will be returned. If the object is invalid or null or if the typeName is unrecognized or if the conversion isn't possible (e.g., QFont to int), a catchable exception will be raised.

This function can also do other kinds of conversions, e.g., int to String. See also, the cast function which can be used for downcasting (which object.convertTo cannot do).

This function creates a null pointer or object with the specified type as type.

widget = object.createNull(QWidget)

This function returns a true value if the object with the symbolic or real (multi-property) name objectName exists; otherwise it returns a false value.

If you know that a particular object exists and you just want to access it (for example, to examine its properties or to perform an action on it or with it), then use the waitForObject function if the object is visible; or use the findObject function if the object is hidden.

This function takes an object reference (as returned by the findObject function or by the waitForObject function), and returns the parent object.

If the given object has no parent, the function returns a null value - the exact type of which depending on the scripting language (i.e. None in Python, null in JavaScript, nil in Ruby etc.).

This function takes an object reference (as returned by the findObject function or by the waitForObject function), and returns a key–value map that holds all of the object's properties. The keys are property names and the values are the property values. The return type is scripting language-specific, e.g., a Python dict, a JavaScript array, or a Perl hash. Examples are given below.

For Tcl the data is written to an array whose name must be given as an additional parameter. The same array should not be used in a second or subsequent call unless you call array unset on it before each use.

widget = waitForObject(":MyWidget")
properties = object.properties(widget)
# Best to use .iteritems(), .iterkeys(), or .itervalues() in Python 2
for name, value in properties.iteritems():
    test.log("%s = %s" % (name, value))

var widget = waitForObject(":MyWidget");
var properties = object.properties(widget);
for (var name in properties) {
    test.log(name + " = " + properties[name]);
}

my $widget = waitForObject(":MyWidget");
my %properties = object::properties($widget);
while (($name, $value) = each(%properties)) {
    test::log("$name = $value");
}

widget = waitForObject(":MyWidget")
properties = Squish::Object.properties(widget)
properties.each {|key, value| Test.log("#{key} = #{value}")}

set widget [waitForObject ":MyWidget"]
object properties $widget properties
foreach key [array names properties] {
    set value [toString $properties($key)]
    test log "$key = $value"
}

This function returns a list of all of the AUT's top-level objects. The return type is scripting language-specific, e.g., a tuple in Python, and an array in the other languages. Examples are given below.

topLevels = object.topLevelObjects()
# iterate over tuple
for obj in topLevels:
    children = object.children(obj)
    ...

var topLevels = object.topLevelObjects();
// iterate over array
for (var i = 0; i < topLevels.length; ++i) {
    var obj = topLevels[i];
    var children = object.children(obj)
    ...
}

my @topLevels = object::topLevelObjects();
# iterate over array
foreach $obj (@topLevels) {
    my @children = object::children(obj)
    ...
}

topLevels = Squish::Object.topLevelObjects()
# iterate over array
for obj in topLevels
    children = Squish::Object.children(obj)
    #...
end

set topLevels [object topLevelObjects]
foreach obj $topLevels {
    set children [object children $obj]
    ...
}

The condition is a piece of code to evaluate, normally passed as a string, and that is expected to return a Boolean value. The waitFor function loops one or more times, and on each iteration it executes the condition code and reads its return value. After each execution, if the condition code's return value is true, waitFor will finish and return true. Otherwise, the waitFor function will perform another iteration, that is, execute the condition code again, and again check its return value, repeating endlessly—or until the condition code returns true, in which case waitFor will finish and return true.

This function is designed as a quick and easy way to poll for a condition in the AUT, where each condition execution takes a very short time (typically a fraction of a second), and always returns true or false. This is useful if you want to synchronize your script execution to a certain state in the AUT.

See How to Create and Use Synchronization Points (Section 17.11) for examples of use.

The condition is a piece of code to evaluate, normally passed as a string, and that is expected to return a Boolean value. The waitFor function loops one or more times, and on each iteration it executes the condition code and reads its return value. After each execution, if the condition code's return value is true, waitFor will finish and return true. If the condition code returned false, the waitFor function checks to see if the time it has been running has exceeded the timeoutMSec—if it has, waitFor finishes and returns false; otherwise it does another iteration, starting with another execution of the condition code.

This function is designed as a quick and easy way to poll for a condition in the AUT, where each condition execution takes a very short time (typically a fraction of a second), and always returns true or false. This is useful if you want to synchronize your script execution to a certain state in the AUT.

See How to Create and Use Synchronization Points (Section 17.11) for examples of use.

Waits for a new application to start up, which Squish then hooks into. If the hooking succeeds it returns an ApplicationContext object representing the application that was started. This is used by Squish for test scripts which access multiple applications which are started by the AUT. (See also, Application Context (Section 18.3.11).)

Waits until the objectOrName object is accessible (i.e., it exists and is visible and enabled). It returns a reference to the object if successful or raises a (catchable) LookupError exception on failure, i.e., if the function times out. The function waits for a maximum of 20 seconds (20 000 milliseconds) or if the optional timeoutMSec parameter is used, that many milliseconds. This function is useful if you want to synchronize your script execution.

This function is only suitable for objects that are (or become) visible; for non-visible objects use the findObject function instead. And if you only want to know if an object exists, use the object.exists function.

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

Waits until the objectOrName object is accessible (i.e., it exists and is visible and enabled), and contains an item that is identified by the itemIdentifier and that is itself accessible. This function is typically used to access items inside containers such as lists, tables, and trees. For example, the itemIdentifier for a table is a string with the format row/column, e.g., "4/21".

This is an extension to the waitForObject function for those widgets that contain their own items. On success, for Java, Qt, and Windows, this function returns a reference to the item (and, of course, items are objects, so the returned reference can be used with any other Squish function that accepts an object as argument). For the other Squish versions (e.g., Web), it returns a reference to the object identified by the objectOrName (not the item!). In all cases, the function raises a (catchable) LookupError exception on failure, i.e., if it times out. The function waits for a maximum of 20 seconds (20 000 milliseconds) or if the optional timeoutMSec parameter is used, that many milliseconds.

This function performs a key press of the specified key keyboard key. This key argument is either a single character or a special key which is written between angle brackets (<>). E.g. "<Ctrl>" for the control key, "<Alt>" for the alt key, "<Shift>", "<Return>" for the enter key and "<Tab>" for the tab key.

This function performs a key release of the specified key keyboard key. This key argument is either a single character or a special key which is written between angle brackets (<>), see keyPress.

This function moves the mouse to position x and y relative to the top-left of the objectOrName widget if one is specified, or relative to the current screen otherwise.

This function is useful if you want to trigger events that need the mouse to be at a particular position. For example, tooltips normally only appear when the mouse is over a certain area.

There are toolkit-specific versions of this function that may have different arguments: mouseMove (Java) and mouseMove (Mac OS X).

This function performs a mouse press. All the parameters are optional excepting that either both or neither of the coordinates must be present.

If x and y coordinates are given, the press takes place at those coordinates, either relative to the objectOrName object if one is specified, or relative to the current screen otherwise. If no coordinates are given the press takes place on the middle of the objectOrName object if one is specified, or wherever the mouse happens to be otherwise.

By default MouseButton.LeftButton is used, but this can be changed by specifying the optional mouseButton argument. Similarly a default modifier state of no modifiers is used, but this can be changed by specifying the modifierState argument. See Squish API Function Parameters for which values are valid for the mouseButton argument and for the modifierState argument.

	Note
	When executing tests on Windows systems, MouseButton.PrimaryButton is used by default instead of MouseButton.LeftButton. This means that Squish will perform a click with the right mouse button in case Windows was configured to have swapped mouse buttons.

There is a toolkit-specific version of this function that may have different arguments: mousePress (Windows).

This function performs a mouse release. All the parameters are optional excepting that either both or neither of the coordinates must be present.

If x and y coordinates are given, the release takes place at those coordinates, either relative to the objectOrName object if one is specified, or relative to the current screen otherwise. If no coordinates are given the release takes place on the middle of the objectOrName object if one is specified, or wherever the mouse happens to be otherwise.

By default MouseButton.LeftButton is used, but this can be changed by specifying the optional mouseButton argument. Similarly a default modifier state of no modifiers is used, but this can be changed by specifying the modifierState argument. See Squish API Function Parameters for which values are valid for the mouseButton argument and for the modifierState argument.

	Note
	When executing tests on Windows systems, MouseButton.PrimaryButton is used by default instead of MouseButton.LeftButton. This means that Squish will perform a click with the right mouse button in case Windows was configured to have swapped mouse buttons.

There is a toolkit-specific version of this function that may have different arguments: mouseRelease (Windows).

This function returns the object's class name as a string. (A suitable object can be obtained using the waitForObject function or the findObject function.)

	Python-specific
	This function is only available to Python test scripts; for other script languages use the typeName function.

This function returns a true value if the object is null (e.g., a null-pointer in C++); otherwise it returns a false value. (A suitable object can be obtained using the waitForObject function or the findObject function.)

This function returns the object's class name as a string. (A suitable object can be obtained using the waitForObject function or the findObject function.) For objects that are created in test scripts, this is their actual type name. For widgets and other application objects, Squish tries to return the correct type name, and if that isn't possible, returns "Object", the name of Squish's generic object type, instead.

JavaScript, Perl, Ruby, and Tcl scripts should always return the correct type name. Python scripts usually return "Object" for application objects, but Squish's API for Python includes the className function, which returns the correct class name of the object it is given, whether that object is created in a test script or is an application object.

Casts the object to the given type and returns a reference to that object, or to a new copy of the object if the object is of an immutable type. (A suitable object can be obtained using the waitForObject function or the findObject function.) The desired type can be specified either by name (as a string) or by using a type object.

For mutable objects the object itself is modified.

If the cast fails the object reference is returned unchanged.

	Python-specific: Type Conversions
	Python programmers should be aware that integer type conversions such as int(x) will not work; use x = cast(x, int) or x = cast(x, "int") instead. Or if you prefer, do import __builtin__, and then use x = __builtin__.int(x). (This is necessary because Squish implements its own int object in Python.)

This function makes it possible to downcast (e.g., from QTextEdit to QWidget). See Event Handlers for Specific Objects (Section 17.10.3) for an example of use. See also the object.convertTo function.

The compare, verify, and exception functions are used to record the results of tests applied to a running AUT in Squish's test log as passes or fails. The other functions can be used to programmatically record any kind of test results in the test log. (See also, the Verification Point Creator view (Section 20.2.19) and How to Create and Use Verification Points (Section 17.22).)

This function grabs an image of the screen the AUT is running on and stores it on the computer where the Squish IDE (or squishrunner) is executing.

If no path is specified the file gets stored in the working directory of the squishrunner process. (The default working directory of squishrunner is the path of the test case that it is currently executing.)

If a relative path is specified it is relative to the working directory of the squishrunner process. (The default working directory of squishrunner is the path of the test case that it is currently executing.)

If an absolute path is specified that path is used as is.

The filename should have a suffix denoting the image format to be used. Here's an example of use that is legal in JavaScript, Python, Ruby, and Perl:

saveDesktopScreenshot("screen.png");

saveDesktopScreenshot "screen.png"

The available formats varies, but will always include at least the following:

This function compares value1 and value2, and if they are equal, a test result of type PASS is added to the test log and this function returns a true value. Otherwise a test result of type FAIL is added to the test log and a false value is returned.

If the optional message parameter (of type string—e.g., a comment, bug number, or test plan reference) is present, it will be added to the test result no matter whether the test passed or failed.

This function excecutes the code passed as a string in code, expecting it to raise an exception. If an exception is raised a test result of type PASS is added to the test log and this function returns a true value. Otherwise a test result of type FAIL is added to the test log and a false value is returned.

If the optional message parameter (of type string—e.g., a comment, bug number, or test plan reference) is present, it will be added to the test result no matter whether the test passed or failed.

This function unconditionally adds a FAIL entry to Squish's test log with the given message string, and with the detail string, if one is given.

This function unconditionally adds a FATAL entry to Squish's test log with the given message string, and with the detail string, if one is given.

This function unconditionally adds a LOG entry to Squish's test log with the given message string, and with the detail string, if one is given.

This function unconditionally adds a PASS entry to Squish's test log with the given message string, and with the detail string, if one is given.

	Python-specific
	Since pass is a reserved word in Python, the Python version of this function is called test.passes.

This function returns the number of results of the given resultCategory of the current test case. The resultCategory must be one of the strings: "errors", "fails", "fatals", "passes", "testcases", "tests", "warnings", "xfails", or "xpasses".

The result counts are only gathered for the currently running test case.

This function evaluates the condition and if it evaluates to a true value (e.g., true or 1), a test result of type PASS is added to the test log. Otherwise a result of type FAIL is added to the test log. In either case the function returns the result of evaluating the condition, (i.e., a true value on PASS and a false value on FAIL).

If the optional message parameter (of type string—e.g., a comment, bug number, or test plan reference) is present, it will be added to the test result whether the test passed or failed.

This function executes the verification point called name. If the verification point references a data set, the record parameter is used to identify the record in the data set that should be used. If the verification point's comparison succeeds, a test result of type PASS is added to the test log and this function returns a true value. Otherwise a result of type FAIL is added to the test log and a false value is returned.

This function unconditionally adds a WARNING entry to Squish's test log with the given message string, and with the detail string, if one is given.

This function is used to handle expected failures in test scripts.

The function compares value1 and value2, and if they are not equal, a test result of type XFAIL (eXpected FAILure) is added to the test log and this function returns a false value. Otherwise a test result of type XPASS (uneXpected PASS) is added to the test log and a true value is returned.

If the optional message parameter (of type string—e.g., a comment, bug number, or test plan reference) is present, it will be added to the test result whether the test passed or failed.

This function is used to test for expected failures in test scripts.

The function evaluates the condition and if it evaluates to a false value (e.g., anything that isn't true or that's non-zero), a test result of type XFAIL (eXpected FAILure) is added to the test log. Otherwise a test result of type XPASS (uneXpected PASS) is added. In either case the function returns the result of evaluating the condition, (i.e., a false value on XFAIL and a true value on XPASS).

If the optional message parameter (of type string—e.g., a comment, bug number, or test plan reference) is present, it will be added to the test result whether the test passed or failed.

Squish can handle tabular data (rows and columns—or in database terminology, records and fields). With respect to Squish's data handling functions, we use the terms “row” and “record” as synonyms, and similarly, “column” and “field”.

Squish can read in test data from .tsv (tab-separated values format), .csv (comma-separated values format), and .xls (Microsoft® Excel™ spreadsheet format—but not .xlsx format) files. In the case of .csv and .tsv files, Squish assumes that they use the Unicode UTF-8 encoding—the same encoding used for all test scripts.

	Data Row Indexing
	In the Squish IDE, the first row of data is used for the headers, with row indexes shown counting from 1. However, the functions listed in this subsection use 0-based indexing, so the first record is at row 0, the second record at row 1, and so on. (And in fact the headers are accessible at row index -1.)

The test data functions are used for data-driven and keyword-driven testing. For examples of data-driven testing see the Tutorials, and for examples of keyword-driven testing see How to Do Keyword-Driven Testing (Section 17.16).

This function returns the name of a file you can write to. If the where parmeter is "shared", the filename will have a path that locates the file in the test suite's shared test data directory (test_suite/shared/testdata/filename), and if the where is "local" the filename will have a path that locates the file in the test suite's, test case's test data directory (test_suite/tst_case/testdata/filename).

This function is designed to be used when you are running a script in a “learning” mode and want to create test data dynamically.

This function (along with the testData.fieldNames and testData.field functions), is used for data-driven and keyword-driven testing.

The testData.dataset function returns a dataset object that refers to an array or tuple of records. The data is retrieved from the file specified by the filename—providing the data is in one of the file formats that Squish recognizes.

The normal practice is for the filename to be given without a path (e.g., mydata.csv). In this case, Squish first tries to find the file in the test case's data (i.e., in the test case's testdata folder if it has one). If that fails, Squish next tries looking in the test suite's shared data folder (i.e., in the test suite's shared/testdata folder). If the file isn't found (or is found but cannot be read or understood), Squish throws a catchable exception. If the filename is specified with a path (e.g., C:\mydata\mydata.csv), then Squish tries to read that specific file and throws a catchable exception if the file doesn't exist or isn't in a format that Squish can understand.

The field names and field values can be retrieved using the functions described below.

This function returns a true value if a file called filename exists in the AUT's current working directory; otherwise it returns a false value.

This function returns the value of the field specified by the given fieldName string or the given fieldIndex integer, taken from the specified record (i.e., from a particular row from the dataset returned by the testData.dataset function).

See Example 17.14, “Extracts from the Shared Scripts” in the User's Guide for usage examples—in particular the compareTableWithDataFile function.

This function returns an array or tuple of field names for the specified record (i.e., from a particular row from the dataset returned by the testData.dataset function).

This function copies the file called filename from the AUT's current working directory to the test case's directory.

This function removes the file called filename from the AUT's current working directory.

If the filename is specified without a path, this function copies the test data file called filename from the test case's directory into the AUT's current working directory. If the filename is specified with a path, this function copies the specified file into the AUT's current working directory. When the AUT is terminated the copied test data file is automatically deleted.

Note that if multiple AUTs are involved—for example, if one AUT starts another program—the deletion occurs when the program in whose context the call to the testData.put function was made is terminated.

For information about manipulating the Object Map using the Squish IDE see the Object Map view (Section 20.2.9). For more about Object Maps in use see Object Map (Section 19.10).

This function adds the given object to the object map. (A suitable object can be obtained using the waitForObject function or the findObject function.)

This function loads an object map from the given filename and uses it to replace the current object map. If the file does not exist, an exception is raised and the current object map is left unchanged.

This function returns the real (multi-property) name for the given object, or for the object with the given symbolicName.

This function tries to return the symbolic name for the specified object or real name from the object map.

If the objectOrRealName is a real name, and it does not match any existing object, it will simply be returned; no error will be thrown.

If the objectOrRealName is an invalid real name it will simply be returned; no error will be thrown.

If the objectOrRealName is a reference to an object and the object map does not contain an object name that matches this object, then a real name for this object will be returned.

This function returns an array (a tuple in Python) containing all the mapped symbolic names. The returned names are in an arbitrary order.

Every AUT that is started by Squish has a corresponding ApplicationContext object. These objects provide the following properties and functions. (For examples of use see How to Use ApplicationContext Objects (Section 17.12.3).)

Here are some quick links to the Application Context-related functions, methods and properties:

This function returns a handle to the application context object with the given name.

	Tcl-specific
	When using the Tcl scripting language, this function is called getApplicationContext.

This read-only property holds the command line that the application was started with.

This read-only property holds the application's current working directory.

This function returns the value of the AUT process environment variable called name or an empty string if no such environment variable exists.

This read-only property holds the host the AUT is running on.

This function returns a false value if the application responds before the timeout (in seconds) expired; otherwise it returns a true value.

This read-only property holds true if the application is still running; otherwise it holds false.

This function detaches from a previously started (or attached) application.

This function makes it possible to force terminating an application which was previously started with startApplication, or to re-attach to an application to which the test already attached using attachToApplication.

After detaching from an application one should not access any of its objects anymore. (This would typically be done by using object references which had been retrieved before detaching.)

If the application context of applicationContext.detach is the current application context, then the current application context will be changed to another (random) application context. So one must make sure to make the desired application context the current one before proceeding. (See applicationContextList, currentApplicationContext and setApplicationContext.)

This read-only property holds the application's name.

This read-only property holds the application's process identifier.

This read-only property holds the port used by the squishserver that started the AUT.

This function reads and returns everything which the application has written to the stderr stream since the last call to readStderr, or since the application started if there has been no previous call.

This function reads and returns everything which the application has written to the stdout stream since the last call to readStdout, or since the application started if there has been no previous call.

This read-only property holds the time when the application was started. (The property's data type varies depending on the scripting language used.)

This read-only property holds the amount of time that the AUT process has been scheduled in user and kernel modes measured in milliseconds.

This read-only property holds the number of bytes of memory used by the application. For Windows operating systems the returning value corresponds to the current working set size (in bytes) of the AUT process. For Linux operating systems the value corresponds to the virtual memory (in KB) currently used by the AUT process. For Mac OS it is the current resident set size (in KB).

This function returns an array (a tuple in Python) of handles to all the existing application contexts.

This function causes Squish to attach to the application called autName and returns a handle to its application context. The autName must be the name of an application that has been registered with the squishserver as an attachable AUT. (See Configuring squishserver (Section 19.4.2.3).) No command line options can be given since the application should already be running.

This function has the same optional arguments as the startApplication function. If the host and port are specified they refer to the machine where the squishserver is running—and this is not the host and port where the attachable AUT is running. The AUT's host and port can be specified when the AUT is registered with the squishserver (see Register the AUT (Section 19.8.3)).

The parameter timeoutSecs is being used after the socket connection to the attachable AUT has been established. If the attachable AUT requires more seconds than specified to respond to the attaching attempt an error will be thrown. If no timeoutSecs is specified the squishserver's (Maximum Startup Time) default is used—this is 20 seconds, unless it has been changed; see Squish Server Settings dialog (Section 20.3.16).

If attaching fails (e.g,. because the AUT is not running), this function throws an exception that can be caught in the test script. If the exception is not caught an error will be logged as an error in the test script's execution.

See Attaching to Running Applications (Section 19.8) for more information.

This function returns a handle to the current application context.

This function returns a handle to the default application context. It is more reliable to use the currentApplicationContext function instead.

This function can be used to change the current application context. The contextHandle object is a handle to an application context that has been returned by the any of the functions that return one—applicationContextList, attachToApplication, defaultApplicationContext, currentApplicationContext, and startApplication. If the argument is omitted the default context is activated.

If the contextHandle object is invalid—for example, if it refers to an application that has crashed—a catchable exception (TypeError in Python), will be thrown.

This function starts the specified application and returns a handle to its application context. The autName parameter must be the name of an application whose path is already registered with the squishserver. (See Configuring squishserver (Section 19.4.2.3)) In addition to the application name, command line options can be included in the string passed to this function.

Optionally, as second and third parameters a host and port can be specified. If these parameters are used, instead of connecting to the default host and port (as specified in the Squish IDE's settings or on squishrunner's command line), a connection to the squishserver on the specified host and listening to the specified port will be established. This makes it possible to control multiple applications on multiple computers from a single test script.

The fourth parameter, timeoutSecs (an integer number of seconds) can also be specifed. This tells Squish how long it should be prepared to wait for the application to start before throwing an error. If specified, this value overrides squishrunner's default AUT timeout. If not specified the squishserver's default is used—this is 20 seconds, unless it has been changed; see Squish Server Settings dialog (Section 20.3.16).

If you want to specify a timeout, but don't want to change the host or port, you can do so by passing an empty string as the host (which will make Squish use the configured host—localhost by default), and by passing -1 as the port.

For more about how application context objects can be used, see How to Use ApplicationContext Objects (Section 17.12.3). (See also, the waitForApplicationLaunch function.)

Most toolkits' grabWidget function returns an Image object. These objects provide a single method, save.

This method saves the image to a file with the the given filename using a file format deduced from the filename for toolkits where this is supported and using the specified imageFormat otherwise. For example:

widget = waitForObject(objectName)
image = grabWidget(widget)
image.save("C:\\screenshot1.png", "PNG")

var widget = waitForObject(objectName);
var image = grabWidget(widget);
image.save("C:\\screenshot1.png", "PNG");

my $widget = waitForObject($objectName);
my $image = grabWidget($widget);
$image->save("C:\\screenshot1.png", "PNG");

widget = waitForObject(objectName)
image = grabWidget(widget)
image.save("C:\\screenshot1.png", "PNG")

set widget [waitForObject $objectName]
set image [invoke grabWidget $widget]
invoke $image save "C:\\screenshot1.png" "PNG"

This example takes a screenshot of the given object and saves it to the file screenshot1.png in the root directory on Windows, using the PNG (Portable Network Graphics) file format.

The available formats varies, but will always include at least the following:

For iOS testing, only the "JPEG" and "PNG" formats are supported.

See grabWidget [Java], grabWidget [Mac], grabWidget [iOS], grabWidget [Tk], grabWidget [Web], and grabWidget [Win].

The global squishinfo object provides the following properties.

This read-only property holds Squish's major version number as a single integer (e.g., 4).

This read-only property holds Squish's minor version number as a single integer (e.g., 0).

This read-only property holds Squish's patch level version number as a single integer (e.g., 1).

This read-only property holds the path to the results directory.

This read-only property holds the current test's currently active settings group.

This read-only property holds the current test case's path.

This read-only property holds Squish's complete version number (major/minor/patch/release) as a single integer (see explanation further on).

This read-only property holds Squish's version number as a human-readable string (e.g., "4.0.1-final").

The squishinfo.version number is a unique number that represents the complete Squish version number (major/minor/patch/release). The number is composed of four bytes by representing each part as a one-byte hexadecimal number. So Squish 4.0.1-final would be represented by the number 0x040001FF where the 0x04 is the major version (4), the 0x00 the minor version (0), the 0x01 the patch version (1), and the 0xFF the release (final). The release is encoded using one of three hexadecimal numbers: 0xAA is used for “alpha”, 0xBB for “beta”, and 0xFF for “final”.

Using a hexadecimal format version number makes it easy to write version-specific code in test scripts. Here's an example where we want some code executed only for Squish 4.0.0-final or later (for example, to take advantage of some Squish 4-specific functionality):

if squishinfo.version >= 0x040000FF:
   # code meant for Squish version 4.0.0-final or higher

if (squishinfo.version >= 0x040000FF) {
   // code meant for Squish version 4.0.0-final or higher
}

if (squishinfo->version >= 0x040000FF) {
   # code meant for Squish version 4.0.0-final or higher
}

if Squishinfo.version >= 0x040000FF
   # code meant for Squish version 4.0.0-final or higher
end

if {[squishinfo version] >= 0x040000FF} {
   # code meant for Squish version 4.0.0-final or higher
}

Squish provides several functions for tests which need interaction with a real user during replay. Such interaction includes simple questions for manual verification as well as providing user-input, i.e. for manually driven testing or for taking notes while observing test execution.

testInteraction functions that display a message box return one of the following constant values depending on the button that was pressed by the user:

Any testInteraction function that displays a dialog shows the current testscript filename and line number in its title bar.

Calling any of these functions only works if squishrunner was started with the --interactive option (See also Executing Test Cases (Section 19.4.1.3)). Tests executed from the Squish IDE are always run in interactive mode. Calling any of the testInteraction functions (except for testInteraction.isAvailable()) in non-interactive mode will result in a script error causing script execution to abort.

Shows a message box with message as message text, an information icon and an OK button.

Shows a dialog with message as message text and a line edit for user input. The returned string contains the contents of the line edit or an empty string if the user canceled the dialog.

This function returns whether the test script is executed by a squishrunner that was started including the --interactive option. This allows creating tests that only show interactive dialogs on request but also run in a non-interactive way.

Shows a message box with message as message text, a questionmark-icon, a Yes button and a No button.

Shows a message box with message as message text, a warning-icon and an OK button.

Squish provides a global testSettings object whose properties and methods can be set to control certain aspects of test execution.

This function returns the list of wrappers associated with the specified application. (See also testSettings.setWrappersForApplication.)

If this property is true every test failure will cause Squish to take a screenshot of the desktop when the failure occurred; by default this property is false and screenshots of failures are not automatically taken

For example, let's assume that we ocassionally experience test failures when verifying the state of a specific widget in our nightly tests. We cannot explain the cause of the problem but suspect that the overall state of our application's GUI is broken due to as yet unknown external factors. To provide the developers with useful information via a visual inspection we enable automatic screenshot capturing—but for only for the test that is causing concern:

testSettings.logScreenshotOnFail = True
# ... perform test ...
testSettings.logScreenshotOnFail = False

testSettings.logScreenshotOnFail = true;
// ... perform test ...
testSettings.logScreenshotOnFail = false;

testSettings->logScreenshotOnFail(1);
# ... perform test ...
testSettings->logScreenshotOnFail(0);

TestSettings.logScreenshotOnFail = true
# ... perform test ...
TestSettings.logScreenshotOnFail = false

testSettings set logScreenshotOnFail 1
# ... perform test ...
testSettings set logScreenshotOnFail 0

If this property is true every test error will cause Squish to take a screenshot of the desktop when the error occurred; by default this property is false and screenshots of errors are not automatically taken

If this property is true every test pass will cause Squish to take a screenshot of the desktop. By default this property is false and this screenshots are not automatically taken for test passes.

This function associates a list of wrappers with the specified application. The list must include at least one of the main toolkit wrappers. Optionally, it may include application-specific wrappers (for those Squish editions that support them). The main toolkit wrappers are:

These main toolkit wrapper names correspond directly to the Toolkit: field in the Test Suite Configuration view of the Squish IDE.

Note that Squish 4's dynamic wrapper support greatly reduces the need to create and maintain application-specific wrappers.

Here is an example that sets the Qt toolkit wrapper as well as a custom application wrapper, and then starts the AUT:

testSettings.setWrappersForApplication("MyApp", ("Qt", "CanvasWrapper"))
startApplication("MyApp")

testSettings.setWrappersForApplication("MyApp", ["Qt", "CanvasWrapper"]);
startApplication("MyApp");

testSettings->setWrappersForApplication("MyApp", ("Qt", "CanvasWrapper"));
startApplication("MyApp");

TestSettings.setWrappersForApplication("MyApp", ["Qt", "CanvasWrapper"])
startApplication("MyApp")

testSettings setWrappersForApplication MyApp { Qt CanvasWrapper }
startApplication "MyApp"

(See also testSettings.getWrappersForApplication.)

If this property is true Squish will not produce Test Result entries for passing or failing test.vp() calls. In combination with using the (boolean) return value of test.vp(), this can come in handy for custom defined verifications on top of a series of Verification Points.

Here is an example that checks that one of three Screenshot Verification Points passes.

testSettings.silentVerifications = True
for current in ['VP-winxp', 'VP-win2k', 'VP-win7']:
    if test.vp(current):
        test.pass("%s matched" % (current, ))
        break
else:
    test.fail("none of the provided VPs matched")

Squish provides the UiTypes namespace (in languages where namespaces make sense) through which items of generic types can be created.

moonLanding = UiTypes.DateTime(1969, 7, 20)

var moonLanding = new UiTypes.DateTime(1969, 7, 20);

my $moonLanding = UiTypes::DateTime->new(1969, 7, 20);

moonLanding = UiTypes::DateTime.new(1969, 7, 20)

set moonLanding [construct DateTime 1969 7 20]

This function returns the full path of the given filename or raises a LookupError exception if the file cannot be found.

If the where parameter is "scripts", findFile looks for the filename in the test case's scripts directory. If that doesn't contain the file the function next tries the test suite's shared/scripts directory. If that doesn't contain the file the function tries the paths in the paths.ini file (see Squish Initialization Files (Section 19.6)), and if it still isn't found, the function tries all of the directories listed in the SQUISH_SCRIPT_DIR environment variable (if it is defined—see Environment Variables (Section 19.5)). As soon as the file is found the filename with full path is returned; otherwise a catchable LookupError exception is raised.

If the where parameter is "testdata", findFile looks for the filename in the test case's testdata directory. If that doesn't contain the file the function next tries the test suite's shared/testdata directory, and failing that the function tries the test case's directory. As soon as the file is found the filename with full path is returned; otherwise a catchable LookupError exception is raised.

(See also, the source function and the Test Data Functions (Section 18.3.9).)

This function tells Squish to sleep for the specified nominal number of seconds. The seconds argument can be a whole number or a floating-point number. The actual sleep time will depend on the current snoozeFactor. Unless you really do need to force Squish to sleep, it is usually more robust to use the waitForObject function than to use snooze.

The snoozeFactor can be set using the Squish IDE. Click Window|Preferences to invoke the Pref­er­ences dialog (Section 20.3.12), then click the Squish item, and then the Playback item and then set the Snooze Factor value. The snoozeFactor can also be set by using squishrunner's command line options; see Recording a Test Case (Section 19.4.1.4) and Executing a Test Case (Advanced) (Section 19.4.1.5).

Reads and evaluates the contents of filename. Use the scripting language's normal “import” mechanism (such as Python's import or Perl's use) for modules in the language's standard libraries and for third party modules, but use the this source function to parse your own shared script files rather than using the scripting language's import mechanism.

A common use case is to write something like source(findFile("scripts", "common.js")). This uses the findFile function to produce a filename including a path and then evaluates that file's contents as a script. This typically results in additional functions (and even new classes and variables) becoming available to the test script that performs this call.

For Ruby, use the built-in require method instead—inside a function or method. For example, require findFile("scripts", "common.rb")).

(See also, How to Create and Use Shared Data and Shared Scripts (Section 17.23), and the Import Squish Resource dialog (Section 20.3.3) and the New Squish Test Script dialog (Section 20.3.8).)

This function simulates a native mouse click on the currently active window. The x and y parameters are the coordinates where the mouse click must take place in screen coordinates. The button parameter is the mouse button that should be used, and must be one of MouseButton.LeftButton, MouseButton.MiddleButton or MouseButton.RightButton.

	Small caveat
	In theory it is possible for a call to the nativeMouseClick function to go astray. For example, if a window or control unexpectedly pops up over the window at which the mouse click was intended, the mouse click will go to the newly active window or control rather than to the intended one. In practice this is a very rare occurrence.

This function simulates user keyboard input using the operating system's facilities, sending keypresses to the currently active window, i.e., to the window with keyboard focus. On Windows, this can be used to interact with native Windows message boxes, for example. The keyboard input will be sent to whatever widget has the keyboard focus. The input is case-sensitive, so nativeType("R") is different from nativeType("r").

This function can also simulate the input of special keys by using their names and enclosing them in angle brackets (<>), and can simulate combinations of keys by separating each key name with a +. Here are some examples:

nativeType("Hello");
nativeType("<Return>");
nativeType("<Alt+F4>");
nativeType("<Alt+Tab>");
nativeType("<Ctrl+c>");

This is valid in JavaScript, Perl, Python, and Ruby.

invoke nativeType "Hello"
invoke nativeType "<Return>"
invoke nativeType "<Alt+F4>"
invoke nativeType "<Alt+Tab>"
invoke nativeType "<Ctrl+c>"

The nativeType function can accept all the normal alphanumeric characters (which are written literally), as well as the following special keys (which must be enclosed in angle brackets): <Alt>, <Ctrl>, <Shift>, <Escape>, <Return>, <Backspace>, <Tab>, <Pause>, <PageUp>, <PageDown>, <Home>, <End>, <Left>, <Right>, <Up>, <Down>, <Insert>, <Delete>, <Print>, <NumPad0>, <NumPad1>, <NumPad2>, <NumPad3>, <NumPad4>, <NumPad5>, <NumPad6>, <NumPad7>, <NumPad8>, <NumPad9>, <MenuLeft>, <MenuRight>, <F1>, <F2>, <F3>, <F4>, <F5>, <F6>, <F7>, <F8>, <F9>, <F10>, <F11>, <F12>, <F13>, <F14>, <F15>, <F16>, <F17>, <F18>, <F19>, <F20>, <F21>, <F22>, <F23>, <F24>, <NumLock>, <ScrollLock> and <Command> (Mac OS only) .

It is usually better to use one of the toolkit-specific type functions.

	Small caveat
	In theory it is possible for keypresses entered with the nativeType function to go astray. For example, if a window unexpectedly pops up over the AUT, the keypresses will go to the newly active window rather than to the intended one. In practice this is a very rare occurrence.

This function sends a sequence of low-level native events to the window called windowName. This function may be useful when interacting with windows from another application or with widgets implemented with a foreign toolkit. For interaction with standard application widgets it is best to use the functions in Squish's API such as the type function.

Here's an example of use that is legal in JavaScript, Python, Perl, and Ruby:

sendNativeEvent("Login", "username");

At present, the only supported types of event are simple keystrokes. Support for complex keystrokes and for mouse events might be added in a future version. Please contact technical support if this is an important requirement for you.