Returns whether the object with the name objectName exists.

Finds and returns the object via the path specified by objectName. The object name contains dots to represent the object hierarchy. The names of the single objects are not necessarily the QObject names, but a unique name. This can also be another unique property like the caption, a groupbox title, etc. In the worst case this is the class name plus a number (e.g. QLineEdit5).

Squish objects blend in with native objects of the scripting language quite smoothly. 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.

The best way to show how that works is to look at the example code below:

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

# read a property of a widget
x = mywidget.x

# set a property of a widget
mywidget.y = 33

# call a member function
mywidget.setCaption("My Widget")

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

Returns True (1) if object is null (a NULL pointer in C), False (0) otherwise.

Returns the class name of the object.

Returns the object name of the object.

Returns whether object is a pointer, reference, value or array in C++.

Casts the <object> to the type <type> and returns a reference to that object. <type> can either be specified by name (as a string) or via a type object.

This modifies the <object> itself. If the cast fails, 0 is returned.

This set of functions implements functions that can be used to verify that the AUT's state is as expected during a test run.

Verifies that condition is True (1). If the condition is True a test result of type PASS is added to the test log, otherwise a test result of type FAIL is added.

Returns True on PASS and False on FAIL.

You may use the optional info parameter to specify an arbitrary string (comment, bug number, test plan reference etc.) that will be added to the test result.

Compares val1 and val2 and if they are equal a test result of type PASS is added to the test log, otherwise a test result of type FAIL is added.

Returns True on PASS and False on FAIL.

You may use the optional info parameter to specify an arbitrary string (comment, bug number, test plan reference etc.) that will be added to the test result.

This function is used for expected failures in test scripts.

Verifies that condition is not True (1). If the condition is True a test result of type FAIL is added to the test log, otherwise a test result of type PASS is added.

Returns True on PASS and False on FAIL.

You may use the optional info parameter to specify an arbitrary string (comment, bug number, test plan reference etc.) that will be added to the test result.

This function is used for expected failures in test scripts.

Compares val1 and val2 and if they are equal a test result of type FAIL is added to the test log, otherwise a test result of type PASS is added.

Returns True on PASS and False on FAIL.

You may use the optional info parameter to specify an arbitrary string (comment, bug number, test plan reference etc.) that will be added to the test result.

If executing code throws an exception, a test result of type PASS is added to the test log, otherwise a test result of type FAIL is added.

	Note
	code must be of type string.

You may use the optional info parameter to specify an arbitrary string (comment, bug number, test plan reference etc.) that will be added to the test result.

	Note
	As pass is a reserved word in Python, the Python version of this functions is called test.passes().

Adds a test result of type PASS, FAIL, FATAL, LOG or WARNING with the message and an optional detail to the test log.

Executes the verification point vp. If the verification point references a data set, record references the record of the data set which should be used.

Returns True on PASS and False on FAIL.

Looks for the file filename. If the first argument is "scripts", the search begins in the test case's scripts directory and if it isn't found there, the shared scripts directory of the test suite is searched. If the first argument is "testdata", the search begins in the test case's testdata directory, and if the file isn't there, then the test suite's shared testdata directory is searched.

If the file is found the absolute file name is returned, otherwise an error is thrown.

Copies the test data file filename from the test case's testdata directory or the test suite's shared testdata directory into the AUT's current working directory.

Copies the file filename from the AUT's current working directory to the test case's testdata directory.

Removes the file filename from the AUT's current working directory.

Returns whether the file filename exists in the AUT's current working directory.

These functions are used for data-driven testing. They allow opening a dataset (e.g. a TSV file) and retrieving fields from the datarecord by fieldindex or fieldname.

This function returns a tuple containing the field names of the specified record.

This function returns a valid filename you can write to. The file will be located in the shared test data directory when where is "shared" or in the local test data directory when where is "local".

This function should be used when you are running a script in a learning mode to create test data dynamically.

Adds object to the object map.

Returns the symbolic name for the given object, or the object referenced by realName.

Returns the real name for the given object, or the object referenced by symbolicName.

Returns a tuple containing all mapped symbolic names. The element order is not defined.

Starts the specified application and returns a reference to its context. aut must be an application whose path is already registered to squishserver. In addition to the application name command line parameters can be specified in the string passed to this function.

Optionally, as second and third parameter a host and port can be passed to this function. This way instead of connecting to the default host and port (as specified in the Squish IDE's settings or squishrunner's command line), a connection to squishserver on the specified host listening to the specified port will be established. This allows to control multiple applications on multiple computers from one test script.

Also optionally, as fourth parameter a timeout (in seconds) can be passed to specify how long Squish should wait for the application to come up before throwing an error. This value overrides squishrunner's default AUT timeout.

Attaches to the specified application and returns a reference to its context. aut must be an application that is registered as an attachable AUT.

The meaning of the optional arguments host,port, and timeout are the same as with the startApplication function.

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

This function can be used to switch the current application context. The ctx handle is is either the one returned from a setApplicationContext(), defaultApplicationContext() or applicationContextList() call. If the argument is omitted the default context is activated.

