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

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 Functions (Section 16.1.3.10).)

Waits until the objectOrName object is accessible (i.e., it exists and is visible and enabled). Returns a reference to the object if successful or raises a (catchable) LookupError exception on failure. This function is useful if you want to synchronize your script execution. By default, the function waits for a maximum of 20 seconds (or whatever timeout has been configured; see the setAUTTimeout option in Configuring squishrunner (Section 16.5.1.7)), after which it throws the exception. With the optional timeoutMSec parameter a different timeout (in milliseconds) can be specified.

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

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.

This is an extension to the waitForObject() function for those widgets that contain their own items. By default, the function waits for a maximum of 20 seconds (or whatever timeout has been configured; see the setAUTTimeout option in Configuring squishrunner (Section 16.5.1.7)). With the optional timeoutMSec parameter a different timeout (in milliseconds) can be specified.

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.

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 testData.fieldNames() and testData.field()), 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.15, “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.

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:

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

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 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.7.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.7.2) for more information.

This function returns a handle to the current application context.

This function returns a handle to the default application context.

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.

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

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

The global squishinfo object provides the following useful properties.

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.

The testSettings object has the following properties:

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 returns the list of wrappers associated with the specified application.

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"

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 preferences dialog, 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.

This function simulates a native mouse click. 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.

This function simulates user keyboard input using the operating system's facilities. 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.

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

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.

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.9.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.9.14).

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

This function returns 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.9.5) which inherits the HTML_FormElement Class (Section 16.1.9.11) which inherits the HTML_Object Class (Section 16.1.9.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.9.11) which inherits the HTML_Object Class (Section 16.1.9.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.)

Sets this button's (or checkbox's, or image's, and so on), value property to the given string value.

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

This class provides the API for HTML checkbox input elements. This class inherits the HTML_ButtonBase Class (Section 16.1.9.5) which inherits the HTML_FormElement Class (Section 16.1.9.11) which inherits the HTML_Object Class (Section 16.1.9.14).

This function returns true if this checkbox is checked; otherwise it returns false. (See also, HTML_CheckBox.setChecked().)

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.

