Using Squish as a module in other Python scripts, applications

Last edited on

Overview

It is possible to automate user interfaces using the Squish API from existing Python scripts using a special Python module called squishtest.

Obtaining a Squish package with the correct Python configuration

The squishtest module functionality is available free of charge and is included in all Squish packages.

However, if you are using a Python installation with a different point-release (or architecture) from what is included in the Squish package, the Python module will not be compatible with your Python installation. In this case, you need a Squish package custom built with a Python version that matches your Python installation.

To provide such a package we need the following from you:

To determine the exact version and information about UCS-2 or UCS-4 please send us the output generated by running the following command:

python -c "import sys; print sys.version; print sys.maxunicode"
Execute in a shell

Using the squishtest module in Python scripts

A simple Python script using squishtest might look like this:

import squishtest

import names

# Must set a test result:
squishtest.setTestResult("xml3", "testresultdir")

# Must specify which GUI toolkit support Squish
# should use for this application.
#
# This depends on the Squish edition; possible values:
#
#  Android, iOS, Java, Mac, Qt, Tk, Web, Windows
squishtest.testSettings.setWrappersForApplication("addressbook", ["Qt"])

# Launch the application:
squishtest.startApplication("addressbook")

# Start interacting with the application...
squishtest.mouseClick(squishtest.waitForObject(...))
myscript.py

Setup

The above example test script can be executed with a plain Python interpreter, as long as the environment is configured correctly for finding the squishtest module, its shared library dependencies and a few other items, as shown below.

Apple macOS

Before the squishtest module can be used you need to configure the Python that you want to use for Squish, as explained in this article:

Changing the Python installation used by Squish binary packages

# Path to Squish package:
export SQUISH_DIR=/home/myuser/squish-6.7.2


# To find the "squishtest" module:
export PYTHONPATH=$SQUISH_DIR/lib:$PYTHONPATH


# To find shared libraries squishtest depends on:
export DYLD_LIBRARY_PATH=$SQUISH_DIR/lib:$LD_LIBRARY_PATH


# To find these Squish modules:
#  objectmaphelper (possibly used in names.py)
#  remotesystem
#  screen
#  toplevelwindow
export PYTHONPATH=$SQUISH_DIR/lib/python:$PYTHONPATH


# Stop squishserver (if still running):
"$SQUISH_DIR/bin/squishserver" --stop 2>/dev/null


# Launch squishserver in background:
"$SQUISH_DIR/bin/squishserver" --verbose &


# Execute Python script that uses squishtest:
python3 myscript.py


