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 or get, set, or iterate over properties on these objects.

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

# 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.setCaption("My Widget")

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

// create an object of type QPoint
var point = 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.setCaption("My Widget");

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

# create an object of type QPoint
my $point = 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->setCaption("My Widget");

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

# 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 setCaption "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 16.1.14).)

The functions 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.alloc()
s.initWithUTF8String_('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.alloc();
s.initWithUTF8String_('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.alloc();
$s->initWithUTF8String_('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
set s [NSString alloc]
invoke $s initWithUTF8String_ '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 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) {
    ...
}

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

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 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)
# Must 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");
}

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)
    ...
}

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

The condition is a piece of code to evaluate, normaly 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 15.1.9) for examples of use.

The condition is a piece of code to evaluate, normaly 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 15.1.9) 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 16.1.3.10).)

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 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 15.1.5.7) 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 itemText and that is itself accessible. This function is typically used to access items inside containers such as lists, tables, and trees.

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 or if the optional timeoutMSec parameter is used, that many milliseconds.

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, 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, 0 is returned.

	Python-specific
	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.)

See Event Handlers for Specific Objects (Section 15.1.8.3) for an example of use.

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 17.2.18) and How to Create and Use Verification Points (Section 15.3).)

This function grabs an image of the screen the AUT is running on and saves it to disk. The filename should have a suffix denoting the image format to be used. Here's an example of use that is legal in Python, JavaScript, and Perl:

saveDesktopScreenshot("images/screen.png");

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 info 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 info 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 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 info 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 info 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 info 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) 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 from row -1.)

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

If the where parameter is "scripts", the search starts in the test case's scripts directory and if the file isn't found there, the test suite's scripts directory is searched. If the where parameter is "testdata", the search starts in the test case's testdata directory and if the file isn't found there, the test suite's testdata directory is searched.

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 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 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 or integer fieldIndex, taken from the specified record (i.e., from a particular row from the dataset returned by the testData.dataset function).

See Example 15.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 test data directory.

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

This function copies the test data file called filename from the test case's test data directory (or if it isn't in the test case's test data directory, from the test suite's shared test data directory), 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 17.2.8). For more about Object Maps in use see Object Map (Section 16.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 returns the symbolic name for the given object, or for the object with the given (multi-property) realName. If the realName is incorrect it will simply be returned; no exception will be raised.

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

Every AUT that is started by Squish has a corresponding The ApplicationContext object. These objects provide the following properties and functions:

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 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 read-only property holds the application's name.

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

This function reads and returns everything which the application has written to the stderr stream since the last call to readStderr.

This function reads and returns everything which the application has written to the stdout stream since the last call to readStdout.

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 number of bytes of memory used by the application.

This function returns a tuple (in Python) or an array (in non-Python scripting languages) 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 16.5.2.3) squishserver.) 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 16.8.2.3)).

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 16.8.2) 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 defaultApplicationContext function or by the applicationContextList function. If the argument is omitted the default context is activated.

If the contextHandle object is invalid—for example, 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 aut parameter must be the name of an application whose path is already registered with the squishserver. (See Configuring squishserver (Section 16.5.2.3) squishserver.) 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 you want to specify a timeout, but don't want to change the host or port, you can do so by passing localhost as the host (and from Squish 3.4.5 an empty string which will make Squish use the configured host—which is 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 15.1.10.2). (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 the specified imageFormat. 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");

set widget [waitForObject $objectName]
set image [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, using the PNG (Portable Network Graphics) file format.

The supported image formats can vary, but those that are supported on all platforms are: "BMP" (Windows Bitmap), "JPG" (Joint Photographic Experts Group), "JPEG" (Joint Photographic Experts Group), "PNG" (Portable Network Graphics), "PPM" (Portable Pixmap), "TIFF" (Tagged Image File Format), "XBM" (X11 Bitmap), and "XPM" (X11 Pixmap).

For iPhone testing, only "JPEG" (Joint Photographic Experts Group) and "PNG" (Portable Network Graphics) are supported.

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

The global squishinfo object provides the following useful 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 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
}

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

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

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 set logScreenshotOnFail 1
# ... perform test ...
testSettings set logScreenshotOnFail 0

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

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"