Checks this checkbox element if the Boolean check argument is true; otherwise it unchecks the checkbox. (See also, HTML_CheckBox.checked().)

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.9.8).) This item class inherits the HTML_Object Class (Section 16.1.9.14). (See How to set up Support for Complex Widgets (Section 15.9.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.9.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 true if this item is open (i.e., expanded—in which case this item's children will be visible); otherwise it returns false.

This function returns true if this item is selected; otherwise it returns false.

This function returns a reference to this item's handle (as type HTML_Object Class (Section 16.1.9.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.9.8)) that contains this item.

Return's a reference to this item's next sibling item (of type HTML_CustomItem Class (Section 16.1.9.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.

Return's a reference to this item's parent item (of type HTML_CustomItem Class (Section 16.1.9.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 function returns 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, for example, be “gwttree”, or “itmilltree”, or “dojotree”, and so on.

If Boolean open is true, opens (expands) this item so that any children it has become visible. If Boolean open is false, closes (collapses) this item so that and children it has become hidden.

If Boolean select is true, this item is selected; otherwise it is deselected.

This function returns 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.9.11) which inherits the HTML_Object Class (Section 16.1.9.14). (See How to set up Support for Complex Widgets (Section 15.9.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.9.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.9.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.9.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 function returns the number of columns displayed in the view.

This function returns the type name of the actual (i.e., real) type wrapped by this API as a string.

The type name returned might, for example, be “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.9.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.9.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.9.3).)

This class provides the API a web page's HTML form elements. This class inherits the HTML_Object Class (Section 16.1.9.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.9.14).

This function returns true if this form element is disabled; otherwise it returns false. (See also, HTML_FormElement.setDisabled().)

Gives the keyboard focus to this form element.

Disables this form element if the Boolean flag is true; otherwise enables it. (See also, HTML_FormElement.disabled().)

Return's 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.9.5) which inherits the HTML_FormElement Class (Section 16.1.9.11) which inherits the HTML_Object Class (Section 16.1.9.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.9.14). (See also, HTML_Select Class (Section 16.1.9.16).)

This function returns true if this option is selected by default; otherwise it returns false.

This function returns the 0-based index position of this option in the selection element.

This function returns true if this option is selected; otherwise it returns false.

Set's this option's text property to the given text string.

Set's this option's value property to the given string value.

This function returns this option's text property as a string.

This function returns this option's value property 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.9.4). (See also, HTML_Object.domClassName().)

This function returns 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.9.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 function returns the object's height. (See also, HTML_Object.width().)

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

This function returns the object's ID.

This function returns the object's inner text—this might contain HTML markup. (See also, HTML_Object.innerText().)

This function returns 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 function returns 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.9.17) object that can be used to query this object's CSS (Cascading Style Sheet) attributes.

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

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

This function returns the object's HTML tag name, for example, DIV or INPUT.

This function returns the object's title.

This function returns true if the object has a visible attribute otherwise it returns false. See the HTML_Object.styleDisplay(), HTML_Object.styleVisibility(), and HTML_Object.style() functions for other ways of checking the object's visibility.

This function returns the object's width. (See also, HTML_Object.height().)

This function returns the object's x-coordinate.

This function returns 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.9.5) which inherits the HTML_FormElement Class (Section 16.1.9.11) which inherits the HTML_Object Class (Section 16.1.9.14).

This function returns true if this radio button is checked; otherwise it returns false. (See also, HTML_RadioButton.setChecked().)

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.

Checks this radio button element if the Boolean check argument is true; otherwise it unchecks the checkbox. (See also, HTML_RadioButton.checked().)

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.9.11) which inherits the HTML_Object Class (Section 16.1.9.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.9.13)) at position index in this selection element. (The indexing is 0-based.)

This function returns an array (HTML_Array Class (Section 16.1.9.3)) of all the options' texts contained in this selection element.

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

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

Selects the option at position index in this selection element. (This method is primarily of use for single selection boxes, that is, those of type select-one.)

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.9.20) which inherits the HTML_FormElement Class (Section 16.1.9.11) which inherits the HTML_Object Class (Section 16.1.9.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.9.20) which inherits the HTML_FormElement Class (Section 16.1.9.11) which inherits the HTML_Object Class (Section 16.1.9.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.9.11) which inherits the HTML_Object Class (Section 16.1.9.14).

Sets this text or text area's text to the given string value.

Return's 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.9.14) (see HTML_Object.evaluateXPath()), an object of type HTML_XPathResult is returned. This object contains the results of the XPath execution.

This function returns the XPath result as Boolean value.

This function returns the XPath result as numerical value.

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

This function returns the number of nodes returned by the XPath execution. A return value of -1 means that no node list has been returned.

the XPath result as string value.

This function returns the node (of type HTML_Object Class (Section 16.1.9.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 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 they all 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.9.3.2); see also Improving Object Identification (Section 16.8).)

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.9.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.9.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.

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.9.3.2); see also Improving Object Identification (Section 16.8).)

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.9.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() 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, __builtin__.int() (Python 2), or builtins.int() (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 write() method can be called, and for files opened in read mode the read() and readln() methods can be called. And for any opened file, the close() method can be called.

This function tries to remove the specified fileName (which may include an absolute or relative path, or no path, in which case the current working directory is used). If the file was successfully removed the function returns true; otherwise it returns false.

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);

This method reads in the next line from 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. Each line is returned without any end of line characters, and if an attempt to read beyond the last line is made, null is returned.

This method writes the given string to the file object returned by the File.open() function—providing the file was opened in append or write mode. The string is written using the UTF-8 encoding.

The File object's separator property holds the file separator used by the operating system. For example, on Windows it holds, "\", and on Unix-like systems, "/".

The OS object provides functions for basic interaction with the operating system. It includes functions for executing commands (i.e., for running programs), for getting and setting the current directory, and for getting and setting environment variables.

This function executes the given command in a shell (console) just like the OS.system() function. The command string must hold the name of the command to be executed, and may optionally include command line arguments and shell redirection characters. What makes this function different from the OS.system() function is that it captures the command's output, that is, any text that would normally go to the console (the stdout stream), and returns it as a string.

Here is an example that shows the execution of a command on Windows, and the capturing of its output:

var files = OS.capture("cmd.exe /C dir C:\\temp\\*.dat");
for (var file in files) {
   // ...
}

Note that in this particular case it is easier and better to use the cross-platform OS.listDir() function to get a list of files in a directory.

This function changes the test script's current working directory to the specified path.

Example:

var dir = "output";
OS.chdir(dir);

This function returns the current working directory as a string.

Example:

var path = OS.cwd();
test.log("Current working directory: " + path);

This function returns the value of the environment variable with the given name, or an empty string if no such environment variable exists. (See also, OS.setenv().)

Example:

var homeDir = OS.getenv("HOME");
test.log("Current user's home directory: " + homeDir);

This function returns a list of all the files and directories in the directory specified by path. The special directories . and .. are excluded. This function does not recurse into subdirectories.

Here is an example that logs all the files that were generated in an output directory on Windows:

var files = OS.listDir("C:\\temp\\output");
for (var i in files)
    test.log("Found generated file: " + files[i]);

The OS object's name property holds the name of the operating system that squishrunner is running on. On Microsoft® Windows systems the value is "Windows". On Unix-like systems the value is the same as the output of uname -s, e.g. "Linux", "Solaris", "Darwin", etc.

This function pauses the script for the specified number of milliseconds. Unlike the snooze() function, the delay is fixed and not influenced by the current <snoozeFactor> setting.

This function sets the environment variable called name to have the given value. The name environment variable is created (and then set to the given value) if it doesn't already exist. (See also, OS.getenv().)

Example:

var preferredEditor = "vim";
OS.setenv("EDITOR", preferredEditor);

This function executes the given command in a shell (console). If the execution is successful the return status is returned; otherwise -1 is returned to signify that an error occurred. The command string must hold the name of the command to be executed, and may optionally include command line arguments and shell redirection characters.

Here is an example that executes a custom application on Windows and redirects its stdout stream to a file:

var result = OS.system("C:\\testprograms\\readresult.exe > output.txt");
if (result == -1)
    test.error("readresult error occurred");
else if (result != 0)
   test.warning("readresult failed");

Here is another example: this sends an email on a Unix system:

var msg = "This is a mail from Squish";
OS.system("echo '" + msg + "' | mail -s Subject bugs@example.com");

The XML object provides a parsing function that operates on a string of XML-marked-up text, and that returns an XMLNode object that provides methods which allow the XML to be traversed and queried.

This function parses the given string of XML markup and returns a document node object that represents the root of the document tree. If the parse fails an exception is thrown.

This node property holds this node's first child—or a null node if this node has no children.

This node method returns a string containing the value of the node's attributeName attribute. If the node doesn't have an attribute called attributeName, the method's behavior is undefined. If the attributeName is an empty string, an exception is thrown. All of a node's attribute names can be retrieved using the node.getAttributeNames() function.

	Note
	This function must only be called on element nodes—those nodes whose nodeType attribute's value is XML.ElementNode. Calling the function on non-element nodes will cause an exception to be thrown.

This node method returns a list of strings containing the names of all the node's attributes. Any of these names can be used as the argument to the node.getAttribute() function to get the attribute's value.

	Note
	This function must only be called on element nodes—those nodes whose nodeType attribute's value is XML.ElementNode. Calling the function on non-element nodes will cause an exception to be thrown.

This function returns true if the node has an attribute called attributeName; otherwise it returns false.

	Note
	This function must only be called on element nodes—those nodes whose nodeType property's value is XML.ElementNode. Calling the function on non-element nodes will cause an exception to be thrown.

This node property is true if the node is a null node; otherwise it is false.

This node property holds this node's next sibling node (which will be a null node if this node has no next sibling).

This node property holds the node's name, which is the tag name for element nodes. For the document node the node name is always “<anonymous xml document>”.

This node property holds the node's type name. The possible type names are:

This node property holds the node's parent node or a null node if this node has no parent. (For example, the document node has no parent.)

This node property holds the text contained within this node (which could be an empty string).

Note that this node property does not traverse its child nodes to produce a concatenation of all their texts. For example:

documentNode = XML.parse("<a>Hello</a>");
anchorNode = documentNode.firstChild;
test.verify(anchorNode.textContent == "Hello");

documentNode = XML.parse("<a><b>Hello</b></a>");
anchorNode = documentNode.firstChild;
test.verify(anchorNode.textContent == "");
boldNode = anchorNode.firstChild;
test.verify(boldNode.textContent == "Hello");

	Note
	This function must only be called on element nodes—those nodes whose nodeType property's value is XML.ElementNode. Calling the function on non-element nodes will cause an exception to be thrown.