Squish API

This section introduces the APIs that Squish provides in addition to the standard features of the scripting languages it supports. The Squish APIs provide the facilities that test engineers need to test GUI applications, and offer a wide range of functionality, from interacting with AUT objects, to recording information in test logs, performing verifications, controlling the AUT, and more.

Squish API Objects/Classes

Squish API Functions

Here are some quick links to the Squish API functions (not including the Squish objects or the toolkit-specific convenience functions):

Squish API Function Parameters

For all of the Squish API functions that take an objectOrName argument, it can be a reference to an object or the name of an object.

Some of the Squish API functions can take a modifierState argument that indicates which special keys are pressed at the time of a mouse click. Further, some of the functions take a mouseButton argument that indicates which mouse button was clicked.

The modifierState can be 0 (Modifier.NoModifier, the default), or the following: Modifier.Alt, Modifier.Control, Modifier.Shift. If more than one modifier is used, they must be OR-d together. For example, Modifier.Alt|Modifier.Shift. The form shown here works for Python and JavaScript. For Perl and Ruby, replace the period with two colons: Modifier::Control. For Tcl, use the enum function: enum Modifier Control.

The mouseButton can be any one of: MouseButton.LeftButton, MouseButton.MiddleButton,MouseButton.RightButton, or MouseButton.NoButton.

For Perl use: MouseButton::LeftButton, etc.

For Ruby use: MouseButton::LEFT_BUTTON, etc.

For Tcl use: enum MouseButton LeftButton, etc.

Identifying Objects

Many of the APIs' functions apply to particular objects, so being able to identify the object of interest is particularly important.

Squish provides several naming schemes, but the ones normally used are symbolic names and real names. Symbolic names are the most robust in the face of AUT changes, but real names can sometimes be more convenient to use. See How to Identify and Access Objects for more about names.

For Qt programs, the easiest and most reliable way of identifying an object in code is to set an object name in C++ for all the objects of interest (using the QObject::setObjectName method), and then in test scripts use a real (multi-property) name specifying the object's objectName and its type. For example:

textEdit = findObject("{objectName='ConfigEditor' type='QTextEdit'}")

var textEdit = findObject("{objectName='ConfigEditor' type='QTextEdit'}");

my $textEdit = findObject("{objectName='ConfigEditor' type='QTextEdit'}");

textEdit = findObject("{objectName='ConfigEditor' type='QTextEdit'}")

set textEdit [findObject "{objectName='ConfigEditor' type='QTextEdit'}"]

It is rare that an AUT has a unique name for every single widget. Sometimes we must identify unnamed objects. This can be done using symbolic names or by matching an object's unique set of property values. The necessary information can be obtained using the Spy tool (How to Use the Spy). This tool can provide an object's symbolic name and its property-based (real) name. Another approach is to create a dummy test, interact with the objects of interest and then look in Squish's object map to see the names that Squish uses, and copy any that are needed.

Here's an example that shows both approaches for finding an unnamed object of type QTextEdit. The object is in a QMainWindow whose title is "My App":

# symbolic name
textEdit = waitForObject(":MyApp_QTextEdit")
# real (multi-property) name
textEdit = waitForObject("{type='QTextEdit' unnamed='1' " +
        "visible='1' window=':MyApp_MainWindow'}")

// symbolic name
var textEdit = waitForObject(":MyApp_QTextEdit");
// real (multi-property) name
var textEdit = waitForObject("{type='QTextEdit' unnamed='1' " +
        "visible='1' window=':MyApp_MainWindow'}");

# symbolic name
my $textEdit = waitForObject(":MyApp_QTextEdit");
# real (multi-property) name
my $textEdit = waitForObject("{type='QTextEdit' unnamed='1' " .
        "visible='1' window=':MyApp_MainWindow'}");

# symbolic name
textEdit = waitForObject(":MyApp_QTextEdit")
# real (multi-property) name
textEdit = waitForObject("{type='QTextEdit' unnamed='1' " +
        "visible='1' window=':MyApp_MainWindow'}")

# symbolic name
set textEdit [waitForObject ":MyApp_QTextEdit"]
# real (multi-property) name
set textEdit [waitForObject "{type='QTextEdit' unnamed='1' \
        visible='1' window=':MyApp_MainWindow'}"]

The Object waitForObject(objectOrName) function waits for the identified object to be ready (visible and enabled) and then returns a reference to it.

On the whole it is best to use symbolic names since they are more robust in the face of AUT changes, since they only require us to update the Object Map rather than our test script code if an object's properties change. (Note that for most GUI toolkits the type property is mandatory when using real names.)

Constructors, Functions and Properties

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

Here are some simple examples:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Functions and Properties (macOS)

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

Here are some examples to illustrate the usage.

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

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

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

# call an instance method
s.characterAtIndex_(1)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# call an instance method
s.characterAtIndex_(1)

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

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

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

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

# call an instance method
invoke $s characterAtIndex_ 1

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

Conversion Functions, RTTI

In Squish, we have different ways to convert and cast, depending on what kind of value we are working with. In short,

1. cast() can be used for converting values or pointers.
2. object.convertTo() is for converting basic types, and value types related to QVariant.
3. castToQObject() is specifically for downcasting QObject-pointers/references in Squish for Qt using Run-Time Type Identification (RTTI).
4. typeName() (or in Python, className()) is a function you can call to get the object's type name at runtime.

Grouping test results into sections

test.startSection(title)

test.startSection(title, description)

test.endSection()

These functions can be used to group test results into logical units. A set of comparison or log/warning statements can be enclosed in startSection/endSection to have it logged as a distinct result section. The squishide will display result sections as a nested set of test results. Executing tests on the commandline will, except when the XML3 report generator is used, get log messages added to the test report whenever a section starts or ends.

Miscellaneous Functions

Object Access Functions

Synchronization Functions

Interaction Functions

Low-Level Functions

Debugging Functions

Verification Functions

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

Comparing Files