# Stop squishserver:
"$SQUISH_DIR/bin/squishserver" --stop 2>/dev/null
On macOS (Execute in a shell/terminal

Linux (Unix)

# Path to Squish package:
export SQUISH_DIR=/home/myuser/squish-6.7.2


# To find the "squishtest" module:
export PYTHONPATH=$SQUISH_DIR/lib:$PYTHONPATH


# To find shared libraries squishtest depends on:
export LD_LIBRARY_PATH=$SQUISH_DIR/lib:$LD_LIBRARY_PATH


# To find these Squish modules:
#  objectmaphelper (possibly used in names.py)
#  remotesystem
#  screen
#  toplevelwindow
export PYTHONPATH=$SQUISH_DIR/lib/python:$PYTHONPATH


# Stop squishserver (if still running):
"$SQUISH_DIR/bin/squishserver" --stop 2>/dev/null


# Launch squishserver in background:
"$SQUISH_DIR/bin/squishserver" --verbose &


# Execute Python script that uses squishtest:
python myscript.py


# Stop squishserver (if still running):
"$SQUISH_DIR/bin/squishserver" --stop 2>/dev/null
On Unix (not macOS; execute in a shell/terminal

Microsoft Windows

:: Path to Squish package:
set SQUISH_DIR=C:\Users\myuser\squish-6.7.2


:: To find the "squishtest" module and shared libraries
:: it depends on:
set PYTHONPATH=%SQUISH_DIR%\bin;%PYTHONPATH%


:: To find these Squish modules:
::  objectmaphelper (possibly used in names.py)
::  remotesystem
::  screen
::  toplevelwindow
set PYTHONPATH=%SQUISH_DIR%\lib\python;%PYTHONPATH%


:: Stop squishserver (if still running):
"%SQUISH_DIR%\bin\squishserver" --stop >nul


:: Launch squishserver in background:
start "" "%SQUISH_DIR%\bin\squishserver" --verbose


:: Execute Python script that uses squishtest:
python myscript.py


:: Stop squishserver:
"%SQUISH_DIR%\bin\squishserver" --stop >nul
On Windows: Execute in cmd.exe

Notable Differences to Regular Test Suites

TestCase Name

As the squishtest module is used in a Python module and does not follow the test suite - test case structure, the default test case name in the report will be '<embedded>'.

Should you there be a need to change this to something more meaningful, this can be done by changing the test case name on the testSettings object, before you set the Report generator.

    squishtest.testSettings.testCaseName = 'MySimpleTestcase'

This will change the test case name in the report to the value entered.

Squish for Web

If you are using squishtest from a Squish for Web package and want to start the web browser via squishtest.startBrowser(), you will find that this function is not available out of the box.

The reason is, that since you are not in a test suite context, the webhook must be started yourself. The two lines below accomplish that and after calling those, it should be possible to start the web browser if the extension has been installed before.

    squishtest.testSettings.setWrappersForApplication("__squish__webhook", ["Web"])
    squishtest.startApplication("__squish__webhook")

Objects handled by UI Automation (Various Squish editions on Windows)

To establish same object lookup/identification behavior as without the squishtest module, the following changes need to be done in the Squish package (whose squishserver is being used):

installEventHandler()

The functions that the installEventHandler() and installSignalHandler() functions use for the callback, must be registered in the squishtest namespace, otherwise they will not be found.

Example:

import squishtest

def handle_callback(object):
    test.log("Object {}".format(object.text))

def main():
    startApplication("addressbook")
    squishtest.handle_callback = handle_callback
    squishtest.installEventHandler("QToolButton", "QMouseEvent","handle_callback")

    squishtest.clickButton(squishtest.waitForObject({"type":"QToolButton","text":"New"}))

    # The callback takes some time to fire, so wait a little:
    snooze(3)

waitUntilObjectReady / waitUntilObjectItemReady

The functions are currently not implemented as needed for the use case. A workaround is to use a helper function to get a similar setup.

Example:

import squishtest

def waitForObject(objectOrRealname,timeoutMS=squishtest.testSettings.waitForObjectTimeout):
    # Do something here ->
    squishtest.waitForObject(objectOrRealname, timeoutMS)
    # or here if needed

def main():
    print("main called")
    squishtest.testSettings.setWrappersForApplication("quickaddressbook", ["Qt"])
    squishtest.startApplication("quickaddressbook")
    waitForObject({"name": "mainWindow", "type": "QQuickApplicationWindow", "visible": True})

if __name__ == '__main__':
    main()

Functions provided by the squishtest module

setDebugFlags(debugLog_flags_string)

This functions allows configuring the verbosity of the 'squishserver' process' diagnostic and status output. (Also see squishrunner --debugLog .)

Status: Optional

Default: Not set

Example:

# Execute this before startApplication()
# and attachToApplication():
squishtest.setDebugFlags("alpw")

setHookSubprocesses(boolean)

This is the equivalent to enabling sub-process hooking in the settings of a test suite (in the Squish IDE in test suite settings > Hook into sub-processes launched by the application (in the tab AUT).

Status: Optional

Default: True

Example:

squishtest.setHookSubprocesses(True)

setResultDir(result_dir_string)

Defines the output directory for fail images, etc. to use for certain report generators.

Status: Optional

Default: Not set

Example:

squishtest.setResultDir("C:\\Users\\myuser\\squish_results_dir")

setTestResult(report_generator_name, result_dir_string)

Status: Mandatory

Default: Not set

Example:

squishtest.setTestResult("xml3", "C:\\Users\\myuser\\squish_xml_results")