Qt Convenience API

Qt Convenience Function Parameters

Some of Qt's convenience functions can take a modifierState argument which indicates which special keys are pressed at the time of a mouse click. And some of the functions can also take a button argument which indicates which mouse button was clicked.

The modifierState can be one or more of the following: Qt.NoModifier, Qt.AltModifier, Qt.ControlModifier, Qt.KeypadModifier, Qt.MetaModifier, Qt.ShiftModifier. If more than one is used they must be OR-d together, for example, Qt.AltModifier|Qt.ShiftModifier. The form shown here works for Python and JavaScript. For Perl and Ruby replace the period with two colons, e.g., Qt::ControlModifier, and for Tcl use the enum function, e.g., enum Qt ControlModifier.

The button can be any one of: Qt.NoButton, Qt.LeftButton, Qt.MidButton, Qt.RightButton.

• For Perl use the following syntax: Qt::LeftButton.
• For Ruby use the following syntax: Qt::LEFT_BUTTON.
• For Tcl use the following syntax: enum Qt LeftButton.

Native Dialogs on KDE

To ensure the most reliable recording and replaying of tests, Squish uses Qt's own dialogs (e.g., for choosing colors, files, and fonts), rather than the underlying platform's native dialogs.

Unfortunately, on KDE, Qt uses the KDE dialogs and this can cause problems when developing cross-platform test scripts. The solution is to set the QT_PLATFORM_PLUGIN environment variable to an invalid value, such as QT_PLATFORM_PLUGIN=nonesuch. This can be done, for instance, in the squishide's Test Suite Settings view's Environment section.

Qt Convenience Functions

Here are some quick links to the Qt Convenience API's functions:

activateItem(itemObject)

activateItem(objectOrName, itemText)

This function activates the specified itemObject, or the item specified by itemText in the popup menu, context menu, or menu bar denoted by objectOrName.

The ampersand characters (&) that indicate keyboard shortcuts should not be included in the item text. If a character in a string is formatted with an underscore (_), meaning that the text inside the program contains an &, write the text without special characters or formatting. For example, for "&Add", write "Add".

activateLink(objectOrName, Url)

This function activates the link with the URL address specified Url inside the objectOrName widget. The function works for QTextBrowser and QLabel and its subclasses.

QObject castToQObject(object)

This function casts the object to a QObject. The object must be a subclass of QObject and QGraphicsItem—or a class derived from QGraphicsItem—and where QObject is inherited first. It is not necessary to use this function for QGraphicsObjects and QGraphicsWidgets since Squish already knows that these are both QObjects and QGraphicsItems at the same time.

Unfortunately QGraphicsItem does not provide support for introspection. This means that although Squish provides full access to all the built-in QGraphicsItem classes and their properties and methods—including their QObject properties and methods if they inherit QObject and the castToQObject function is used—none of the properties or methods you add to your own QGraphicsItem subclasses can be accessed by Squish.

For examples of testing Qt's graphics/view classes see How to Test Graphics Views, Graphics Scenes and Graphics Items.

clickButton(objectOrName)

This function clicks the specified objectOrName button.

clickItem(objectOrName, itemOrIndex, x, y, modifierState, button)

This function clicks the mouse on the item with the specified itemOrIndex inside the given objectOrName view widget. This function is typically used to access items inside views such as lists, tables, and trees.

For tables the itemOrIndex is a string with the format row/column, e.g., "4/21". For the tree views the itemOrIndex is a list of segments separated by the "." character. Each segment may optionally contain a _X suffix where X is interpreted as 1-base occurrence index. If any of the involved tree items contains the ".","_" or "\" characters in its text, these characters need to be escaped in the itemOrIndex as "\.","\_" and "\\" respectively in order to avoid being iterpreted as special characters. (Note that the script interpreter may require additional escaping for the "\" character.) The sequence of the segments corresponds to the tree path of the returned item. For example the "Item1.Sub\.ItemX_3.Leaf" finds an item with text "Leaf" that is a direct child of the third item with the text "Sub.ItemX" among the children of the root node with text "Item1". For other views it is the relevant item's text.