Returns a handle to the default application context.

Returns a list of handles to all existing application contexts.

The ApplicationContext object provides the following properties and functions:

Installs an event handler on an object class, an object or globally (if no class or object is specified). The script function handlerFunction will be called when the event of the type event occurs.

event can be any event type such as QKeyEvent (Qt), ButtonPressed (XView, Tk), etc. Squish adds the following convenience event types:

A numeric property holding the Squish major version number.

A numeric property holding the Squish minor version number.

A numeric property holding the Squish patch level version number.

A numeric property holding a unique number representing the Squish version. The number is made up of a hexadecimal representation of major, minor, patch and release level. The individual values are shifted and packed into a single 4-byte number. The release levels Alpha, Beta and Final are denoted by the values 0xAA, 0xBB and 0xFF, respectively. As an example, 0x030001FF stands for the final 3.0.1 release.

This kind of representation looks odd on first sight but simplifies version tests in script code. Here's some JavaScript sample code that does a single comparison for conditional code:

if (squishinfo.version >= 0x030100AA) {
   // code meant for version 3.1.0-alpha or higher
}

A property of type string holding the human-readable Squish version number, e.g. "3.0.0-alpha".

A property that denotes the currently active settings group of the test.

Reads and evaluate the contents of filename. Use this function to parse shared script files.

Sleep for the specified nominal number of seconds. Fractions of seconds can be specified as well by using decimal numbers. The effective delay will depend on the current <snoozeFactor>.

Evaluates condition until it becomes true or the waiting times out after the number of specified milliseconds. The timeout parameter is optional. This is useful if you want to synchronize your script execution to a certain state in the AUT.

Waits until the object with the name objectname exists and is accessible. This is useful if you want to synchronize your script execution. By default, it waits for maximum 20 seconds. With the optional timeout parameter a different timeout (in milliseconds) can be specified.

Waits for a new application, which Squish will hook into, to start. This is used by Squish for test scripts which access multiple applications which are started by the AUT.

Send a sequence of low-level native events to the specified window with the name window. This function may be of use when interacting with windows from another application or controls implemented with a foreign toolkit. For interaction with standard application controls use of type() and other function is recommended.

Example:

sendNativeEvent("Login", "username");

Currently, the only supported type of events are simple keystrokes. Support for complex keystrokes and mouse events might be added in a future version. Please contact technical support to voice your demand.

The extension modules are loaded automatically by internally executing the equivalent of the statements

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

before the script is executed. It's therefore not necessary to import them by yourself unless you are developing your own standalone module.

Note the drawback of above wild card import of the wrapped API: native Python functions like int() and type() will be shadowed as their names conflict with the wrapped int C type and the type() function used to send key events to the AUT. To access the built-in functions just import the __builtin__ module and access them with their fully qualified name, e.g. __builtin__.int().

Besides the Squish extension API the full set of Python language features and modules is available for scripting. The Python Documentation page lists a few books and also has the current documentation available for download and online browsing.

For documentation on the Tcl language and standard extension packages see the Tcl/Tk Documentation page on the Tcl home page. Next to links to the man pages you'll find a tutorial there.

Theoretically you could pick up any JavaScript book or online resource to learn about the language or look up a function. Unfortunately most authors don't draw a clear line between features that are part of the language proper and those specific to a web browser. When browsing such HTML programming documentation beware of any example code that operates on the window or document object.

When keeping this distinction in mind you'll still be able to draw the required information from a variety of books and online resources. Here are some online resources that we have collected for your convenience:

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 handful of built-in classes provide functions for the most common data handling. These objects are:

You may notice the lack of classes such as file or network I/O typically found in languages like Python and Tcl. This is because pure JavaScript (or rather ECMAScript) has been designed to be a small language that can safely be embedded into an application. It's meant to be extended by custom API specific to the embedding application, though. In the case of web browsers there are hundreds of functions and properties that allow manipulation of HTML documents via the DOM API for example. In the case of Squish we have added numerous functions specific to testing. We also added some general purposes classes described below. If you need anything else please file an enhancement request.

Returns true when a file or directory path does exist on the local hard disk; false otherwise.

Attempts to remove the file with path from the local hard disk. Returns true on sucess; false otherwise.

Will attempt to open file path and return a File instance. In case of failure an exception will be thrown. The mode can either be "r" for read access or "w" for write access. If undefined it will default to "r".

Functions like read(), write() and access() can be called on the returned File instance.

Reads in and returns the content of a file. The file content is assumed to be UTF-8 encoded.

Example:

var f = File.open("input.txt", "r");
var t = f.read();
inputField.setText(t);

Writes the string to the file using UTF-8 encoding. The file has to be opened in write-mode.

Closes the file. Afterwards no data can be read or written anymore.

The name property of the OS object holds the name of the operating system that squishrunner is running on. On Microsoft Windows systems the value will be "Windows". On Unix-like systems the value will be identical to the output of uname -s, i.e. "Linux", "Solaris", "Darwin" etc.

Executes command by calling the system command line shell. In case of a successfull execution the return status of the command will be returned. On errors -1 will be returned.