(See also testSettings.getWrappersForApplication.)

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. In Squish 4, click Window|Preferences to invoke the "Pref­er­ences" dialog (Section 17.3.11), then click the Squish item, and then the Playback item and then set the Snooze Factor value. In Squish 3, click Edit|Preferences to invoke the preferences dialog and set the Script snooze factor value. The snoozeFactor can also be set by using squishrunner's command line options; see Recording a Test Case (Section 16.5.1.4) and Executing a Test Case (Advanced) (Section 16.5.1.5).

Reads and evaluates the contents of filename. Use this function to parse shared script files. A common use case is to write something like source(findFile("scripts", "common.js")), using the findFile function to produce a filename including a path.

(See also the "Import Squish Resource" dialog (Section 17.3.3) and the "New Squish Test Script" dialog (Section 17.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>")

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

The usage for JavaScript and Perl is identical.

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>, and <ScrollLock>.

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 Python, JavaScript, and Perl:

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.

In addition the the functions described above, test scripts can create native Java™ arrays, and insert and retrieve objects stored in the arrays. (For examples of use see Creating and Using JavaArrays (Section 15.1.6.5.2).)

This is a constructor function for creating native Java arrays. The size specifies how many objects it may contain (indexed from 0, so the last valid index is size - 1). If the optional nameOfType string is omitted, the function will return an array of type java.lang.Object[size]; otherwise the array will be of type nameOfType[size]. The nameOfType is a string that can specify a non-object type such as "int", or an object type such as "java.lang.String".

JavaArrays have two functions and one property.

This function returns the object at position index in the array. If the index is out of bounds a catchable exception is raised.

This read-only property holds the number of positions in the array. The first item is at position 0 and the last item is at postion javaArray.length - 1.

This function sets the item at position index in the array to the given object. If the index is out of bounds or if the object is of an invalid type (e.g., a string when the JavaArray holds integers), a catchable exception is raised.

This object's methods provide information about the browser being used.

This function returns the name of the browser which is being used for running the test.

This function returns the type of the browser which is being used for running the test. The type can have one of the following values:

This class provides the API for HTML anchor elements (links). This class inherits the HTML_Object Class (Section 16.1.10.14).

This function clicks this anchor (link), as if the user had clicked it.

This class represents a JavaScript array, such as those returned by web functions like HTML_Document.getElementsById and HTML_Document.getElementsByTagName. This class inherits the HTML_Object Class (Section 16.1.10.14).

This function returns the element at position index in the array. Index positions are 0-based.

This read-only property holds the number of elements in the array. This could be 0.

This class provides the API for HTML button and submit input elements. This class inherits the HTML_ButtonBase Class (Section 16.1.10.5) which inherits the HTML_FormElement Class (Section 16.1.10.11) which inherits the HTML_Object Class (Section 16.1.10.14).

For normal buttons, this is the same as calling HTML_ButtonBase.click. For submit buttons, this invokes the button's form's submit action.

This is the base class of all the HTML input button elements—such as, button, submit, radio, checkbox, and image—and provides the common API shared by all of them. This class inherits the HTML_FormElement Class (Section 16.1.10.11) which inherits the HTML_Object Class (Section 16.1.10.14).

Clicks this button (or checkbox, or image, and so on), as if the user had clicked it. (Some subclasses allow keyboard modifiers and the precise position where the element is clicked to be specified.)

This property holds this button's (or checkbox's, or image's, and so on's), value as a string.

This class provides the API for HTML checkbox input elements. This class inherits the HTML_ButtonBase Class (Section 16.1.10.5) which inherits the HTML_FormElement Class (Section 16.1.10.11) which inherits the HTML_Object Class (Section 16.1.10.14).

This property holds true if this checkbox is checked; otherwise it holds false.

Clicks this checkbox as if the user had clicked it. All the arguments are optional. See Web Object API Function Parameters for which values are valid for the modifierState. The x and y are the checkbox-relative coordindates of the click.

This class provides an abstract item API to access any supported item type contained in a custom item view (HTML_CustomItemView Class (Section 16.1.10.8).) This item class inherits the HTML_Object Class (Section 16.1.10.14). (See How to set up Support for Complex Widgets (Section 15.8.4) for how this API can be used to support those custom item view widgets which Squish doesn't support as standard.)

Return's a reference to this item's first child item (of type HTML_CustomItem Class (Section 16.1.10.7)) or returns 0 if there isn't one.

The column is optional (and not all item's support it), but if it is specified (and supported), then the item's first child item in the given column is returned if there is one; otherwise 0 is returned.

This function returns a reference to this item's handle (as type HTML_Object Class (Section 16.1.10.14)), or returns 0 if this item doesn't have an item handle.

This function returns the view (of type HTML_CustomItemView Class (Section 16.1.10.8)) that contains this item.

Return's a reference to this item's next sibling item (of type HTML_CustomItem Class (Section 16.1.10.7)); or returns 0 if there isn't one.

The column is optional (and not all item's support it), but if it is specified (and supported), then the item's next sibling item for the given column is returned if there is one; otherwise 0 is returned.

This property holds true if this item is open (i.e., expanded—in which case this item's children will be visible); otherwise it holds false.

If this property is set to true, it opens (expands) this item so that any children it has become visible. And if this property is set to false, it closes (collapses) this item so that any children it has become hidden.

Return's a reference to this item's parent item (of type HTML_CustomItem Class (Section 16.1.10.7)); or returns 0 if there isn't one, that is, if this is the root item.

The column is optional (and not all item's support it), but if it is specified (and supported), then the item's parent item for the given column is returned if there is one; otherwise 0 is returned.

This read-only property holds the type name of the actual (i.e., real) type wrapped by this API as a string. The name could be the view's type name rather than the item's type name, depending on the implementation. (The example shipped with Squish returns the view's type name.)

The type name returned might be, for example “gwttree”, or “itmilltree”, or “dojotree”, and so on.

This property holds true if this item is selected; otherwise it holds false.

If this property is set to true this item is selected. If this property is set to false this item is deselected.

This read-only property holds the item's text as a string.

If the extension provides an itemText function, that function's return value is returned; otherwise the item's innerText property's value is returned.

This class provides an abstract item view API to access any supported item view, that is, any DHTML/AJAX/JS item view widget with dedicated support. This class inherits the HTML_FormElement Class (Section 16.1.10.11) which inherits the HTML_Object Class (Section 16.1.10.14). (See How to set up Support for Complex Widgets (Section 15.8.4) for how this API can be used to support those custom item view widgets which Squish doesn't support as standard.)

The API for the items in the item view is provided by the HTML_CustomItem Class (Section 16.1.10.7).

The itemText used in many of the methods listed below identifies the relevant item. In the example shipped with Squish, the itemText is always the item's text as a string.

Return's a reference to the view's first item (of type HTML_CustomItem Class (Section 16.1.10.7)); or returns 0 if the view is empty.

The column is optional (and not all view's support it), but if it is specified (and supported), then the view's first child item in the given column is returned if there is one; otherwise 0 is returned.

Clicks the expand/collapse handle of the item called itemName.

Clicks the item called itemName.

Return's the view's caption for the given column.

Double-clicks the item called itemName. See Web Object API Function Parameters for which values are valid for the optional modifierState.

This function returns a reference to the item called itemName (of type HTML_CustomItem Class (Section 16.1.10.7)); otherwise it returns 0.

This function returns true if the view has an item called itemName; otherwise it returns false.

This function returns true if the view has an item called itemName, and the item is open (i.e., any child items it has are visible); otherwise it returns false.

This function returns true if the view has an item called itemName, and the item is seleced; otherwise it returns false.

This read-only property holds the number of columns displayed in the view.

This read-only property holds the type name of the actual (i.e., real) type wrapped by this API as a string.

The type name might be, for example, “gwttree”, or “itmilltree”, or “dojotree”, and so on.

This class represents a web page's HTML document object and provides useful accessor methods. This class inherits the HTML_Object Class (Section 16.1.10.14).

This function returns an array of all the DOM tree's elements that have the given id. (See also, HTML_Array Class (Section 16.1.10.3).)

This function returns an array of all the DOM tree's elements that have the given tagName. (See also, HTML_Array Class (Section 16.1.10.3).)

This class provides the API a web page's HTML form elements. This class inherits the HTML_Object Class (Section 16.1.10.14).

Invoke's the form's “submit” action.

This class is the base class for HTML form elements such as buttons, checkboxes, and so on, and provides the common API shared by all these elements. This class inherits the HTML_Object Class (Section 16.1.10.14).

This property holds true if this form element is disabled; otherwise it holds false.

Gives the keyboard focus to this form element.

This read-only property holds the name of this form element's type (such as, button, select, text, etc.).

This class provides the API for HTML image input elements—its methods are all inherited from its base classes. This class inherits the HTML_ButtonBase Class (Section 16.1.10.5) which inherits the HTML_FormElement Class (Section 16.1.10.11) which inherits the HTML_Object Class (Section 16.1.10.14).

This class provides the API for HTML option elements which provide the contents of selection elements. This class inherits the HTML_Object Class (Section 16.1.10.14). (See also, HTML_Select Class (Section 16.1.10.16).)

This read-only property holds true if this option is selected by default; otherwise it holds false.

This property holds the 0-based index position of this option in the selection element.

This read-only property holds true if this option is selected; otherwise it holds false.

This property holds this option's text as a string.

This property holds this option's value as a string.

This is the ultimate base class used for all objects that are HTML elements. The functions and properties defined in this class are available for all objects which are returned from Squish's findObject function.

This function returns the subclass name of the HTML object; for example, HTML_Button Class (Section 16.1.10.4). (See also, HTML_Object.domClassName.)

This read-only property holds the object's class name that is used by the DOM. (See also, HTML_Object.className.)

Evaluates the XPath statement and returns an HTML_XPathResult Class (Section 16.1.10.21) object. The XPath statement is executed relative to this HTML_Object's XPath.

This method makes it possible to efficiently operate on a web application's DOM document, for example, to retrieve elements and access their properties.

This function returns the object's first child (as an HTML_Object), or an invalid object if the object has no children. (See also, HTML_Object.lastChild, HTML_Object.nextSibling, HTML_Object.numChildren, HTML_Object.parentElement, and HTML_Object.previousSibling.)

This read-only property holds the object's height. (See also, HTML_Object.width.)

This function returns this object's hierarchical, qualified name.

This read-only property holds the object's ID.

This read-only property holds the object's inner text—this might contain HTML markup. (See also, HTML_Object.innerText.)

This read-only property holds the object's inner text as plain text, so the returned string does not contain any HTML markup. (See also, HTML_Object.innerHTML.)

Invokes an HTML_Object method called methodName, and returns the value returned by the method call as a string. Both the argument1 and argument2 arguments are optional. If either or both are given it or they are passed as argument(s) to the method call, so the HTML_Object.invoke method can be called with the following combinations of arguments: (methodName), (methodName, argument1), (methodName, argument1, argument2).

This function returns the object's last child (as an HTML_Object), or an invalid object if the object has no children. (See also, HTML_Object.firstChild, HTML_Object.nextSibling, HTML_Object.numChildren, HTML_Object.parentElement, and HTML_Object.previousSibling.)

This function returns this object's internal JavaScript reference name.

This function returns the object's next sibling (as an HTML_Object), or an invalid object if the object has no following sibling. (See also, HTML_Object.firstChild, HTML_Object.lastChild, HTML_Object.numChildren, HTML_Object.parentElement, and HTML_Object.previousSibling.)

This read-only property holds how many children this object has—this could be 0. (See also, HTML_Object.firstChild, HTML_Object.lastChild, HTML_Object.nextSibling, HTML_Object.parentElement, and HTML_Object.previousSibling.)

This function returns the object's parent object (as an HTML_Object), or an invalid object, if this object has no parent. Note that only a web site's document node has no parent; all other nodes are children of the document or of other nodes within the document. (See also, HTML_Object.firstChild, HTML_Object.lastChild, HTML_Object.nextSibling, HTML_Object.numChildren, and HTML_Object.previousSibling.)

This function returns the object's previous sibling (as an HTML_Object), or an invalid object if the object has no preceding sibling. (See also, HTML_Object.firstChild, HTML_Object.lastChild, HTML_Object.nextSibling, HTML_Object.numChildren, and HTML_Object.parentElement.)

This function returns the value of the property called name as a string. (The returned value is always a string even if the property was set to an integer or Boolean.) (See also, HTML_Object.setProperty.)

Sets the property called name's value to value. The value may be a string, integer, or Boolean. (See also, HTML_Object.property.)

This function returns an HTML_Style Class (Section 16.1.10.17) object that can be used to query this object's CSS (Cascading Style Sheet) attributes.

This read-only property holds the object's style.display value.

This function returns the object's style.visibility value.

This read-only property holds the object's HTML tag name, for example, DIV or INPUT.

This read-only property holds the object's title.

This read-only property holds true if the object has a visible attribute otherwise it holds false. See the HTML_Object.styleDisplay property and the HTML_Object.styleVisibility and HTML_Object.style functions for other ways of checking the object's visibility.

This read-only property holds the object's width. (See also, HTML_Object.height.)

This read-only property holds the object's x-coordinate.

This read-only property holds the object's y-coordinate.

This class provides the API for HTML radio button input elements. This class inherits the HTML_ButtonBase Class (Section 16.1.10.5) which inherits the HTML_FormElement Class (Section 16.1.10.11) which inherits the HTML_Object Class (Section 16.1.10.14).

This property holds true if this radio button is checked; otherwise it holds false.

Clicks this radio button as if the user had clicked it. All the arguments are optional. See Web Object API Function Parameters for which values are valid for the modifierState. The x and y are the radio button-relative coordindates of the click.

This class provides the API for HTML selection input elements (select and select-one). Web browsers normally render select elements as list boxes and select-one elements as comboboxes. This class inherits the HTML_FormElement Class (Section 16.1.10.11) which inherits the HTML_Object Class (Section 16.1.10.14).

This function returns true if this selection element is a multi-selection (type select); otherwise it returns false (meaning that this element is of type select-one).

Return's the option (HTML_Option Class (Section 16.1.10.13)) at position index in this selection element. (The indexing is 0-based.)

This is a convenience function equivalent to html_select_object.options().at(index).

This function returns an array (HTML_Array Class (Section 16.1.10.3)) of all the options (as HTML_Option Class (Section 16.1.10.13) objects) contained in this selection element.

This property holds this selection element's selected index. (This property is only really useful for single selection boxes, that is, those of type select-one.)

This property holds the selected option's text, or if this is a select (multi-selection) element, holds a string that contains a comma-separated list of the selected options' texts.

If this property is assigned to, it sets the option which has the same text as the given text to be selected.

If this is a select (multi-selection) element, the text string can specify a list of option texts by separating each one with a comma. In such cases, every option that has a text that matches one of the texts in the comma-separated list will be selected.

This class provides the API for accessing an object's CSS (Cascading Style Sheet). HTML_Style objects are returned by the HTML_Object.style function.

This function returns the string value of the CSS (Cascading Style Sheet) attribute with the given name, or an empty string if there is no element called name.

When it comes to composite attributes (such as background-color), Squish adopts the widely-used JavaScript convention of capitalizing the letter following a hyphen and then dropping hyphens. So, for example, to access the background color, we would write something like:

var style = myobject.style();
var bgColor = style.value("backgroundColor");

This class provides the API for HTML text input elements. All the class's API is inherited from its base classes. This class inherits the HTML_TextBase Class (Section 16.1.10.20) which inherits the HTML_FormElement Class (Section 16.1.10.11) which inherits the HTML_Object Class (Section 16.1.10.14).

This class provides the API for HTML textare input elements. All the class's API is inherited from its base classes. This class inherits the HTML_TextBase Class (Section 16.1.10.20) which inherits the HTML_FormElement Class (Section 16.1.10.11) which inherits the HTML_Object Class (Section 16.1.10.14).

This is the base class for HTML text input elements (text and textarea), and provides methods common to both. This class inherits the HTML_FormElement Class (Section 16.1.10.11) which inherits the HTML_Object Class (Section 16.1.10.14).

This property holds this text or textarea's text as a string.

This is the type of the result object returned when an XPath is evaluated.

When evauating an XPath statement on any HTML_Object Class (Section 16.1.10.14) (see HTML_Object.evaluateXPath), an object of type HTML_XPathResult is returned. This object contains the results of the XPath execution.

This read-only property holds the XPath result as Boolean value.

This read-only prototype holds the XPath result as a numerical value.

This function returns the first node (of type HTML_Object Class (Section 16.1.10.14)) of the node list if the result of the XPath execution was a node list.

This read-only property holds the number of nodes returned by the XPath execution. A value of -1 means that no node list has been returned.

This read-only property holds the XPath result as string value.

This function returns the node (of type HTML_Object Class (Section 16.1.10.14)) at the given index position in the node list if the result of the XPath execution was a node list.

The Squish object provides an API through which Squish's web edition can be extended to recognize custom AJAX/JavaScript/DHTML widgets. This means that Squish can work on high-level custom widgets instead of working on the low-level DOM objects.

Using this mechanism makes it possible to create robust high-level tests for those AJAX/JavaScript/DHTML widgets that Squish doesn't support as standard.

This function registers the given function as a handler for simulating mouse clicks. The function will be called with an HTML element when a click on that element ought to occur. If the element is one that the handler function wants to handle the handler function should perform the click and return true; otherwise it should return undefined if it wants Squish to try other handlers (and default to Squish's own functionality if no other handler is available or if all the handlers return undefined).

This function registers the given function as a handler when finding the actual object an event refers to. The function will be called with an HTML element when an event for that element occurs, and may return the element, or another element, or undefined if it wants Squish to try other handlers (and default to Squish's own functionality if no other handler is available or if all the handlers return undefined).

This function registers the given function as an object name matcher function that returns a Boolean to indicate whether the real (multi-property) name matched, i.e., if the object matched by its properties. The function will be called with an object, a property name, and a valueObject—see the Squish.matchProperty function for more about the parameters—and returns a Boolean or undefined if it cannot perform the match. When matching a name, Squish will try as many name matching functions as have been registered using this function, and if all of them return undefined (or if there aren't any), Squish will fall back to using its own built-in name matching algorithm. (For an example of use, see How to Implement a Custom Name Matcher (Section 15.8.3.2); see also Improving Object Identification (Section 16.9).)

This function registers the given function as a name generator function that returns a unique name real (multi-property) name for a given object. The function will be called with an object and must return a name that uniquely identifies the object as a string in the form of a real name—or it must return undefined if it cannot generate a name for the object. When generating a real name for an object, Squish will try as many name of functions as have been registered using this function, and if all of them return undefined (or if there aren't any), Squish will fall back to using its own built-in name generation algorithm. (See How to Implement a Custom Name Generator (Section 15.8.3.1) for an example.)

This function registers the given function as a function that returns the high-level type of a DOM object. The typeOf function (function) takes a single string as argument (an element) and returns a string as its result.

When Squish encounters an HTML element that has been registered with the Squish.registerWidget function, and whenever it needs to know the element's type, it uses the hook function registered here. So if, for example, we had a <span> tag that we wanted to treat as a button, we could return "button" as the tag's type instead of the default (which in this example would be "span").

Here is a very simple typeOf function that we could register with the Squish.addTypeOfHook function:

function typeOf(element)
{
    if (element.className == "span")
	return "button";
    return undefined;
}

This function re-identifies <span> tags as buttons, but leaves the types of all other tags unchanged. For elements that you want Squish to treat as interactive elements, you would normally return one of the types button, checkbox, image, radio, or submit. Returning undefined for cases we don't handle is important—it means that Squish will look for another typeOf function (since many can be registered), falling back on its own internal typeOf function if there are no others or if all the others return undefined for the element.

This function returns a copy of string s with any leading and trailing whitepace removed and each internal occurrence of multiple whitespace (or of tabs or newlines) replaced with a single space. Also, all occurrences of Unicode characters U+2011 (non-breaking hyphen) and U+2013 (en-dash), are replaced with a hyphen.

This function returns the real (multi-property) name of an item in a view. The name is produced by taking the viewObjectName real name and adding an additional property to hold the itemText to provide a name that uniquely identifies the view item.

This function returns the first element that has the given className and tagName relative to the specified contextNode. (See Item traversal (Section 15.8.4.4.4) for examples.)

This function returns an array of those elements that have the given className and tagName relative to the specified contextNode.

This function returns true if the given DOM object/web element has a DOM class whose name matches the text passed as className; otherwise it returns false.

For HTML elements that have a single name for their class name, e.g., <span class="warning">dangerous ducks</span> this function works exactly as expected. For example:

if (Squish.hasClassName(element, "warning"))
    handleWarningElement(element)

However, HTML elements are at liberty to have multiple space-separated class names, e.g., <span class="heading major">New Section</span>. In such cases Squish tracks the class names as a list, which is very flexible. For example:

if ((Squish.hasClassName(element, "heading") and
     Squish.hasClassName(element, "major")):
    # Both class names present
    handleMajorHeadingElement(element)
elif Squish.hasClassName(element, "heading"):
    # Only "heading" class name present
    handleHeadingElement(element)

This function returns true if the given valueObject's value matches the value of the given property; otherwise it returns false.

The valueObject contains both a string value to match and an integer flag indicating whether the match should be based on literal string comparison (0), wildcard matching (2), or regular expression matching (1), using the format {value: string, modifiers: integer}.

This function should be used in your custom matchObject function instead of doing a straight comparison.

Custom match property functions are registered using the Squish.addMatchObjectHook function. (For an example of use, see How to Implement a Custom Name Matcher (Section 15.8.3.2); see also Improving Object Identification (Section 16.9).)

Sends a mouse click event on the given objectOrName at the specified relative x, y position. The ctrl is a Boolean which if true means that the Ctrl key is pressed. Both shift and alt are also Booleans and work in the same way regarding the Shift and Alt keys. All the parameters are optional and can be omitted.

This function returns the real (multi-property) name of the given objectOrName.

This method might call a registered name hook function, so be careful when calling this from your custom name hook handler.

Given a DOM objectOrName/web element, this function returns a string containing one or more space separated propertyName='propertyValue' pairs, one for each of the properties in the given listOfPropertyNamess. The resultant string is suitable for use in name generation, for example, by the Squish.uniquifyName function.

This function is used to register custom web elements with Squish so that they can be scripted, recorded, and played back correctly. The argumentObject is a JavaScript object (i.e., a named argument list—an object enclosed in braces and that contains a comma-separated list of name–value pairs), and that supports two keys:

For an example see How to set up Support for Simple Widgets (Section 15.8.2).

The purpose of this function is to allow you to add support for the recording of mouse clicks (mouseClick) on HTML elements that Squish would normally ignore. This is useful if you want to record clicks on, say, <span> tags, or on custom tags supported by the particular web framework you're using.

Squish can tell an element's type by checking its type attribute or its tagname but you can override this (for example, make a <span> tag be treated as a button), by registering a typeOf function. Such a function should return one of the types button, checkbox, image, radio, or submit, and is registered using the Squish.addTypeOfHook function. Note that although we must register each custom element with its own individual Squish.registerWidget function call; we could call the Squish.addTypeOfHook function just once, since in the typeOf function we can return an appropriate type for all the custom elements we have registered.

This function returns a “uniquified” version of the name for the given objectOrName by adding the correct occurrence into the name.

The name must be provided as a real name, that is a string of the form {propertyName1='propertyValue1' propertyName2='propertyValue2' ... propertyNameN='propertyValueN'}. Given a name and an objectOrName, this function returns the name unchanged if the name uniquely identifies an application object. Otherwise it returns name with an additional property (occurrence) whose value is an integer such that the name is unique. The purpose of this function is to create a name that uniquely identifies the given objectOrName.

Squish's Python-specific extension modules are loaded automatically by internally executing the equivalent of the following statements:

import test
import testData
import object
import objectMap
import squishinfo
from squish import *

This means that it is not necessary to import them yourself unless you are developing your own standalone module.

Squish's object module has the same name as the base class of all Python 2 new-style classes, and of all Python 3 classes. In practice this is very rarely a problem. For Python 2 we can just create old-style classes or do import __builtin__ and inherit from __builtin__.object instead of object. For Python 3 there is no need to do anything since we don't ever explicitly inherit object since it is inherited by default if no other class is specified.

The wildcard import of all the objects in the squish module means that some of Python's built-in objects are replaced with Squish objects that have the same names but completely different behavior. The most important cases are Squish's int object (which is the Squish type for an integer in the wrapper's C and C++ code), and the type function which is used to simulate keyboard input by the user. In the case of Python's built-in type function it is better Python practice to use the isinstance function. But in any case, if you want to use any of Python's built-in objects that have been replaced by a Squish object it is easy to do. Simply import the built-ins at the top of your test script (Python 2: import __builtin__; Python 3: import builtins), and then use the fully-qualified name for the built-in objects you want to use. For example, the __builtin__.int function (Python 2), or the builtins.int function (Python 3).

If you need to import custom modules that are not in sys.path you can make them available either by setting (or extending if already set) the PYTHONPATH environment variable with the path or paths to the module or modules you want to import, or you can extend sys.path at the start of your test scripts like this:

import sys
sys.path.append("my/path")

You can then import any module from my/path as normal, e.g., import mymodule.

	Note
	Most scripting languages, including Python, understand Unix-style paths that use / as a path separator, even on Windows. However, if you really want to use Windows-style paths with the \ path separator, you must either escape them (e.g., "my\\path") or use a raw string (e.g., r"my\path").

In addition to the Squish extension API, the full set of Python language features and modules is available for scripting. The Python Documentation page has links to the Python documentation for the current and older versions. If you prefers books, a good Python 2 book is Core Python Programming by Wesley Chun, and a good Python 3 book is Programming in Python 3 by Mark Summerfield.

For documentation on the Tcl language and standard extension packages see the Tcl/Tk Documentation page on the Tcl home page. That page also has links to Tcl tutorials. If you prefer books, a good Tcl book is Practical Programming in Tcl and Tk by Brent Welsh and Ken Jones with Jeffrey Hobbs.

In theory, any JavaScript book or online resource is suitable for learning about the language or for looking up functions. Unfortunately most authors don't make a clear distinction between features that are part of the JavaScript language itself and browser-specific extensions. When reading such texts beware of any example code that makes use of the window or document objects since these are provided by browsers and are not part of the language.

By keeping in mind the distinction between the pure language (which is what Squish supports) and browser-specific extensions, you'll be able to find the information you need from a variety of books and online resources while avoiding confusion. Here are some useful online JavaScript language resources:

If you prefer books, a good JavaScript book is JavaScript: The Definitive Guide by David Flanagan.

The JavaScript engine shipped with Squish is compliant with the ECMAScript language specification (ECMA 262 Edition 3). This corresponds with Netscape's JavaScript 1.5 and Microsoft®'s JScript 5.5. The language core that is defined in this standard encompasses operators, control structures, objects, and other features commonly found in a scripting language. A set of built-in classes provide methods for the most common data handling—these classes are: Boolean, Date, Error, Function, Number, Object, RegExp, and String.

	Invoking Java Functions from JavaScript
	Some Java™ functions or methods have the same names as JavaScript reserved words. It is still possible to call such functions or methods, but to avoid conflicts with reserved words we must use a slightly different syntax. For example, to call object obj's delete method (which conflicts with JavaScript's delete reserved word), instead of writing obj.delete() we must write obj["delete"]() instead.

The pure JavaScript (i.e., ECMAScript) language has no built-in support for file handling or networking, unlike other scripting languages such as Python and Tcl. This is because JavaScript has been designed to be a small language that can be safely embedded into applications. However, JavaScript is also designed to be extened by custom APIs specific to the embedding application. In the case of web browsers there are hundreds of functions and properties that allow for the manipulation of HTML documents via the DOM API, for example. In the case of Squish we have added numerous functions specific to testing. And we have also added some general purposes classes described below. And if the features we have added are not sufficient for your needs contact support and request an enhancement.

Note

Some JavaScript functions take a path parameter. This can be a directory or a filename (and can include the full path), such as C:\My Documents\test-plan.odt or /home/user/test-plan.odt. In most scripting languages, including JavaScript, the backslash character (\) is used to start an escape sequence inside strings and so cannot be written by itself. For this reason, when writing Windows paths in JavaScript strings we must escape the backslash—for example, "C:\\My Documents\\test-plan.odt".

The File object provides basic file handling functions such as checking for a file's existence, opening a file for reading or writing, and removing a file.

This method closes the file object it is called on. Once closed a file object cannot be read from or written to.

This function returns true if the specfied fileOrDirectory exists; otherwise it returns false. The fileOrDirectory may include an absolute or relative path, or no path, in which case the current working directory is used.

This function tries to open the specified fileName (which may include an absolute or relative path, or no path, in which case the current working directory is used). The optional mode parameter defaults to "r" (open for reading). If the mode is specified it must be: "a" (open for append), or "r" (open for reading), or "w" (open for writing). If the fileName cannot be opened an exception is thrown.

Once a file has been successfully opened its methods can be called. For files opened in append or write mode the file.write method can be called, and for files opened in read mode the file.read and file.readln methods can be called. And for any opened file, the file.close method can be called.

This method reads in the entire contents of the file object returned by the File.open function—providing the file was opened in read mode. The file's content is assumed to be plain text using the UTF-8 encoding.

Example:

var file = File.open("C:\\testdata\\input.txt", "r");
var text = file.read();
inputField.setText(text);