The click is made at position x and y (in the itemOrIndex item's coordinates) using the specified button and with the modifierState modifier state. It is safe to pass 0 for the coordinates and for the state. Normally, we would pass Qt.LeftButton for the button.

Squish supports this function for view widgets of type QAbstractItemView, and its subclasses, including QListView, QTableView, and QTreeView, and also older Qt3Support classes such as Q3IconView, Q3ListBox, Q3Table, and also classes derived from these types.

Qt Convenience Function Parameters lists valid values for the modifierState and the button arguments.

clickTab(objectOrName, tabText)

This function clicks on the tab that has the specified tabText on the objectOrName tab widget. (Note that &'s should not be included in the tabText, so if the tab's text is, say, "Advanced"—meaning that the text inside the program is really "&Advanced"—we just write plain "Advanced".)

doubleClick(objectOrName)

doubleClick(objectOrName, x, y, modifierState, button)

This overload double-clicks the mouse on the objectOrName widget at position x and y (in the objectOrName widget's coordinates) using the specified button and the modifierState modifier.

If the single-argument overload is used, the Qt.LeftButton without modifiers is used to double-click on the center of objectOrName.

Qt Convenience Function Parameters lists valid values for the modifierState and the button arguments.

doubleClickItem(objectOrName, itemText, x, y, modifierState, button)

This function double-clicks the mouse on the item with the specified itemText inside the given objectOrName view widget. The click is made at position x and y (in the itemText item's coordinates) using the specified button and with the modifierState modifier state.

Squish supports this function for view widgets of type QAbstractItemView, and its subclasses, including QListView, QTableView, and QTreeView, and also older Qt3Support classes such as Q3IconView, Q3ListBox, Q3Table, and also classes derived from these types.

Qt Convenience Function Parameters lists valid values for the modifierState and the button arguments.

doubleTap(objectOrName)

doubleTap(objectOrName, x, y)

doubleTap(objectOrName, x, y, modifiers)

This function double-taps on the objectOrName widget.

If x and y arguments (in the objectOrName widget's coordinates) have been provided, the taps will happen there, otherwise replay will happen at the center of the widget.

If the modifiers argument has been provided, the taps will happen with keyboard modifiers pressed, otherwise replay will happen without any keyboard modifiers being pressed.

Tapping is supported on objects of type QQuickItem and QWindow.

dragAndDrop(source_­object­Or­Name, sx, sy, target_­object­Or­Name, tx, ty, action)

This function performs a drag and drop operation. It begins by initiating a drag on the source_objectOrName widget starting at position sx and sy (in the source_objectOrName widget's coordinates), and then it does the drop on the target_objectOrName widget at position tx and ty (in the target_objectOrName widget's coordinates). The action is an integer (enum) which can be either Qt::CopyAction or Qt::LinkAction.

dragItemBy(objectOrName, x, y, dx, dy, modifierState, button)

This function performs a drag operation. It initiates a drag of the specified objectOrName widget starting at position x and y (in the objectOrName widget's coordinates), using the specified button and with the modifierState modifier state. The objectOrName widget is dragged by dx pixels horizontally and by dy pixels vertically.

dropOn(target_objectOrName, tx, ty, action)

This function performs a drop that was initiated by a call to the startDrag(source_objectOrName, sx, sy) function. It does the drop on the target_objectOrName widget at position tx and ty (in the target_objectOrName widget's coordinates). See dragAndDrop(source_­object­Or­Name, sx, sy, target_­object­Or­Name, tx, ty, action) for possible values of the action parameter.

Normally the dragAndDrop(source_­object­Or­Name, sx, sy, target_­object­Or­Name, tx, ty, action) function is used to perform a drag and drop in a single action. However, in some situations it may be necessary to move the mouse over a different object before the drop can take place. In such cases the test code would look something like this:

startDrag(sourceObject, sx, sy)
mouseMove(otherObject, x, y)
dropOn(targetObject, tx, ty, action)

flick(objectOrName, x, y, dx, dy, cdx, cdy)

This function performs a "flick" operation (a move or scroll on a QML Flickable). It initiates a flick of the specified objectOrName item—which must be a QML Flickable—starting with the mouse at position x and y (in the objectOrName item's coordinates) and moving the mouse by dx pixels horizontally and by dy pixels vertically. At the same time the position of the objectOrName item's contents is moved relative to its previous position by cdx pixels horizontally and by cdy pixels vertically.

gesture(objectOrName, touches)

This function plays a gesture. The specified objectOrName can refer to any object that is visible and serves for synchronization only. The specified touches refers to a GestureBuilder object, which can be retrieved using readGesture(gesture-file).

Gesture replay is supported on objects of type QWindow and QWidget.

hideKeyboard()

This function hides the on-screen keyboard when it is showing.

installEventHandler(eventName, handlerFunctionName)

installEventHandler(className, eventName, handlerFunctionName)

installEventHandler(object, eventName, handlerFunctionName)

This function installs an event handler that is applied to all objects of the className class or to the specified object or globally (if no className or object is specified). The script function named in handlerFunctionName (which can be passed as a string or as a function reference), will be called when an event of the eventName type occurs on an object of the className class, or to the specified object, or globally.

The eventName can be the name any standard Qt event type such as QKeyEvent event or QMouseEvent, or one of the Squish convenience event types listed below:

• Crash: This event occurs if the AUT crashes.
• DialogOpened: This event occurs when a top-level QDialog is shown.
• MainWindowOpened: This event occurs when a top-level QMainWindow is shown.
• MessageBoxOpened: This event occurs when a top-level QMessageBox is shown.
• Timeout: This event occurs when the Squish response timeout is reached.
• ToplevelWidgetOpened: This event occurs when any other kind of top-level widget is shown.

The function named in handlerFunctionName is called with a single argument—the object on which the event occurred.

For examples, see How to Use Event Handlers.

installLazySignalHandler(name, signalSignature, handlerFunctionName)

This function installs a Qt (not Unix) signal handler that eavesdrops on the object identified by the given symbolic or real name. The signalSignature must be the exact signature used in C++ with no parameter names—for example, "activated(int)" or "triggered(QAction*)". The handlerFunctionName (which must be passed as a string, not as a function reference), will be called whenever the specified widget emits the specified signal and will be passed a reference to the object that emitted the signal, followed by all the signal's arguments (if there are any).

In Perl the function name needs to be prefixed with the package name the function is declared in, otherwise calling the signal handler may fail. For functions in test.pl this prefix is main::.

This function is very flexible in that the object identified by the name does not have to exist at the time the function is called, since the object will be looked for whenever the signal is emitted. The price to be paid for this flexibility is that the use of this function can significantly slow down playback if the signal is emitted a lot. If possible it is better to use the less flexible installSignalHandler(objectOrName, signalSignature, handlerFunctionName) function instead.

Where possible the signal's arguments are passed as types that can be handled normally such as numbers, strings, or their actual Qt types such as QAction or QTableWidgetItem. However, some types are sent as plain Squish Objects; custom types and other unrecognized types are passed as strings.

installSignalHandler(objectOrName, signalSignature, handlerFunctionName)

This function installs a Qt (not Unix!) signal handler that eavesdrops on the specified objectOrName widget. The signalSignature must be the exact signature used in C++ with no parameter names—for example, "activated(int)" or "triggered(QAction*)". The handlerFunctionName (which must be passed as a string, not as a function reference), will be called whenever the specified widget emits the specified signal and will be passed a reference to the object that emitted the signal, followed by all the signal's arguments (if there are any).

As is usual with Squish functions, the objectOrName widget must exist at the time this function is called. This requirement is relaxed by the installLazySignalHandler(name, signalSignature, handlerFunctionName) function which can only accept a symbolic or real name, but of an object that need not exist when the function is called. Nonetheless, it is best to use this installSignalHandler function whenever possible since it is potentially a lot faster than the installLazySignalHandler(name, signalSignature, handlerFunctionName) function.

Where possible the signal's arguments are passed as types that can be handled normally such as numbers, strings, or their actual Qt types such as QAction or QTableWidgetItem. However, some types are sent as plain Squish Objects; custom types and other unrecognized types are passed as strings.

For an example, see How to Use Qt Signal Handlers.

longMouseClick(objectOrName, x, y, modifierState, button)

longMouseClick(objectOrName, x, y, button)

longMouseClick(objectOrName, modifierState, button)

longMouseClick(objectOrName, button)

longMouseClick(objectOrName)

This function clicks the mouse on the specified objectOrName widget with a fixed delay of about one second between pressing and releasing the mouse button. Apart from the delay this function behaves identical to mouseClick, see mouseClick(objectOrName, x, y, modifierState, button) for more details.

The longMouseClick function is supported on objects of type QQuickItem and QWindow.

longMouseDrag(objectOrName, x, y, dx, dy, modifierState, button)

This function performs a mouse drag operation with a fixed delay of about one second between pressing the mouse button and starting to move the mouse cursor. Apart from the delay this function behaves identical to mouseDrag. See mouseDrag(objectOrName, x, y, dx, dy, modifierState, button).

The longMouseDrag function is supported on objects of type QQuickItem and QWindow.

mouseClick(objectOrName, x, y, modifierState, button)

mouseClick(objectOrName)

This function clicks the mouse on the specified objectOrName widget. The click is made at position x and y (in the objectOrName widget's coordinates) using the specified button and with the modifierState modifier state.

If only the objectOrName is specified, the object is clicked in the middle by the Qt::LeftButton button and with no keyboard modifiers pressed.

If this function is used to click Q3ListView objects, Q3TableItem objects, or web objects inside QtWebKit objects, the modifierState and button parameters are optional.

Qt Convenience Function Parameters lists valid values for the modifierState and the button arguments.

mouseDrag(objectOrName, x, y, dx, dy, modifierState, button)

This function performs a mouse drag operation. It initiates a mouse drag of the specified objectOrName widget starting at position x and y (in the objectOrName widget's coordinates), using the specified button and with the modifierState modifier state. The objectOrName widget is dragged by dx pixels horizontally and by dy pixels vertically.

See longMouseDrag(objectOrName, x, y, dx, dy, modifierState, button) when the mouse drag needs to be executed "more slowly", with more delay in between the individual steps of the drag.

Qt Convenience Function Parameters lists valid values for the modifierState and the button arguments.

mouseWheel(objectOrName, x, y, xdegrees, ydegrees)

This function performs a mouse wheel operation, emulating rotation of the horizontal and/or vertical wheel of a mouse. Replay happens on the specified objectOrName object at position x and y (in the objectOrName objects's coordinates), using the specified xdegrees and ydegrees values for the amount of wheel rotation.

The mouseWheel function is supported on objects of type QQuickItem and QWindow.

nativeMouseClick(objectOrName, x, y, modifierState, button)

This function simulates a native mouse click on the specified objectOrName widget at position x and y (in the objectOrName widget's coordinates), using the specified button and with the modifierState modifier state.

Qt Convenience Function Parameters lists valid values for the modifierState and the button arguments.

openContextMenu(objectOrName, x, y, modifierState)

This function simulates the user opening a context menu by clicking the specified objectOrName widget at position x and y (in the objectOrName widget's coordinates), and with the modifierState modifier state.

Qt Convenience Function Parameters lists valid values for the modifierState argument.

openItemContextMenu(objectOrName, itemText, x, y, modifierState)

This function simulates the user opening a context menu by clicking the menu option with the specified itemText inside the objectOrName view widget at position x and y (in the itemText item's coordinates), and with the modifierState modifier state.

Squish supports this function for view widgets of type QAbstractItemView, and its subclasses, including QListView, QTableView, and QTreeView, and also older Qt3Support classes such as Q3IconView, Q3ListBox, Q3Table, and also classes derived from these types.

Qt Convenience Function Parameters lists valid values for the modifierState argument.

pressAndHold(objectOrName, x, y)

pressAndHold(objectOrName, x, y, dx, dy)

This function performs a press and hold operation on the specified objectOrName item—starting with the mouse at position x and y (in the objectOrName item's coordinates) and optionally moving the mouse by dx pixels horizontally and by dy pixels vertically if these offsets are specified. (Note that dx and dy are relative to the starting mouse position in QML scene coordinates, not in objectOrName item coordinates which is normally the case.)

The pressAndHold function is supported on objects of type QDeclarativeItem.

The press and hold operation performed by this function is similar to what the dragItemBy(objectOrName, x, y, dx, dy, modifierState, button) function does, except for the hold (the initial pause when the mouse is first pressed down). QML scenes support press and hold by using an invisible MouseArea item that is overlaid on top of one or more of the scene's QML items. Squish doesn't record actions for invisible items so for a press and hold it records the item at the mouse (or finger for touch screens) position that is actually under the MouseArea.

Other Object Types

For objects of type QQuickItem, you can use either longMouseClick(objectOrName, x, y, modifierState, button) or longMouseDrag(objectOrName, x, y, dx, dy, modifierState, button).

For other objects it should be possible to emulate the effect of pressAndHold() by using a combination of the following functions:

• snooze(seconds)
• mouseMove(x, y)
• mousePress()
• mouseRelease()

For example:

function main()
{
    //...

    mouseMove(waitForObject(":target_object_name"), 5, 5);
    mousePress(waitForObject(":target_object_name"));
    snooze(3);
    mouseRelease(waitForObject(":target_object_name"));

    //...
}

qmlContext(object)

This function returns the QQmlContext for the object, or null if no context has been set. This is equivalent to calling the C++ function QQmlEngine::contextForObject. A QML Context is a container for properties and allows data to be exposed to QML from C++. For an example of its use, see this blog post.

qmlEngine(object)

Returns the QQmlEngine associated with object or null if the object is not associated with any QML Engine. This is equivalent to QQmlEngine::contextForObject(object)->engine(), but more efficient. The QQmlEngine class provides an environment for instantiating QML components.

readGesture(gesture-file)

This function opens a gesture file from a test suite directory and returns a GestureBuilder object. This can then be passed to gesture(objectOrName, touches). The specified gesture-file refers to the filename.

scrollTo(objectOrName, position)

This function scrolls the objectOrName widget to the given position. The position is an absolute value (i.e., a pixel offset).

sendEvent(eventName, objectOrName, ...)

This function sends an event of type eventName to the objectOrName widget. All the other arguments (...) are passed on to the event constructor—they are typically coordinates, button states, and similar. The eventName is any of the Qt events supported by Squish — this includes all the most commonly used ones, such as, "QCloseEvent", "QHideEvent", "QKeyEvent", "QMouseEvent", "QMoveEvent", "QShowEvent", "QTabletEvent", and "QWheelEvent".

setFocus(objectOrName)

This method changes the keyboard input focus to the object specified by objectOrName.

Changing the keyboard input focus is currently supported on objects of type QQuickItem, QWidget and QWindow.

setMouseTracking(className, onOrOff)

This function can be used in init files to disable or enable the recording of MouseMove events for certain widget classes. The class to disable or enable mouse tracking for is specified by the className parameter. Pass an onOrOff parameter value of true to enable mouse tracking or of false to disable mouse tracking. (By default mouse tracking is off.)

Wrapper-Specific Initialization

The init files are Tcl scripts that are registered with the squishrunner and then read before starting any tests. The registration process is explained in Configuring squishrunner. Although init files must be written in Tcl, this does not affect the scripting language used for test suites, which may be in any of the scripting languages that Squish supports.

We can have as many init scripts as we like for each GUI toolkit or we can put all the initialization statements in a single Tcl script per toolkit. However many init scripts we use, they must all be registered with the squishrunner.

Example

setMouseTracking ScribbleArea true

This sets mouse tracking on for an AUT's custom ScribbleArea class.

To make this work, we must tell Squish to execute a file that contains this Tcl script at startup when it is used to test a Qt-based AUT:

squishrunner --config addInitScript Qt /home/harri/qt_init1.tcl

An absolute path must be used.

setRecordMouseDrag(className, onOrOff)

This function can be used in init files to disable or enable the recording of mouseDrag statements for certain widget classes. The class to disable mouse dragging for is specified by the className parameter. Pass an onOrOff parameter value of true to enable mouse drag recording or of false to disable mouse drag recording. (By default mouse drag recording is on.)

See also Wrapper-Specific Initialization.

The init files are Tcl scripts that are registered with the server and then read before starting any tests. The registration process is explained in Configuring squishrunner.

Example

setRecordMouseDrag ScribbleArea false

This switches off mouse drag recording for an AUT's custom ScribbleArea class.

To make this work, we must tell Squish to execute a file that contains this Tcl script at startup when it is used to test a Qt-based AUT:

squishrunner --config addInitScript Qt /home/harri/qt_init2.tcl

An absolute path must be used.

setWindowState(objectOrName, windowState)

This function sets the state of the given objectOrName window to that specified by the windowState enumeration.

Note that using this function only makes sense for top-level windows.

Valid window state values are: WindowState.Fullscreen, WindowState.Maximize, WindowState.Minimize, and WindowState.Normal.

The form shown above works for Python and JavaScript.

For Perl use this: WindowState::Maximize, etc.

For Ruby use this: WindowState::MAXIMIZE, etc.

For Tcl use this: enum WindowState Maximize, etc.

spinUp(objectOrName)

This function clicks the "up" button on the objectOrName spinbox. The function works for QAbstractSpinBox and its subclasses, such as QSpinBox and QDoubleSpinBox.

spinDown(objectOrName)

This function clicks the "down" button on the objectOrName spinbox. The function works for QAbstractSpinBox and its subclasses, such as QSpinBox and QDoubleSpinBox.

startDrag(source_objectOrName, sx, sy)

This function initiates a drag on the source_objectOrName widget starting at position sx and sy (in the source_objectOrName widget's coordinates). The drop can be done using the dropOn(target_objectOrName, tx, ty, action) function.

tapObject(objectOrName)

tapObject(objectOrName, x, y)

tapObject(objectOrName, x, y, modifiers)

This function taps on the specified objectOrName widget. The x and y coordinates as well as the modifiers keyboard modifiers are optional. If they are not specified, the tap is made in the center of the widget using no keyboard modifiers. On the other hand, if the additional coordinate parameters are given, the tap is made at position x and y in the objectOrName widget's coordinates.

Tapping is supported on objects of type QQuickItem, QWindow and QWidget.

touchAndDrag(objectOrName, x, y, dx, dy)

touchAndDrag(objectOrName, x, y, dx, dy, modifiers)

touchAndDrag(objectOrName, x, y, dx, dy, modifiers, delayAfterPress)

This function performs a touch-based drag operation. It initiates a touch drag of the specified objectOrName widget starting at position x and y (in the objectOrName widget's coordinates). The objectOrName widget is dragged by dx pixels horizontally and by dy pixels vertically.

If specified, the keyboard modifiers provided in modifiers are set while performing the drag.

If specified, the number of milliseconds provided in delayAfterPress is waited before the drag starts.

Touch-based dragging is supported on objects of type QQuickItem and QWindow.

touchPress(objectOrName, x, y)

touchPress(objectOrName, x, y, modifiers)

This function performs a touch-based press operation. It replays a touch press on the specified objectOrName widget at position x and y (in the objectOrName widget's coordinates).

If specified, the keyboard modifiers provided in modifiers are set while performing the operation.

Since the object and Qt itself rely on press and release operations to always happen in pairs a call to touchPress should always be paired with a call to touchRelease to ensure a consistent state. For most cases using just tapObject is sufficient.

A single touch press can be performed on objects of type QQuickItem and QWindow.

touchRelease(objectOrName, x, y)

touchRelease(objectOrName, x, y, modifiers)

This function performs a touch-based release operation. It replays a touch release on the specified objectOrName widget at position x and y (in the objectOrName widget's coordinates).

If specified, the keyboard modifiers provided in modifiers are set while performing the operation.

Since the object and Qt itself rely on press and release operations to always happen in pairs a call to touchRelease should always be preceded by a call to touchPress to ensure a consistent state. For most cases using just tapObject is sufficient.

A single touch release can be performed on objects of type QQuickItem and QWindow.

type(objectOrName, text)

This function types the specified text (as if the user had used the keyboard) into the objectOrName editable widget. If the text is surrounded by angle brackets (<>), it is interpreted as a key combination, e.g "<Ctrl+Return>". The input is case-sensitive, so type(object, "R") is different from type(object, "r"). (For a list of the supported special keys see the nativeType(keys) function's documentation.)

Unlike nativeType(keys), type() treats Ctrl and Command as the same key on all platforms. This means that you can write type("<Ctrl+c>") in a test script and it will result in Ctrl+r on Linux and Windows and in Command+r on macOS. In turn, to make Squish press the actual Ctrl key on macOS, you need to use Qt terminology: type("<Meta+r>").

uninstallEventHandler(eventName, handlerFunctionName)

uninstallEventHandler(className, eventName, handlerFunctionName)

uninstallEventHandler(object, eventName, handlerFunctionName)

This function uninstalls an event handler that has been previously installed using installEventHandler(eventName, handlerFunctionName).

uninstallSignalHandler(objectOrName, signalSignature, handlerFunctionName)

This function uninstalls a signal handler that has been previously installed using installSignalHandler(objectOrName, signalSignature, handlerFunctionName).

uninstallLazySignalHandler(name, signalSignature, handlerFunctionName)

This function uninstalls a signal handler that has been previously installed using installLazySignalHandler(name, signalSignature, handlerFunctionName).

waitForSignal(object, signalSignature)

waitForSignal(object, signalSignature, timeoutMSec)

This function waits for Qt (not Unix!) signal to be emitted by the given object. The object is a reference to object and can be obtained from one of the functions returning object references (e.g. Object waitForObject(objectOrName) or Object findObject(objectName). The signalSignature must be a string, and contain the exact signature used in C++ with no parameter names (see installSignalHandler(objectOrName, signalSignature, handlerFunctionName) for examples of valid signatures). The duration of the waiting loop is defined by the testSettings.waitForObjectTimeout property or if the optional timeoutMSec parameter is used, that many milliseconds. If the signal doesn't arrive within the given timeout, (catchable) RuntimeError exception is raised.

waitForSignal(waitForObject(names.window_Window), "titleChanged()")

waitForSignal(waitForObject(names.windowWindow), "titleChanged()")

waitForSignal(waitForObject($Names::window_window), "titleChanged()");

waitForSignal(waitForObject(Names::Window_Window), "titleChanged()")

invoke waitForSignal [waitForObject $names::window_Window] "titleChanged()"

QWebView Class

Squish provides additional support for the QWebView class in the form of three additional methods.

Object QWebView.clearObjectCache()

This function clears the cache of objects that are being looked up using hierarchical names like DOCUMENT.HTML1.BODY1.DIV2. See also clearObjectCache().

Object QWebView.evalJS(code)

This function evaluates the JavaScript code string in the QWebView's context (i.e., in the context of the active QWebView page). The result of the last statement in the code is returned as a string. See also How to Use evalJS.

Object QWebView.retrieveJSObject(code)

This function evaluates the JavaScript code string in the QWebView's context (i.e., in the context of the active QWebView page). The result of the last statement in the code is returned as a primitive value, like a string or number, or a reference to a JsObject in the page. (See also How to Use retrieveJSObject and JsObject retrieveJSObject(javascriptcode).)

Boolean QWebView.isPageLoaded()

This function returns true if the page has been completely loaded; otherwise it returns false. A complete and successful load implies that all of the page's objects can potentially be accessed. This function can be used with the Boolean waitFor(condition) function to wait for a page to be loaded before accessing it from a test script.

Since page loading, HTTP requests, and so on, are asynchronous, even after a call to the isPageLoaded function returns true it is essential that the Object waitForObject(objectOrName) function (or another wait function) is used to ensure that the specific object or objects of interest are ready to be accessed. Also, it may be necessary to pass a longer timeout to the Object waitForObject(objectOrName) function than the default 20 seconds (20 000 milliseconds). See also How to Synchronize Web Page Loading for Testing.

QWebView.loadUrl(url)

This function changes the QWebView's current page to the new url.

QML Extension API

Qt applications that utilize QtQuick can dynamically load QML code, including custom QML objects, so it is quite possible that AUTs that use QML will have QML objects that are unknown to Squish. This isn't a problem since Squish can still record and playback interactions with such objects, but will do so in terms of the primitives they are built from (e.g. Rectangle or Text items), rather than with the actual (logical) item types (e.g., CustomButton).

The QML Extension API makes it possible to make Squish treat certain custom QML object types as "black boxes" so that recording and playback can work at a higher level (i.e., in terms of the custom objects themselves rather than with the primitives that they are built from). Squish comes with a small example that makes use of some of the QML Extension APIs and that shows how to implement a SquishHook for a custom Calculator Button type: SQUISHDIR/examples/qt5/calqlatr/extension/Calqlatr.qml.

Squish also includes a more substantial QML Extension for support of QtQuick Controls, located in SQUISHDIR/lib/extensions/qt/qtquick/ControlsExt.qml.

The Format of a QML Extension

QML Extensions are standard QML scripts in .qml files (using the UTF-8 encoding), and using some additional functionality provided by Squish. For QtQuick 1.x the structure of a Squish QML extension looks like this:

import Qt 4.7
import com.froglogic.squish.qml 0.1

SquishHook {
    // extension code...
}

For QtQuick 2.x the basic structure of a QML extension is:

import QtQuick 2.0
import com.froglogic.squish.qtquick 0.1

SquishHook {
    // extension code...
}

Installing QML Extensions

Squish automatically looks in the SQUISHDIR/lib/extensions/qt/qml directory for extension files targeting QtQuick 1.x and into the SQUISHDIR/lib/extensions/qt/qtquick directory for QtQuick 2.x extension files. All that is needed to "install" a new QML extension is to move or copy it into one of these directories. It is also possible add an additional directory for Squish to search for QML extensions: Set the SQUISH_QML_EXTENSION_PATH environment variable (which you may need to create) to the directory where you want to keep your QtQuick 1.x QML extensions. For QtQuick 2.x rather set the SQUISH_QTQUICK_EXTENSION_PATH environment variable to the directory where you keep your QML extensions.

QML Extension API Documentation

Squish's QML Extension API consists of a single item of type SquishHook. This item provides various properties and functions which are listed below. A custom QML extension can make use of these properties and functions—and in some cases override them. In addition, Squish provides some helper functions to make writing QML extensions easier.

The QtQuick 1.x API uses the QML basic types and elements specified in the Qt 4.8 Reference Documentation.

The QtQuick 2.x API uses the QML basic types and items specified in the Qt 5.x Reference Documentation.

bool isCustomQmlType(item)

This function returns whether the given item of type Item is a custom type. (Every QML item that introduces new properties is considered to be a custom QML type by Qt—and by this function.)

bool isQmlType(item, className)

This function returns whether the given item of type Item inherits the class specified by the className string.

bool itemHasContents(item)

This function returns whether the given item of type Item has the QQuickItem::ItemHasContents flag set. This is a helper function to access this particular flag from within QML. It can serve as a hint whether an item should be ignored by default. See also Flag enum.

String qmlId(item)

This function returns the id for the given item or an empty string if item has no id set.

String qmlType(item)

This function returns the given item of type Item's class name if it is a declarative type; otherwise it returns an empty string.

String source(item)

This function returns the given item of type Item's URL if the item was loaded from a local file or remotely; otherwise it returns the item's containing component's URL (which might be an empty string).

SquishHook

The SquishHook class is an abstract class for extending in custom QML Extensions.

readonly property var SquishHook.blacklistedTypes

This variable can contain a list of strings, which are QML types you wish to have ignored by this extension.

readonly property var SquishHook.containerTypes

Some types can serve as containers for others. If you are interacting with a child of a container type, you should see a container= in the real name generated by Squish for that child, pointing to its container.

In this property, you can specify a list of strings, containing type names of classes which can be containers for all of their children.

This property is used in simple cases where a given class can always be a container type based on its class name.

If you need to look at properties to determine whether something is a container for a particular item, you should override the containerFor() function instead of using this property.

Item SquishHook.containerFor(item)

This function returns the container the given item of type Item is in (itself of type Item, e.g., a ListView or a GridView) which is normally also the item's parent; otherwise it returns null if the item isn't in a container.

You can implement your own version of this function in your QML extension, in which case for any given item you must return one of the following three values: An Item (possibly of your own custom type) which contains the given item. Or null, if you don't want the given item to have a container (in which case the view will be considered to be the item's container). Or, the special value, unhandled, if you don't want this extension to handle the given item (e.g., because it is a standard Item type that you want Squish to handle), since unhandled tells Squish to handle the item itself.

StringList SquishHook.extraPropertiesFor(item)

This function returns a list of the property names for the given item of type Item that should be taken into account when generating a Squish object name for the item. (This function can be used to achieve the same kind of control over Squish's naming as editing the Qt wrapper descriptor file—for which see, Object Name Generation—but with finer control possible since property names can be considered on a per-item basis, not just on a per-type basis.)

You can implement your own version of this function in your QML extension, in which case for any given item you must return either: A list of property names (as an array of strings) whose values should be used to create the Squish object name for the given item. Or, the special value, unhandled, if you don't want this extension to handle the given item (e.g., because it is a standard Item type that you want Squish to handle), since unhandled tells Squish to handle the item itself.

bool SquishHook.isIgnored(item)

This function returns false if the given item of type Item should be taken notice of by Squish — for example, visible and available for picking in the Spy and recorded.

You can implement your own version of this function in your QML extension, in which case for any given item you must return one of the following three values: The value false if you want Squish to take notice of the given item, or true if you want Squish to ignore the item, or the special value, unhandled, if you don't want this extension to handle the given item (e.g., because it is a standard Item type that you want Squish to handle), since unhandled tells Squish to handle the item itself.

bool SquishHook.isItemReady(item)

This function returns true if the given item of type Item is ready to be interacted with, that is, is visible, enabled, and is in a stable state (e.g., it is not being or about to be animated).

You can implement your own version of this function in your QML extension, in which case for any given item you must return one of the following three values: The value true if the given item is ready for interaction, or false the item isn't ready, or the special value, unhandled, if you don't want this extension to handle the given item (e.g., because it is a standard Item type that you want Squish to handle), since unhandled tells Squish to handle the item itself.

readonly property var SquishHook.objectNameProperties

This variable is expected to be a {dictionary} of key:value pairs, where the key is a "string", the QML type name, and the value is a [list] of "strings", property names of that type, that should be used to form the real name when it is added to the object map (at record time).

This QML-only functionality is similar to the qtwrapper_descriptors.xml which works on all Qt types.

int SquishHook.priority

This property holds a priority value for the QML extension and has a default value of 0. Squish accesses QML extensions in priority order from highest to lowest.

You can implement your own version of this property in your QML extension to give your extension a priority value higher than 0, e.g., to increase its priority.

String SquishHook.propertyFor(item, property)

This function returns a property value (as a string) for the given item of type Item's property (specified as a string).

You can implement your own version of this function in your QML extension, in which case for any given item and property you must return either: A string property value, or the special value, unhandled, if you don't want this extension to handle the given item (e.g., because it is a standard Item type that you want Squish to handle), since unhandled tells Squish to handle the item itself.

Note that this function is not called when the object.property("propertyName") function is used inside a test script.

readonly property var SquishHook.whitelistedTypes

This variable can contain a list of strings, which are QML types you wish Squish to prefer (over its more primitive children), when it is picking objects.

GestureBuilder

Objects of this type hold the touch strokes information needed to replay gesture(objectOrName, touches). An instance of this class is returned by readGesture(gesture-file). Strokes are defined by screen coordinates points, pressure and touch size.

int GestureBuilder.areaWidth

The width of the area in which this gesture is defined. This will be the device or emulator screen width.

int GestureBuilder.areaHeight

The height of the area in which this gesture is defined. This will be the device or emulator screen height.

All GestureBuilder methods listed in the Gesture creation and Gesture manipulation section, return the GestureBuilder object itself, unless specified differently.

Gesture creation

This section lists the methods for manually creating a GestureBuilder object.

GestureBuilder(width, height, unit)

GestureBuilder(xml)

Two constructor functions for creating a GestureBuilder object. The width and height are the target screen size. The unit can be either 0 or 1, meaning respectively in pixels or millimeters. The constants GestureBuilder.Pixel and GestureBuilder.MilliMeter can be used as well.

The second constructor function constructs a GestureBuilder object by passing a string containing XML, which should be in the same format as the recorded gesture files.

Object GestureBuilder.addStroke(x, y)

Object GestureBuilder.addStroke(startTime, x, y)

Object GestureBuilder.addStroke(startTime, x, y, pressure)

Object GestureBuilder.addStroke(startTime, x, y, pressure, size)

Starts a new stroke. The whole movement of one finger or pen from touch down to releasing the screen is called a stroke. The touch down coordinate is (x, y). For the non-first stroke, a time offset can be specified in milliseconds using the startTime argument. Strokes cannot be disjointed in time, at least one finger or pen has to be down during the whole gesture. The maximum simultaneous touches is device dependent (See QTouchDevice::maximumTouchPoints()).

Finally, the pressure and size are relative messure values for respectively pen or finger pressure and size. These should be between 0.0 and 1.0 and when omitted defaults to 0.25.

Object GestureBuilder.curveTo(duration, controlX, controlY, endX, endy)

Object GestureBuilder.curveTo(duration, control1X, control1Y, control2X, control2Y, endX, endy)

Adds a bézier curve movement to the latest added stroke in duration milliseconds. The curve starts with the end coordinate of the last added movement or, if none added to the stroke, the stroke touch down coordinate. The end coordinate is specified with endX and endY. One or two so called control points can be used.

Object GestureBuilder.lineTo(duration, endX, endy)

Adds a line movement to the latest added stroke in duration milliseconds. The line starts with the end coordinate of the last added movement or, if none added to the stroke, the stroke touch down coordinate. The end coordinate is specified with endX and endY.

Object GestureBuilder.build()

Creates the gesture from the added strokes and movements. After calling this method, no strokes or movements can be added.

Gesture manipulation

Object GestureBuilder.accelerate(factor)

Changes stroke speed given a factor. A factor between 0.0 and 1.0 slows down the gesture, above 1.0 will speed it up.

Object GestureBuilder.rotate(degrees)

Object GestureBuilder.rotate(degrees, originX, originY)

Rotates the strokes. The degrees is the agle in degrees in a counter clockwise direction. The originX and originY define the origin of the rotate operation. If omitted, the area center is taken as origin.

Object GestureBuilder.scale(scale)

Object GestureBuilder.scale(scaleX, scaleY)

Object GestureBuilder.scale(scaleX, scaleY, originX, originY)

Changes the size of the strokes. The scaleX is the scale factor in the horizontal direction and scaleY in the vertical direction. The originX and originY define the origin of the scale operation. If omitted, the area center is taken as origin. When also scaleY is omitted, then the scaling is homogeneous in both directions.

Object GestureBuilder.translate(x, y)

Moves the strokes. The x and y specifies the movement. A positive value for x moves the strokes to the right and a positive value for y moves the strokes downwards.