command can not only hold the name of an executable but also command line arguments to be interpreted by the application or shell.

Example:

var ret = OS.system("readresult.exe > output.txt");
if (ret != 0)
   test.warn("readresult failed");

Analogous to OS.system() will execute command from a system shell. The commands Stdout output will be read and returned.

Example:

var files = OS.capture("ls out/*.dat");
for (var f in files) {
   ...
}

Obtains the current value of the environment variable, name.

Example:

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

Inserts the environment variable name into the current environment. If the variable name does not exist, it is inserted with the given value. If the variable does exist, its value is overwritten.

Example:

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

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

Returns the list of files and directories in the directory specified by path. The special directories . and .. are excluded.

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

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

Attempts to parse the given string of XML markup. In case of success, a document node is returned which represents the root of the document ree. In case of an error, an exception is thrown.

Returns whether this node is a null node.

Returns the name of the node. For elements, it's the tag name. For the document node, the string “<anonymous xml document>” is returned.

Returns the type of the nodename of the node. Possible return values are:

Returns the parent node of this node. If there is no parent node (which is true for the document node) then a null node is returned.

Returns the first child node of this node. If this node does not have any children, a null node is returned.

Returns the next sibling node of this node. This this node does not have any siblings, a null node is returned.

Returns the text contained within this node. Note that this function does not recursively collate the text of all child nodes (assuming that aElem always points to the “a” element):

    // XML markup is '<a>Hello<a>'
    test.log( aElem.textContent ); // prints 'Hello' to the test log

    // XML markup is '<a><b>Hello</b></a>'
    test.log( aElem.textContent ); // prints an empty string to the test log

	Note
	This function can only be called on element nodes (where nodeType returns XML.ElementNode). Calling it on non-element nodes will cause an exception to be thrown.

Returns a boolean indicating whether the given node has an attribute called attrName.

	Note
	This function can only be called on element nodes (where nodeType returns XML.ElementNode). Calling it on non-element nodes will cause an exception to be thrown.

Returns a string with the value of the attribute with the name attrName. If there is no such attribute with that name, the behaviour is undefined. If attrName is an empty string, an exception is thrown.

	Note
	This function can only be called on element nodes (where nodeType returns XML.ElementNode). Calling it on non-element nodes will cause an exception to be thrown.

Attempts to create a connection to some SQL database. The information required is expected to be passed via an object whose properties are then interpreted. Here's a sample invocation showing how to connect to a MySQL server on the host “dulsberg”:

    var c = SQL.connect( { Driver: "MySQL",
                           Host: "dulsberg",
                           Port: 1342,
                           Database: "mydatabase",
                           UserName: "test",
                           Password: "secretPhrase" } );

The settings have the following meanings:

In case there was some problem while connecting to the SQL server, an exception is thrown. If there is no error, an object of type 'SQLConnection' is returned which can be used to evaluate SQL statements. The connection object provides the following functions:

Closes the given SQL connection.

Executes an SQL query on the given connection object <connection>. In case of an error, an exception is thrown. Otherwise an object of type 'SQLResult' is returned which can be used to iterate over the returned data. Here is an example how to execute a SQL query on some connection object:

var result = connection.query( "SELECT last_name, first_name FROM persons WHERE country LIKE 'A%';" );

The result objects returned by this function provide the following functions and properties:

Returns whether this result object is in a valid state. Some functions return invalid result objects to flag an error or otherwise special condition (see below).

Selects the next row in this SQL result. Marks <result> as invalid in case there is no other row to navigate to. This function and the isValid property above let you iterate over the rows returned by some SQL query easily, as in this example:

var result = connection.query( "SELECT last_name, first_name FROM persons WHERE country LIKE 'A%';" );
while ( result.isValid ) {
    // do something with the result
    result.toNext();
}

Navigate to the first row in this result. This is useful if you want to iterate over the rows many times: after processing the rows using toNext, call toFirst to jump back to the first result so that you can use toNext again.

Returns the number of rows which this result contains.

These two functions can be used to get the data in the given column of the current row. The column can either be addressed using a number (counting from zero), or using the name of the column (case insensitive). The data in the given column is implicitely converted into a string. Note that you can also use the bracket-syntax as a shortcut. This little example will execute a sample SQL query and then iterate over the returned data rows, printing the first and last name of all matching entries in the persons table:

var result = connection.query( "SELECT last_name, first_name FROM persons WHERE country LIKE 'A%';" );
while ( result.isValid ) {
    var s = "First name: ";
    s += result.value( 1 );   // same as result["first_name"] or result.value( "first_name" );
    s += ", Last name: ";
    s += result["last_name"]; // same as result.value( 0 ) or result.value( "last_name" );
    test.log( s );
    result.toNext();
}

The Perl documentation contains a manual page perlintro that can serve as a good starting point. Links to other manual pages, tutorials and FAQs can be found on the Online Documentation and the perldoc page.

There is a great numer of Perl books available for purchase. A listing can be found at the Perl Books page. Among the most popular ones are probably "Learning Perl" and "Programming Perl" both published by O'Reilly & Associates.