7.4. Command Line Reference

Table of Contents

7.4.1. Installer
7.4.2. squishconfig
7.4.3. squishrunner
7.4.4. squishserver
7.4.5. squishidl
7.4.6. squishide
7.4.7. start*aut
7.4.8. Web Proxy
7.4.9. convertvp
7.4.10. uibrowser
7.4.11. xml2jira
7.4.12. Command Files
7.4.13. configure

In the following descriptions, command line options shown in square brackets are optional, and those followed by a * may be occur zero or more times. Alternatives are indicated using the vertical bar (|)—they are enclosed in square brackets if all the alternatives are optional or in angle brackets if one of the alternatives must be specified. Italics are used to indicate variable items (for example, groups of options, or options that you must enter such as a directory name).

[Note]Command Line Tool Return Values

When a command line tool succeeds it returns 0 to the operating system (as is conventional), and if it fails it returns 255 (-1). Probably the most common cause of failure is forgetting to start the squishserver. If the squishserver is running, the most common problems are not being able to find the AUT, or not being able to start or connect to the AUT.

7.4.1. Installer

The Squish installer supports a range of command line options to permit unattended installations.

[Note]Note

The actual name of the installer depends on the particular Squish package being installed. For the following paragraphs, this documentation will use the generic placeholder name "<squishinstaller>".

Usage:

<squishinstaller> {unattended=1} [targetdir=<PATH>] [licensekey=<KEY>] [jrepath=<PATH>] [support-applets=1] [qtpath=<PATH>] [startmenupath=<PATH>] [menushortcut=1] [desktopshortcut=1]

unattended=1

Causes any values required during the installation (such as the target directory name) to be read from the command line.

targetdir=<PATH>

Optional, defines to which directory the Squish package is installed. If the directory exists already, it will be overwritten. If this argument is omitted, the Squish installer will select a default target directory in the home directory (for Windows and Linux) resp. the /Applications directory (for macOS) based on the name of the package being installed.

licensekey=<KEY>

Required if no key installed already. Specifies the license key to use for the installation. If this setting is omitted, a previously installed license key will be used if available.

jrepath=<PATH>

Optional, relevant for testing Java applications. Specifies the path to the JRE used by the application to be tested. If this argument is omitted, the Squish installer will try to auto-detect a JRE installation.

support-applets=1

Optional, relevant for testing Web applications. Specifies whether the support for automating Java applets in Web pages will be disabled.

qtpath=<PATH>

Required on macOS. Specifies the path to the Qt library used by the application to be tested. This value is ignored on other operating systems.

startmenupath=<PATH>

Only supported on Microsoft® Windows. Defines the place where start menu shortcuts are to be created. Implicitely sets menushortcut=1.

menushortcut=1

Causes the installer to create shortcuts (e.g. to the Squish IDE) in the application menu, i.e. the start menu on Microsoft® Windows. On Windows, the Squish installer will create shortcuts in Squish for <edition> <version> (e.g. Squish for Qt 6.0.1) unless startmenupath defines a different path.

desktopshortcut=1

Only supported on Microsoft® Windows. Causes the installer to place a shortcut to the Squish IDE on the desktop.

7.4.2. squishconfig

The squishconfig program is used to configure a specific Squish installation such that it uses a given license key and other system dependencies (such as a particular Java installation or a particular web browser).

Usage:

squishconfig {--licensekey=<STRING>} [--java=<PATH>] [--swt=<PATH>] [--support-applets] [--qt=<PATH>]

--licensekey=<STRING>

Defines the license key to use for this Squish installation. Specify the license key exactly as given by the froglogic team, i.e. including any dashes.

This argument can also be used to specify an activation code provided by froglogic when configuring a node-locked installation. squishconfig will then attempt to contact the froglogic license server to activate the license.

--java=<PATH>

Relevant for testing Java applications or Java applets; defines the path to the Java Runtime Environment (JRE) used by the application to test.

--swt=<PATH>

Relevant for testing Java/SWT applications. Specifies the path to the swt.jar file.

--support-applets

Relevant for testing Web applications; defines, whether automation of Java applets into web pages is supported or not.

--qt=<PATH>

Relevant for testing Qt applications on macOS; specifies the path to the Qt library used by the application.

7.4.3. squishrunner

squishrunner is used to execute and record test cases and test suites, and to set and retrieve the settings that squishrunner uses at runtime. In fact, squishrunner has many different modes of use, all of which we will cover here.

Note that in almost every case, to make use of the squishrunner, a squishserver must already be running.

7.4.3.1. Server Options

Every mode of use can accept one or more of these server option arguments:

[--host host]
[--port port]
[--debugLog commands]

The square brackets are not part of the syntax—they indicate optional items. Here, every option is optional.

By default squishrunner connects to the squishserver on the local host (127.0.0.1). Use the --host host option if you want squishrunner to connect to a squishserver running on a different machine.

By default squishrunner tries to connect to the squishserver on port 4322, which is also the port squishserver listens to by default. If you have told squishserver to listen on another port, use the --port port option to tell squishrunner which port it should use when connecting to the squishserver.

The --host and --port options are optional—Squish will use sensible defaults if they aren't specified.

7.4.3.1.1. squishrunner --debugLog

This command line option can be used to output additional debugging information to the squishserver's debug log.

Example:

squishrunner --debugLog alpw --testsuite /home/reggie/squish_addressbook_py

This will execute all the test cases in the specified test suite and output all the additional debugging information that is available.

The “apwl” is not a single command, but rather a list of one-letter commands, 'a', 'l', 'p', and 'w'. Any of them can be specified, for example, ap, or w. The meaning of the letters are:

  • a – log the application's start (this is the same as checking the Squish IDE's Application Start checkbox in the Pref­er­ences dialog (Section 8.3.15)'s Squish pane's Logging child pane).

  • l – log dllpreload.exe (this only applies on Windows; if used on other platforms it is safely ignored).

  • p – log the preload phase (this is the same as checking the Squish IDE's Hooking checkbox in the Pref­er­ences dialog (Section 8.3.15)'s Squish pane's Logging pane).

  • w – log the wrapping phase (this is the same as checking the Squish IDE's Wrapper Library checkbox in the Pref­er­ences dialog (Section 8.3.15)'s Squish pane's Logging pane).

7.4.3.2. The suite.conf File

When the squishrunner is executed with the --testsuite or --testcase options, it reads in the suite.conf file in the test suite's root directory, and its behavior will be affected by those of the file's settings listed below. Note also that many of these settings can be viewed and edited using the Squish IDE (see Settings view (Section 8.2.16).)

  • AUT=aut [argument]* This specifies the AUT to start for each test case, and optionally any command line arguments that should be passed to the AUT when it is started. (This can be overridden on squishrunner's command line using the --testsuite and --testcase options' --aut option. The --aut option requires that Automatically start the AUT option in the test suite settings is checked/enabled.)

  • CLASSPATH Normally set through the Squish IDE;see Settings view (Section 8.2.16).

  • CWD=pathOrMagic This specifies the AUT's working directory when being tested. If this option isn't present or if its value is empty the AUT's working directory is set to the path of the AUT's executable. If the value is not empty it is taken to be the path to use (e.g., C:\temp); unless it has one of two “magic” values. One magic value is <AUT_path> which means use the path of the AUT's executable (just the same as if the value were empty). Another magic value is <CWD_of_Server> which sets the AUT's working directory to the squishserver's working directory. This setting is normally set through the Squish IDE; see the Settings view (Section 8.2.16)'s Working Directory panel.

  • ENVVARS=filename This specifies a file that contains one or more lines of VARIABLE=VALUE pairs which define the environment variables and their values that should be in force during the AUT's execution. Squish will ensure that the environment is set up correctly before each run of the AUT. (This can be overridden on squishrunner's command line using the --testcase option when also using the --record option, by using the --envvars option. Alternatively, again when using the --testcase option when also using the --record option, it is possible to specify individual additional environment variables using one or more --envvar options.)

  • HOOK_SUB_PROCESSES=Boolean This specifies whether Squish should hook into sub-processes launched by the AUT. The Boolean should be true or 1 or false or 0. This setting is normally set through the Squish IDE; see the Settings view (Section 8.2.16)'s Application Under Test (AUT) panel.

  • IMPLICITAUTSTART=Boolean This specifies whether Squish should automatically start the AUT. This was common for Squish 3 scripts; but for Squish 4 this setting is normally false and the AUT is started in the test script using the startApplication function. The Boolean should be true or 1 or false or 0. This setting is normally set through the Squish IDE; see the Settings view (Section 8.2.16)'s Application Under Test (AUT) panel.

  • LANGUAGE=language This specifies the scripting language used by the test scripts. Currently this must be JavaScript, Python (for Python 2), Perl, Ruby, or Tcl. (This can be overridden on squishrunner's command line using the --testcase option's --lang option.)

  • NAMINGSCHEME=scheme If present, the naming scheme must be MULTIPROP or HIERARCHICAL. Normally it is best to use MULTIPROP (the default), except for Tk applications where HIERARCHICAL is used.

  • OBJECTMAP=filename By default, Squish reads the test suite's object map from the objects.map file in the root of the test suite's directory. If a different filename (with full path) is specified here, Squish will use the specified file instead of reading the default file. (This can be overridden on squishrunner's command line using the --testcase option when also using the --record option, by using the --objectmap option.)

    [Note]Note

    This configurating setting only applies to Text-Based Object Map (Section 7.11.5).

  • TEST_CASES=testcase [testcase]* The value of this option is a space-separated list of one or more test case names. If the entire test suite is run, e.g., by using the squishrunner's --testsuite option without using the --testcase option to specify which ones, every test case will be run. If every test case is run and this TEST_CASES option is set, the given test cases will be run first—in order—followed by those test cases that aren't listed (if any). In addition, this option is used by the Squish IDE to determine the order in which the test cases are shown in the Test Cases view. (If you only want to have particular test cases run then use the squishrunner's --testcase option.)

  • WRAPPERS=wrappers This lists the wrappers which must be loaded for the tests to run successfully. Currently supported are Qt and XView. Additionally, a number of AUT-specific bindings libraries (application wrappers) to be loaded may also be specified. (This can be overridden on squishrunner's command line using the --testcase option's --wrapper options.) Tests using Squish 4 should rarely need to use this option.

The values used in the suite.conf file can also refer to environment variables. The syntax for this is $(ENVVAR). When such an entry is read, it is effectively replaced by the value of the environment variable of the same name. So if there was an environment variable called MAIL with value /var/spool/mail/reggie, if we used $(MAIL) in the suite.conf file, it would be replaced with /var/spool/mail/reggie.

7.4.3.3. squishrunner --testsuite: Running tests in batch mode

Use squishrunner with the --testsuite option to execute all of a test suite's test cases, or one or more specified test cases.

Usage:

squishrunner [server-options] [settings-option] --testsuite test-suite-dir [other-options]

All items in square brackets are optional. The server-options are described in Server Options (Section 7.4.3.1). The settings-option and other-options are discussed shortly. When used in this mode the squishrunner's behavior is affected by the test suite's suite.conf; see The suite.conf File (Section 7.4.3.2).

There is one deprecated settings-option:

[--settingsGroup settingsGroup]

The square brackets are not part of the syntax—they indicate that this option is optional. This option makes it possible to specify which settings group to use. (Settings groups are deprecated and have no support in the Squish IDE. This option exists purely for backward compatibility.) Since the option was not used in the example above, the default settings were used in that case.

There are several other-options:

[--resultdir result-dir]
[--reportgen report-generator[,filename|dir]]
[--testcase|--skip-testcase test-case-dir]*
[--interactive]
[--abortOnFail]
[--webbrowser browser]
[--webbrowserargs args]
[--applauncher launcher]
[--launcherargs args]
[--device serial-number]
[--exitCodeOnFail code]
[--snoozeFactor factor]
[--timeout seconds]
[--retry number]
[--scriptargs [scriptargument]*]
[--tags tags]*
[--random [sequence-number]]
[--aut aut [argument]*]

The square brackets are not part of the syntax—they indicate optional items. Here, every option is optional, and some parts of some options are optional. The * indicates an option that can occur zero or more times, and | indicates alternatives.

See Playback option --testcase (Section 7.4.3.6) for more details on playback related options.

7.4.3.4.  squishrunner --resultdir: Setting the Result Directory

squishrunner can output a report detailing what happened during test case execution. The --resultdir option uses the default report generator for generating reports. This option requires a directory name to be specified—squishrunner will output its results to a file called results.xml (using Squish's latest xml3 format) in this directory, and if necessary will create a hierarchy of subdirectories, for example, to hold screenshots of failed image verifications.

Given a test suite called suite_myapp, a test case called tst_case1, a result directory my_app_results, and assuming that an image verification point fails, squishrunner will write: my_app_results/results.xml and my_app_results/suite_myapp/tst_case1/verificationPoints/failedImages/failed_1.png.

7.4.3.5.  squishrunner --reportgen: Generating Reports

Squish supports several report generators. To use one that isn't the default format, it is necessary to use the --reportgen report-generator,directorypath option. For example, --reportgen json1.2,/tmp/results. (Notice the comma "," which is essential.)

The report-generator supports many output formats, and some of them are versioned. squishrunner --help gives you a list of supported formats.

  • xml3.2 is recommended for Squish 6.3. Older versions are offered for backward compatibility: xml3.1 for Squish 6.1, xml3 for Squish 6.0, xml2.2 for Squish 5, and xml for older versions.

  • xmljunit - the same output as JUnit tests; less informative than Squish's native XML formats

  • xls - Excel™ spreadsheet

  • json1.2 - JavaScript Object Notation (json1.1, json and JSON are older formats, kept for backward compatibility)

  • html - nice-looking HTML reports

  • stdout - the default used by squishrunner, an ASCII plain text table

All the generators output to the console unless a directory path is specified, in which case the output is to the specified directory.

When report-generator is set to xml3, squishrunner expects to create a results file in the given folder. squishrunner --testsuite /some/path/suite_test --reportgen xml3.2,/some/output/path/your_folder. When an older version of XML is set, for example xml2.2, squishrunner will write its results into the specified file. squishrunner --testsuite /some/path/suite_test --reportgen xml2.2,/some/output/path/result.xml.

7.4.3.6.  Playback option --testcase

By default, all the test suite's test cases are executed, but if we want to specify exactly which test case or test cases are executed we can do so by supplying 1 or more of the --testcase test-case-dir option for each test case we want executed. Alternatively to the --testcase it's possible to skip test cases by using the --skip-testcase test-case-dir option.

Example:

squishrunner --testsuite /home/reggie/suite_addressbook --testcase tst_add_address --testcase tst_edit_address

This example runs two specific test cases in the suite_addressbook suite. If we wanted to run all of the suite's test cases we would simply omit the two --testcase options since without them squishrunner defaults to running all of the suite's test cases.

7.4.3.7.  Playback option --aut

By default, the AUT specified in the test suite's suite.conf file will be used for the execution of the test cases, along with any command line arguments that are specified there. However, we can override this by specifying the name of the AUT using the --aut aut option, followed by zero or more command line arguments. The specified AUT must be registered as a Mapped AUT already and the Automatically start the AUT option in the test suite settings must be checked/enabled. (See also, The suite.conf File (Section 7.4.3.2).)

7.4.3.8.  Playback option --interactive

By default squishrunner works in non-interactive mode which allows it to run without access to any kind of graphical display. For using any of the testInteraction functions (See testInteraction Functions (Section 6.3.17)) however squishrunner needs to be run in interactive mode. Pass the --interactive option to enable interactive mode which will allow squishrunner to display dialogs and message boxes.

7.4.3.9. Playback option --abortOnFail

squishrunner with --testsuite option executes all test suite's test cases one by one. If the --abortOnFail option is specified, squishrunner will terminate the suite execution as soon as a failed test case is detected.

7.4.3.10. Playback option --webbrowser

When recording a web test, the browser to be used can be specified via the --webbrowser browser option. The browser can be any of: firefox (Firefox), ie (Microsoft® Internet Explorer), edge (Microsoft® Edge), safari (Safari), google-chrome (Google Chrome), or chromium-based (Chromium-based Applications).

Additionally, a --webbrowserargs option can be passed to invoke the chosen web browser with your choice of command line arguments.

7.4.3.11. Playback option --device

The --device option is for the Squish Android edition only. It is required when more than one Android devices connected and/or emulators running, to specify on which the application should be tested.

7.4.3.12.  Playback option --snoozeFactor

Most modern tests use the waitForObject function, but for various reasons some tests may have calls to the snooze function. To influence the delay triggered by calls to the snooze function, it is possible to use the --snoozeFactor factor option. The factor must be a number—if it is less than 1 (i.e., a decimal fraction, like 0.5), it will cause shorter delays, and if it is greater than 1 it will cause longer delays. A factor of 0 will produce the fastest possible execution.

7.4.3.13. Playback option --exitCodeOnFail

By default squishrunner returns non-zero value in case of fatal errors and 0 otherwise, regardless of the tests results. If --exitCodeOnFail option is set and defines the specific exit code, squishrunner will return the custom exit code on fatal errors or if any of the test cases has failed, and 0 otherwise.

7.4.3.14. Playback option --timeout

The --timeout option defines the amount of time (in seconds), after which a test case will be terminated regardless of its state. The option applies in --testsuite mode only and accepts the positive integer values. After a test case is timed out, it terminates and the execution proceeds with the next text case, if any.

7.4.3.15. Playback option --retry

The --retry option defines the number of times Squish should try to execute a failed test case again (at maximum). This retrying of the current test case will end as soon as it passes. The option only applies to the --testsuite mode and accepts only positive integer values. For BDD tests the --retry option applies to every scenario of a feature.

7.4.3.16. Playback option --scriptargs

The --scriptargs option marks the end of squishrunner arguments. All following arguments are passed to the executed script which can, depending on the script language, access them as variables. See OS.argv for an example of how to access script arguments in JavaScript.

7.4.3.17. Playback option --tags

The --tags option can be used to execute just those test scripts or BDD scenarios which match a given tag filter. The leading '@' sign from the feature file tags can be omitted. Some examples for the --tags option follows:

Table 7.1. Semantics of --tags switch to select scenarios or test scripts

Options givenMeaning
--tags fooExecute all scenarios or test scripts with the tag foo
--tags ~fooExecute all scenarios or test scripts not tagged foo
--tags foo,barExecute all scenarios or test scripts tagged foo or bar (or both).
--tags foo --tags barExecute all scenarios or test scripts tagged both foo and bar.
--tags foo,bar --tags yoyoExecute all scenarios or test scripts with the tag yoyo and one (or both) of foo and bar.


For an example of how to @tag a BDD scenario, see this page.

7.4.3.18. Playback option --random

The --random option is for executing testcases in random order. The used sequence number is printed in the report as log message. If it is necessary to reproduce a specific order the sequence number can be given as parameter to the --random option. This can be used to reproduce a failure that occurs during random test execution. A sequence number of 0 indicates that a new sequence number is generated. It gives the same behavior as when the value for the option is omitted.

7.4.3.19. squishrunner --record: Recording a Test Case

Use squishrunner with the --testsuite and --record options to record a new test case in the test suite.

Usage:

squishrunner [server-options] --testsuite test-suite-dir --record tst_test-case-dir [other-options]

All items in square brackets are optional. The server-options are described in Server Options (Section 7.4.3.1). The other-options are discussed shortly. When used in this mode the squishrunner's behavior is affected by the test suite's suite.conf; see The suite.conf File (Section 7.4.3.2). The tst_test-case-dir is the test case's name (and the directory where it will be stored)—it must start with tst_.

Example:

squishrunner --testsuite /home/reggie/suite_addressbook --record tst_search_for_address --useWaitFor

This example will cause squishrunner to execute the AUT specified in the test suite's suite.conf file. All your interactions with the AUT will be recorded in the test suite's tst_search_for_address subdirectory in the test.py file (or in test.js, etc., depending on the language specified in the suite.conf file).

Notice that we used the --useWaitFor option. This forces Squish to use the waitForObject function rather than the snooze function to provide the best possible playback reliability.

There are several other-options:

[--useWaitFor]
[--testdata testdata]*
[--disableEventCompression]
[--webbrowser browser]
[--webbrowserargs arguments]
[--aut aut [argument]*]

The square brackets are not part of the syntax—they indicate optional items. Here, every option is optional. The * indicates an option that can occur zero or more times.

7.4.3.20.  Recording option --disableEventCompression

By default, squishrunner uses event compression during recording—this means that mouse moves and drags result in high-level API calls rather than lots of intermediate mouse hover and move events. If the --disableEventCompression is used, this compression is switched off. This option is only supported for Qt Widgets.

7.4.3.21.  Recording option --webbrowser

The --webbrowser and --webbrowserargs have the same behavior in recording mode as in playback mode, please refer to Playback option --webbrowser (Section 7.4.3.10).

7.4.3.22.  Recording option --aut

By default, the AUT specified in the test suite's suite.conf file will be used for the recording of the test case, along with any command line arguments that are specified there. However, we can override this by specifying the name (with full path) of the AUT using the --aut aut option, followed by zero or more command line arguments—if any arguments are specified they will be passed to the AUT when it is started up. (See also, The suite.conf File (Section 7.4.3.2).)

7.4.3.23. Executing a Test Case (Advanced)

Use squishrunner with the --testcase option to execute or record a specific test case. Using the --testsuite option is easier and more convenient than using this advanced option; see squishrunner --testsuite: Running tests in batch mode (Section 7.4.3.3) and squishrunner --record: Recording a Test Case (Section 7.4.3.19).

Usage:

squishrunner [server-options] --testcase tst_test-case-dir [other-options]

All items in square brackets are optional. The server-options are described in Server Options (Section 7.4.3.1). The other-options are discussed shortly.

Keep in mind that the squishrunner needs to know various items of information to work correctly in --testcase mode. One way to ensure it has the information it needs is to specify each item individually using the --wrapper option, the --objectmap option, and so on.

Example:

squishrunner --testcase tst_update_address --aut addressbook

This example starts the addressbook application and executes the specified test case. Since no language has been explicitly specified Squish will assume Tcl. (And similarly, if the --record option is used, Squish will write Tcl. This can be changed of course, as we will see next.)

There are many other-options:

[--record]
[--explicitAutStart]
[--testdata testdata]*
[--lang language]
[--disableEventCompression]
[--snoozeFactor factor]
[--reportgen report-generator[,filename]]
[--wrapper wrapper]*
[--envvars filename]
[--envvar key=value]*
[--cwd @app|@server|path]
[--objectmap filename]
[--webbrowser browser]
[--webbrowserargs arguments]
[--interactive]
[--aut aut [argument]*]

The square brackets are not part of the syntax—they indicate optional items. Here, every option is potentially optional. The * indicates an option that can occur zero or more times, and | indicates alternatives.

squishrunner will assume that the scripting language (to execute, or to record) is Tcl unless the --lang language option is used. If the script does not have a call to startApplication, then the --aut aut option must be used to specify the AUT.

If the --record option is used the test case will be recorded; otherwise it will be executed.

If the --explicitAutStart option is used a recording will include a call to the startApplication function. This is useful for Test Suites created by the Squish IDE which do not automatically start the AUT when executing a testcase.

Zero or more --testdata testdata files may be specified.

To change from Squish's default scripting language (Tcl), use the lang language option, where language is one of JavaScript, Python, Perl, Ruby, or Tcl.

By default, squishrunner uses event compression during recording—this means that common event sequences result in high-level API calls rather than lots of low-level events. If the --disableEventCompression is used the compression is switched off. Using this option is not recommended.

Most modern tests use the waitForObject function, but for various reasons some tests may have calls to the snooze function. To influence the delay triggered by calls to the snooze function, it is possible to use the --snoozeFactor factor option. The factor must be a number—if it is less than 1 (i.e., a decimal fraction, like 0.5), it will cause shorter delays, and if it is greater than 1 it will cause longer delays. A factor of 0 will produce the fastest possible execution.

Squish can output a report detailing what happened during test case execution. Several different report generators are supported, and the one to use along with the file into which the report should be written can be specified using the --reportgen report-generator,directorypath option. For example, --reportgen xml3,/tmp/results. (Notice the comma "," which is essential.)

For a list of all report-generator formats, see squishrunner --reportgen: Generating Reports (Section 7.4.3.5)

If the test case needs one or more wrappers these can be specified by using a --wrapper wrapper option for each one.

The test case's entire environment can be specified using the --envvars filename option where the filename specifies the full path to a file that has key=value entries, one per line, and that will be set as environment variables.

It is also possible to add or override one or more environment variables by using one or more --envvar key=value options.

By default, squishrunner will use the current working directory when executing or recording the test case. But this can be overridden by using --cwd @app which tells squishrunner to use the AUT's directory as the working directory, or by --cwd @server which says to use squishserver's directory, or by --cwd path where we specify an explicit absolute path.

When using Text-Based Object Map (Section 7.11.5), the object map must be loaded by the test case itself using the objectMap.load function, but it can also be specified using the --objectmap filename option where the filename specifies the full path of the object map to read (if executing or recording a test) or create or append to (if recording a test).

When executing a web test, the browser to be used can be specified via the --webbrowser browser option. The browser can be any of: firefox (Firefox), ie (Microsoft® Internet Explorer), edge (Microsoft® Edge), safari (Safari), google-chrome (Google Chrome), or chromium-based (Chromium-based Applications).

Additionally, a --webbrowserargs option can be passed to invoke the chosen web browser with your choice of command line arguments.

If the test case doesn't use the startApplication function, the AUT (with full path) must be specified using the --aut aut option, followed by zero or more command line arguments—if any arguments are specified they will be passed to the AUT when it is started up.

By default squishrunner works in non-interactive mode which allows it to run without access to any kind of graphical display. For using any of the testInteraction functions (See testInteraction Functions (Section 6.3.17)) however squishrunner needs to be run in interactive mode. Pass the --interactive option to enable interactive mode which will allow squishrunner to display dialogs and message boxes.

7.4.3.24. Querying for Information

Use squishrunner with the --info option to query for various items of information.

Usage:

squishrunner --info topic

The topic may be any one of: wrappers, applications, AUTTimeout, cursorAnimation, settingsKey, attachableApplications, webBrowsers, defaultWebBrowser, responseTimeout, androidDevices, or androidInstrumentation.

Example:

squishrunner --info applications

This will print a list of the registered AUTs and their paths on the console.

Here is a description of the information that is output for each of the available topics. (As is usual for squishrunner, a squishserver should be running for squishrunner to work.)

--info wrappers
--info applications
--info AUTTimeout
--info cursorAnimation
--info settingsKey
--info attachableApplications
--info webBrowsers
--info defaultWebBrowser
--info responseTimeout
--info androidDevices
--info androidInstrumentation

If the wrappers topic is specified, squishrunner will print out a list of the installed wrappers.

If the applications topic is specified, squishrunner will print out a list of all the applications which are located in the squishserver's application paths and that can be tested by Squish with the current settings.

If the AUTTimeout topic is specified, squishrunner will print out how many seconds squishrunner will wait before timing out with a test failure if the AUT doesn't respond after being started. (This value can be changed using the --config setAUTTimeout option; see Configuring squishrunner (Section 7.4.3.25).)

If the cursorAnimation topic is specified, squishrunner will print “on” if the mouse cursor should be animated (visually moved between positions) during script playback; otherwise it will print “off”. (This value can be changed using the --config setCursorAnimation option; see Configuring squishrunner (Section 7.4.3.25).)

If the settingsKey topic is specified, squishrunner will print the settings key for this Squish installation, e.g., “ver1”.

If the attachableApplications topic is specified, squishrunner will print a list of all the registered attachable applications.

If the webBrowsers topic is specified, squishrunner will print a list of all the system's web browsers that it has detected.

If the defaultWebBrowser topic is specified, squishrunner will print the name of the web browser that it uses for web testing.

If the responseTimeout topic is specified, squishrunner will print the number of seconds that Squish will wait before timing out with a test failure during (mostly network based) communication between the squishserver and the squishrunner, and also between other Squish components.

If the androidDevices topic is specified, squishrunner will print a list of all attached Android emulator/device instances.

If the androidInstrumentation topic is specified, squishrunner will print a list of all installed instrumentation packages on all attached Android emulator/device instances.

7.4.3.25. Configuring squishrunner

Use squishrunner with the --config option to change various settings.

Usage:

squishrunner --config action

Only a single configuration action can be specified each time.

Example:

squishrunner --config setAUTTimeout 60

This will set the AUT timeout to 60 seconds (the default is 20 seconds).

Many actions are supported:

--config setBaseDir wrapper directory
--config setBrowserPath browser executable
--config addInitScript wrapper script
--config setAUTTimeout seconds
--config setResponseTimeout seconds
--config setAUTPostMortemTimeout milliseconds
--config setCursorAnimation on|off
--config setPauseHotkey key
--config setDefaultWebBrowser browser
--config setAttachableAUT aut [host:]port
--config removeAttachableAUT aut [host:]port
--config isBrowserExtensionInstalled browser-id browser-executable
--config installBrowserExtension browser-id browser-executable
--config getGlobalScriptDirs
--config setGlobalScriptDirs dir1,dir2,dir3,...

Use the setBaseDir action to create a new wrapper with the given wrapper name and with the given base directory.

Use the setBrowserPath action to specify a browser and the path to its executable. The browser should be one of firefox (Firefox), ie (Microsoft® Internet Explorer), edge (Microsoft® Edge), or safari (Safari), chromium-based (Chromium-based Applications), and the executable should include the full path to the browser's executable.

Use the addInitScript action to specify the filename of a Tcl script that should be executed when the specified wrapper is used. The script should either be a filename with an absolute path or a filename with a path relative to the wrapper's base directory. Whenever a test case needs to use a wrapper, Squish first executes all the scripts registered with this action for the wrapper (if any), before the test case is executed. (Although init scripts must be written in Tcl, they are only used to initialize GUI toolkit wrappers, and have no effect on what language we use to write our test scripts.)

Use the setAUTTimeout action to specify how long Squish should wait before timing out with a test failure if the AUT doesn't respond after being started. (This action's current setting can be output using the --info AUTTimeout option; see Querying for Information (Section 7.4.3.24).)

Use the setResponseTimeout action to specify how long Squish should wait before timing out with a test failure during (mostly network based) communication between the squishserver and the squishrunner, and also between other Squish components.

Use the setAUTPostMortemTimeout action to specify how long Squish should wait after an application has exited to end squishrunner. In some setups, a second process is started from the first one and the second Squish hookup happens after the first one has exited.

Use the setCursorAnimation action with an argument of on or off to specify whether the mouse cursor should be animated (visually moved between positions) during script playback. (This action's current setting can be output using the --info cursorAnimation option; see Querying for Information (Section 7.4.3.24).)

Use the setPauseHotkey action with the name of a key to specify a hotkey that Squish should monitor, so that when the key is pressed Squish will pause test execution (e.g., to make it possible to spy on the AUT). (This action's current setting can be output using the --info pauseHotkey option; see Querying for Information (Section 7.4.3.24).)

For web applications use the setDefaultWebBrowser action to specify the default web browser. The browser can be any of: firefox (Firefox), ie (Microsoft® Internet Explorer), edge (Microsoft® Edge), safari (Safari), google-chrome (Google Chrome), or chromium-based (Chromium-based application).

Use the setAttachableAUT action to specify an AUT that should be attached to when the test case is run.

Use the removeAttachableAUT action to unregister an AUT that was previously registered using the setAttachableAUT action.

Use the isBrowserExtensionAvailable option to verify whether the extension for the browser-id is installed, enabled and the version allows automation with this version of Squish. This option currently supports using firefox and google-chrome for the browser-id. The command will output its results to the command window from where it is being invoked. If you have multiple browser installations on your system or Squish cannot find the browser by itself you can provide the executable as another argument.

Use the installBrowserExtension option to install the browser extension needed to automate the browser identified by browser-id. The installation procedure will start the browser and point it to the extension, the browser will then request your permission to install and activate the extension and eventually it will require you to restart the browser. Once all of this has completed make sure to completely quit the browser by using the Quit menu entry. This option currently supports using firefox and google-chrome for the browser-id. If you have multiple browser installations on your system or Squish cannot find the browser by itself you can provide the executable as another argument. The command will output its results to the command window from where it is being invoked.

The getGlobalScriptDirs prints out a list of currently set GlobalScript locations.

Use the setGlobalScriptDirs option to define GlobalScript locations, which will be included when interpreter searches for source(findFile()) includes. Several comma separated locations can be given.

Additional Note: Use squishrunner --help to get a list of any options and actions which your currently used Squish package actually supports.

7.4.4. squishserver

The squishserver is responsible for handling the communications between the squishrunner and the application under test. The squishserver must be run on the same machine as the AUT, although squishrunner can run on a different machine.

If the squishserver is started without any command line options, it will listen to connections on port 4322 and will only accept connections from the local host (127.0.0.1). To make it accept connections from other hosts, those hosts must be specified. For this purpose, squishserver reads the file /etc/squishserverrc (on Unix-like systems) or C:\squishserverrc (on Windows). If the file isn't found the squishserver will try SQUISHDIR/etc/squishserverrc (on Unix-like systems) and SQUISHDIR\etc\squishserverrc and SQUISHDIR\etc\squishserverrc.txt (on Windows).

The squishserverrc file can specify the IP addresses from which connections are allowed using a line of this form:

ALLOWED_HOSTS=ip-address1 ip-address2 ...

Wildcards can be used in the specified IP addresses to match more than a single IP address. For example:

ALLOWED_HOSTS=192.168.0.* ...

The port number that squishserver listens to can be changed by adding a line of the form PORT=port to the squishserverrc file.

[Note]The squishserverrc File

Squish does not create a squishserverrc file itself; if one is needed, it must be created manually using a plain text editor.

The squishserver has three modes of use: serving, stopping, and configuring, all of which we will cover here.

7.4.4.1. Serving

Use squishserver with no command line options, or with those documented here, to have a server for squishrunner to use.

Usage:

squishserver [--verbose] [--port port] [--daemon]

The items in square brackets are optional.

squishserver can be used with no options at all, or with a --port port to specify which port to listen on. The command line option overrides any PORT=port that is specified in the squishserverrc file.

If the --verbose option is used, squishserver will produce more output than usual. The extra output is designed to be helpful for investigating problems such as remote server connection problems or incorrect Qt library path settings.

On Unix-like platforms (i.e., not on Windows), the --daemon option can be specified. If this option is used then the squishserver will be run in the background. This means that the server will detach itself from the controlling terminal and stop printing anything to standard output or to standard error. Note that with this option in force, anything that the AUT prints to these channels will also be lost; which means that there is no point using the --verbose option when the --daemon option is used. (The squishserver also supports a --local option in this mode; it exists for backward compatibility and should not be used now.)

7.4.4.2. Stopping

To stop a squishserver from running use the --stop option.

Usage:

squishserver [--port port] --stop

If the port isn't specified the server will be contacted using Squish's default port number.

Example:

squishserver --stop

This tells the squishserver to shut down. (In almost all use cases, a squishrunner cannot operate without a squishserver.)

7.4.4.3. Configuring squishserver

Use squishserver with the --config option to change various settings.

Usage:

squishserver --config action

Only a single configuration action can be specified each time. (For backward compatibility an additional optional option, --settingsGroup settingsGroup is supported. If specified it tells the squishserver which settings group to use. The Squish IDE has no support for settings groups and this option is deprecated.)

Example #1:

squishserver --config addAppPath C:\squish\examples\qt4\addressbook

This will use the default settings, and add the C:\squish\examples\qt4\addressbook path to Squish's list of paths in which to look for AUTs.

Note that it is possible to refer to environment variables on the command line using the syntax $(NAME) (although on some shells—typically those used on Unix—the $() parts may need to be escaped).

Example #2.

squishserver --config addAUT addressbook $(SQUISHPATH)\examples\qt4\addressbook

Here we have added a new AUT and to do so we have used the SQUISHPATH environment variable—which must have been set earlier.

Many actions are supported:

--config addAppPath path
--config removeAppPath path
--config addAUT aut path
--config removeAUT aut path
--config addAttachableAUT aut [host:]port
--config removeAttachableAUT aut [host:]port
--config setWrapperLibs aut lib1[,lib]*
--config usesBuiltinHook aut
--config setAUTTimeout seconds
--config setResponseTimeout seconds
--config setAUTPostMortemTimeout milliseconds
--config setHardExitTimeout milliseconds
--config setSoftExitTimeout milliseconds
--config setBrowserPath browser executable
--config setProxyConnectAddress [host:]port
--config setStartProxyServer true|false
--config setStartBrowserForProxy true|false
--config setJavaVM filename
--config setLibJVM filename
--config setJavaVersion version
--config setSWTJar filename
--config setConfig aut path
--config removeConfig aut path

Use the addAppPath action to add a path to the list of paths in which squishserver looks for applications when starting an AUT.

Use the removeAppPath action to remove a path from the list of paths in which squishserver looks for applications when starting an AUT.

Use the addAUT action to add an application mapped to the specified path. If different versions of the same application have the same executable name and appear in different paths that have been registered using the --config addAppPath option then which one should Squish use? By using the --config addAUT option, we can say specifically which executable should be used in which path thereby avoiding any ambiguities.

Use the removeAUT action to remove an application mapped to a specified path.

Use the addAttachableAUT action to specify an AUT that can be attached to.

Use the removeAttachableAUT action to unregister an AUT that was previously registered using the addAttachableAUT action.

Use the setWrapperLibs action to specify the wrapper library or libraries to use with the specified AUT.

Use the usesBuiltinHook to force Squish to use a built-in hook rather than the default non-intrusive hooking. Be sure to read about this option before using it—see Using the Built-in Hook (Section 7.13.2).

Use the setAUTTimeout action to specify how many seconds Squish should wait before timing out with a test failure if the AUT doesn't respond after being started. The default is 20.

Use the setResponseTimeout action to specify how many seconds Squish should wait before timing out with a test failure when waiting for a response from the AUT. The default is 300. (This is distinct from the timeout used by the waitForObject function.)

Use the setHardExitTimeout action to specify how many seconds squishserver should maximally wait after sending a SIGTERM to an application, before sending a SIGKILL if the application is still running. This option does nothing on Windows. The time is on top of setSoftExitTimeout ms. The default is 300.

Use the setSoftExitTimeout action to specify how many milliseconds squishserver should maximally wait after squishrunner has ended before killing the application if it is still running, when started automatically or with startApplication. The default is 2000.

Use the setAUTPostMortemTimeout action to specify how many milliseconds Squish should wait after the first AUT process has exited. This applies to AUTs that actually start the "real" AUT as a new/separate (sub-)process, like Java Web Start, but also third party Java application launchers. In those cases the first AUT process may exit before the second (the "real") AUT process has been hooked up by Squish. And this will cause Squish to abort its attempt to start (and hook up) the AUT with an error - unless hooking of the second AUT process succeeds within the number of milliseconds specified by this setting. The default is 1500.

Use the setBrowserPath action to specify a browser and the path to its executable. The browser should normally be one of firefox (Firefox), ie (Microsoft® Internet Explorer), edge (Microsoft® Edge), or safari (Safari), chromium-based (Chromium-based application), and the executable should include the full path to the browser's executable.

Squish supports specific web browsers on specific desktop platforms out of the box. However, it is also possible to test other web browsers or test on non-desktop platforms (e.g., iPhones and similar) by using Squish's web proxy (Web Proxy (Section 7.4.8)).

Use the setProxyConnectAddress action to tell Squish that when it communicates with the Web Proxy (Section 7.4.8) it should use the specified host (or localhost if no host is given) and port. The squishserver and squishrunner will communicate as usual using Squish's normal port number, so the port number that the web proxy uses must be different to avoid a conflict.

Use the setStartProxyServer action to tell Squish to start—or not start—a proxy server itself. For remote testing of, say, Safari on an iOS device, set this to false since you will need to start the Web Proxy (Section 7.4.8) yourself manually. (See Browsers on mobile devices (Section 3.1.7.9).)

Use the setStartBrowserForProxy action to tell Squish whether to start a web browser on the local computer. For remote testing of, say, Safari on an iOS device, set this to false since we want the device's browser to be used.

All the following configuration actions are specific to Java™ AUTs.

Use the setJavaVM action to tell Squish where the Java executable is located, giving it the full path (e.g., /usr/lib/jvm/java-6-sun/jre/bin/java on Linux).

Use the setLibJVM action to tell Squish where the Java virtual machine is located, giving it the full path (e.g., /usr/lib/jvm/java-6-sun/jre/lib/i386/client/libjvm.so on Linux).

Use the setJavaVersion action to specify a particular version of Java to use (e.g., 1.5.0_11).

For Java™ AUT's using the SWT GUI library, the SWT library to use should be specified using the setSWTJar action and giving the full path to the .jar file (e.g., C:\swt\swt.jar on Windows).

Use the setConfig action to register a custom .jar file that implements Squish's Java Extension API. (See Java Extension API for Custom Widgets (Section 6.7.4).)

Use the removeConfig action to unregister a custom .jar file that implements Squish's Java Extension API. (See Java Extension API for Custom Widgets (Section 6.7.4).)

The squishserver has some other configuration options, specifically, usesBuiltinHook and setJavaHookMethod; these are for backward compatibility; they should not be used now.

7.4.5. squishidl

squishidl is a tool which parses C++ header files and generates C++ introspection and automation code. It is mostly used internally by other Squish tools, although some customers have also found it useful. (Note that since Squish 4 this tool is rarely needed since Squish 4 is often able to dynamically detect properties and methods, even of custom AUT objects.)

For each C++ header file that is processed, two output files are required—a .h file and a .cpp file. To produce these files, squishidl must be run twice: first to produce the .h file; and second, using the original and generated header files to produce the .cpp file.

Usage:

squishidl <--decl|--impl> -i filename.h [other-options]

The item in angle brackets is required; | signifies alternatives. So here, either the --decl option or the --impl must be specified. The -i (input) option is also required.

To generate the header file, run squishidl with the --decl (declaration) option, and specify the C++ header that must be parsed with the -i option. For example:

squishidl --decl -i myapp.h -o generated.h

This reads the input header myapp.h and outputs the generated header generated.h.

To generate the cpp file, run squishidl with the --impl (implementation) option, and specify both the C++ header using the -i option, and the header that was just generated using the -h option. For example:

squishidl --impl -i myapp.h -h generated.h -o generated.cpp

This reads the input header myapp.h and the generated header generated.h, and outputs the generated implementation file generated.cpp.

Many optional other-options are supported—and some can be used multiple times (indicated by *):

[-o outputfile]
[--dump [dumpfile]]
[-D macro]*
[-U macro]*
[-I includepath]*
[-F path]*
[--strict]
[--filter expr]*
[--nocache]
[--includePrefix prefix]
[--extraInclude includefile]*
[--commandFile filename]

By default the output is written to the stdout stream (e.g., to the console). Use the -o outputfile option to specify a file for the output to be written to.

The --dump dumpfile option is used for debugging squishidl so should not normally be used. It causes squishidl's intermediate format after parsing the C++ header and that is then processed by the output generator, to be output. By default the output is sent to the stdout stream (e.g., to the console), but if a filename is specified the output will be written to the file instead.

Use the -D macro to define a macro on the command line—this works just the same way as defining macros for a C++ compiler using the command line. Any macros defined like this when compiling the input file should also be passed to squishidl.

Use the -U macro to undefine a macro on the command line—this works just the same way as undefining macros for a C++ compiler using the command line. Any macros undefined like this when compiling the input file should also be passed to squishidl.

Use the -I includepath option to add an include search path in the same way as is done on the command line with a C++ compiler. The same include paths as passed to the C++ compiler when compiling the input file should be passed to squishidl.

On macOS use the -F path option to add include search paths in frameworks. The same frameworks include paths as passed to the C++ compiler when compiling the input file should be passed to squishidl.

By default, when parsing the C++ header file, parse errors are interpreted as warnings. Use the --strict option to force squishidl to treat parse errors as fatal errors.

Use the --filter expr option to specify a global function, class, method, or template instantiation, for which introspection code should not be generated. The expr must be the fully qualified signature of a type or of a function. For example, to exclude the QListIterator class use --filter QListIterator. And to exclude both of the QList::erase methods, the option must be used twice, --filter "QList::iterator QList::erase(QList::iterator)" and --filter "QList::iterator QList::erase(QList::iterator,QList::iterator)"; the quotes are needed to account for the whitespace between the return type and the method name.

By default squishidl caches its first run's data in an intermediate format and only parses the C++ header file on the second run if the cache's timestamp has changed. Use the --nocache option to switch off squishidl's caching. (Using this option will slow squishidl down and should not be necessary.)

Use the --includePrefix prefix option to specify the prefix which should be used when generating #include statements. An empty prefix means the same as specifying the current directory. For example, if the input file has the include #include <header> and an --includePrefix of ../parallel/ is specified, then the generated result will be #include <../parallel/header>.

Use the --extraInclude include option to specify a filename which should appear in the generated file in an #include statement.

Options can also be read using the --commandFile filename option; see Command Files (Section 7.4.12).

The squishidl tool has one small limitation which very occasionally comes to light: the tool cannot wrap the properties of types that have a private assignment constructor or a private copy constructor. This is because Squish's bindings need to copy property values and obviously that isn't possible for types that disallow assignment or copying.

See also, How to Create and Access Application Bindings (Section 5.26).

7.4.6. squishide

The Squish IDE is a GUI tool used to create, record, modify, debug, and run tests.

Usage:

squishide [-h|-help|--help] [-toolsPackage=toolsDirectory] [-data workspaceDirectory] [-use-ide-cwd-for-squishserver] [suite_test...]

This is the new IDE introduced with Squish 4.0. When the Squish IDE is started it restores the previous session—that is it opens the same test suite and creates tabs for the same test cases that were open at the time the Squish IDE was last exited.

You can specify the directory that the IDE should use for the Squish commandline tools using the -toolsPackage commandline option. The directory will be preferred over any previously set directory, but can be overridden if the IDE is bundled along with the commandline tools in a single package. The commandline tools directory can also be specified by setting an environment variable called SQUISHIDE_TOOLS_PACKAGE_DIRECTORY.

You can specify the directory where the IDE will store the previous session and all its settings using the -data switch. The given directory will be used instead of the default workspace that the IDE would normally use ($HOME/.squish/workspace-ver-4 on Linux/Unix/MacOSX and %APPDATA%\froglogic\Squish\workspace-ver-4 on Windows).

The IDE sets the working directory of squishserver to the bin subdirectory of the package it belongs to. Using the option -use-ide-cwd-for-squishserver you can change this behavior and make the IDE use its own working directory also as the working directory for squishserver.

[Note]Note

This can cause problems when automating Eclipse RCP applications when starting the IDE from inside the directory containing squishide.exe

If the Squish IDE is started with one or more optional command line arguments that specifies the path to an existing test suite, after restoring the previous session, the Squish IDE then opens the specified test suite ready for use.

7.4.7. start*aut

The start*aut programs start an AUT that is to be attached to by Squish. There are three of these programs: androidobserver (Section 7.4.7.2) for android AUTs, startaut (Section 7.4.7.1) for Qt, macOS, and Tk AUTs, startjavaaut (Section 7.4.7.3) for Java AUTs, and startwinaut (Section 7.4.7.4) for native Windows AUTs.

See Attaching to Running Applications (Section 7.8) for an example of how to make use of these tools.

7.4.7.1. startaut

Usage:

startaut [--verbose] [--capture-output] [--wrapper=toolkit] [--cwd=working-directory] --port=port|--uses-builtin-hook aut [aut-command-line-options]

The --verbose option is only useful for debugging the tool itself and is not normally used. The --wrapper option is used to specify the AUT's GUI toolkit, which must be one of Qt, Mac, or Tk. If the --wrapper option isn't specified, Qt is assumed. The --cwd option can be used to specify the working directory for the AUT. Either the --port option or the --uses-builtin-hook must be specified. The --capture-output option specifies whether the AUT's standard output and error will be available. This option will not apply if the --uses-builtin-hook option is specified. The --port option is used to specify the port number that Squish should use for communicating with the AUT. Naturally, the aut must be specified. Any aut-command-line-options options are passed to the AUT when the startaut program starts it.

See Attaching to a Running Application with the Built-in Hook (Section 7.13.2.3) for how to use this tool with the --uses-builtin-hook option.

7.4.7.2. androidobserver

Usage:

androidobserver [--device serialNumber] [--port port] [--clear-app-settings] [--force-rotation rotation] [--attach-port attachPort] [--no-autostart-observer] [--no-ui-automation] [--web-hookup-timeout msec]emphasis> [-e key value]* aut

7.4.7.2.1. --device

The --device option is required when more than one Android devices connected and/or emulators running, but otherwise optional.

7.4.7.2.2. --clear-app-settings

The --clear-app-settings runs Android package manager clear command for the AUT before launching it.

7.4.7.2.3. --force-rotation

The --force-rotation is a workaround in case screenshots are rotated or upside down. The rotation value must be either 0, 1, 2 or 3, representing resp. zero, 90, 180 or 270 degrees.

7.4.7.2.4. --port

The --port option is used when multiple simultaneous tests are started from the commandline. Each androidobserver forwards this TCP port to the device or emulator. The default value is 37090.

7.4.7.2.5. --attach-port

The --attach-port option is used to specify the port number that Squish should use for communicating with the AUT. Naturally, the aut, which is the Android package name, must be specified and must have been instrumented first by the Squish IDE or Using a separate test package (Section 3.1.9.1.1).

7.4.7.2.6. --no-autostart-observer

This option will considerably speed-up the Android app launch time. It skips part of the hook-up process. The test script must contain startObserver in order to complete it. It can be used to overcome a start-up timeout. Between startApplication and startObserver the object recognition is limited.

7.4.7.2.7. --no-ui-automation

This option will disable Android UIAutomation support (technically, run the Squish instrumentation runner without the wait option). Before Squish version 6.1 this was the default. Squish version 6.1 automatically enables UiAutomation when available (Android-4.3 or later).

7.4.7.2.8. --web-hookup-timeout

This option sets the time Squish will wait after a page-finished event to do a WebView control hook-up.

7.4.7.2.9. -e key value

This option allows passing key/value pairs to the Android Intent.

7.4.7.3. startjavaaut

Usage:

startjavaaut [--verbose] [--cwd=directory] --port=port aut [aut-command-line-options]

The --verbose option is only useful for debugging the tool itself and is not normally used. The --cwd option is used to specify the AUT's working directory. The --port option is used to specify the port number that Squish should use for communicating with the AUT. Naturally, the aut must be specified and must be a Mapped AUT (Section 7.3.2.2) name. Any aut-command-line-options options are passed to the AUT when the startjavaaut program starts it.

7.4.7.4. startwinaut

startwinaut can be used to start an AUT as a child process, or to attach to an already running one, depending on the options that are used. Usage:

startwinaut --port=port (--window-title=title of window | --pid=Process ID of AUT | [--cwd=directory] command [command-line-options])

  • --port is required to specify the port number that Squish should use for communicating with the AUT.

  • --pid option is used to specify the process ID of the AUT to attach to.

  • --window-title option is used to specify the window caption of the AUT to attach to. The value may use simple glob-style wildcards (* for zero or more of any character, ? for any single character). It is not possible to use an escape character for * or ?.

  • The command may be an AUT or a batch file that starts the AUT. Any command-line-options options are passed to the command if the startwinaut program starts it this way.

  • --cwd is used to specify the command's working directory.

[Note]Note

When startwinaut is started over console it can happen that the console window is found instead of the target window. This is because the console window title changes to the executed command. It is possible to overcome this by using "START" to run the startwinaut in a new window which does not have a dynamic window title:

c:\> START $SQUISHDIR/bin/startwinaut --window-title=somewindow

7.4.8. Web Proxy

There are two ways to work with web applications—directly, or using the web proxy mechanism introduced in Squish 4.1. For testing web applications with Safari on macOS, Microsoft Internet Explorer on Windows, or Firefox on Windows/MacOSX/Linux/Unix it is best not to use the proxy mechanism since the mechanism imposes a few limitations.

For all other browsers, including Safari on Windows or iOS, the proxy mechanism must be used. If the proxy mechanism is used the key limitations that apply are that native dialogs and file-upload fields are not supported, it is not possible to use a single proxy for multiple parallel test recordings/replays, the HTTPS protocol is not supported, and screenshot verifications on remote browsers (e.g., browsers running on iPhones and iPads) are not supported.

In addition, when using the proxy mechanism, some browsers may show a progress indicator throughout test recording and replay—this is to be expected because Squish is in constant communication with the web application.

The web proxy mechanism is set up by changing the squishserver's configuration, telling the Squish IDE to use the web proxy, and by running the web proxy itself. For squishserver see Configuring squishserver (Section 7.4.4.3), in particular, setProxyConnectAddress, setStartProxyServer and setStartBrowserForProxy. For the Squish IDE set the browser to use to be “Web Proxy”; (see Squish Preferences Child Panes (Section 8.3.15.7.1)).

The web proxy is in SQUISHDIR/bin/webproxy and its excecutable is called proxy. The proxy must be executed with a command line like the following:

$ $SQUISHDIR/bin/webproxy/proxy [<-H|--host> proxy-host] [<-p|--port> proxy-port] [listen-host] listen-port

The -H (or --host) option is used to specify the hostname of the proxy host (e.g., the device) that the tests must run on; it defaults to localhost. The -p (or --port) option is used to specify the proxy's port; it defaults to 8000. These two options must be followed by the hostname and port—or just the port, leaving the hostname to default to localhost—that Squish must use to communicate with the web proxy—these must match those set using the squishserver's setProxyConnectAddress option.

For an example of the web proxy mechanism in use see Browsers on mobile devices (Section 3.1.7.9).

7.4.9. convertvp

This program is used internally by Squish to handle image verifications. However, some customers have found one of its facilities useful: its ability to take two images and produce a third image which is a diff (shows the difference) of the other two. When used with two identical images it simply produces a plain white image the same size as the two images it was given.

Here is an example of it in use:

convertvp --diff screenshot1.jpg screenshot2.jpg diff.png

The program takes four arguments, --diff, followed by the names of the two images files that are to be compared, followed by the name of the resultant image file. The filenames may include paths. The program supports all the image formats that the underlying Qt library supports, which at a minimum includes, BMP, JPG, PNG, PPM, TIFF, XBM, and XPM.

The program has several other options, but the only one likely to be of use is --topng which converts an image in one format to another format. Use convertvp -h to get a list of the commands and their arguments.

7.4.10. uibrowser

uibrowser is a tool for browsing the AUT's GUI while examining a GUI coverage results file. When given a filename, will open it as an XML gui coverage results file, and display a UI Browser that looks like this:

The UI browser

For info about what the browser displays, and how to save GUI coverage results, see Tutorial: Coverage of GUI elements (Section 4.1.4).

To open the uibrowser to browse a single coverage file:

$ uibrowser coveragefile.xml

To merge the results of 2 coverage files into a single output file:

$ uibrowser [-o coverage_outputfile.xml] [--coverage file1.xml [file2.xml]*]

To merge results of all coverage files found in a directory:

$ uibrowser [-o coverage_outputfile.xml] [--coveragedir directory]

The options --coverage and --coveragedir cannot be used together.

-d and --coveragedir are equivalent. -o and --output are equivalent.

7.4.11. xml2jira

The xml2jira tool allows automated creation/updating of JIRA issue tickets based on result output generated by Squish tests.

xml2jira creates a JIRA ticket corresponding to a Squish test suite. When it got passed a new result.xml file, it connects to JIRA and (related to the test suite which has generated the result) creates a ticket there, or (if a related ticket already exists) it updates the already existing ticket with these new gathered, actual test results.

To make ticket creation and updating possible for xml2jira, your JIRA system needs to be configured so that 'labels' field is settable from within a project's default ticket creation dialog. Xml2jira needs the 'labels' field to 'mark' a ticket, so it later can identify it as being the right ticket, corresponding to exactly that test suite which new gathered results are going to be updated.

The JIRA issue Description contains the Test suite status describing when the executed test cases passed or failed last and the test execution duration. If a corresponding issue already exists its description will be updated accordingly.

Test suite status

In addition, on every invocation of xml2jira, a comment containing an overview (Test suite summary) of the test cases executions mentioned in the specified Squish XML report file, will be added to the respective JIRA issue.

Test suite summary

Optionally the Squish XML report file can be added as file attachment to the JIRA issue for later analysis.

The xml2jira tool changes the JIRA issue status to Open if the Squish XML report file may contain any failure. If the report file does not contain failures, the status is set to Closed.

7.4.11.1. Synopsis

xml2jira {--server <url>} {--user <name>} {--password <password>} {--project <project key>} {--reportfile <filename>} [--issueType <name>] [--component <name>] [--transitions <workflow>] [--customField <field=content>] [--commandFile <filename>] [--attachSquishReport] [--deleteIssue]

The available arguments are described below:

--server <url>

The URL of the JIRA server including the port, e.g. http://jira:8080.

--user <name>

Indicates the name of the JIRA user used to authenticate against the JIRA server.

--password <password>

Indicates the password for the JIRA user.

--project <project key>

Specifies the JIRA project by taking project key as argument.

--component <name>

Optionally specifies the name of the JIRA project component.

--issueType <name>

Optionally specifies issue type for the JIRA ticket. (when given, parameter must match one of the issueTypes defined in JIRA, otherwise ticket creation will fail. when option is omitted, issueType 'Bug' will be used per default.)

--reportfile <filename>

Specifies the absolute path to the Squish XML report file for which a JIRA issue will be created or updated, e.g. C:\reports\squishreport.xml. Supported result formats are: xml2, xml2.1, xml2.2, xml3, xml3.1, xml3.2, xml3.3

--commandfile <filename>

Specifies an optional UTF-8 encoded file containing command-line options used in addition to the options passed to the xml2jira tool.

--attachSquishReport

Optionally indicates to attach the Squish XML report file to the JIRA issue.

--customField <fieldname=fieldcontent>

Optionally defines customfields on JIRA tickets for being updated by <fieldcontent>. Also it is used for filling fields with <fieldcontent> within the ticket creation dialog, which have been set 'required' for ticket creation. This option can be given several times, for each field which may need update. Also 'CustomOptionFields' (as Dropdown-fields or Combo-boxes) can be filled. In this case, <fieldcontent> must exactly match one of the field's selectable options.

--transitions <workflow endpoint definitions>

Optionally defines custom workflow endpoint states and transitions between them. When your Jira platform is configured to use non-standard workflow definitions, this option can be used to let xml2jira know about them.

This option always needs 4 comma-separated parameters, given in this order: Active=metaID, AtransD=metaID, Disabled=metaID, DtransA=metaID, otherwise ticket creation will fail:

  • For 'Active' and 'Disabled' give the names of these states which xml2jira should use when updating results (in JIRA standard workflow, these would be called 'Open=1' and 'Closed=6'). A PASSED update would lead to a ticket being 'Disabled' and a FAILED update would lead to a ticket being 'Activated'.

  • For 'AtransD' and 'DtransA' names of the transitions leading from 'Active' to 'Disabled' state and vice versa must be given. (in JIRA standard workflow, these would be called 'CloseIssue=2' and 'ReopenIssue=3').

  • For each of these names also the <meta-id> must be given, separated by '=' sign. Short example: A --transition parameter which matches the JIRA predefined standard states and transitions would look like following:

    xml2jira ... --transitions "Open=1,CloseIssue=2,Closed=6,ReopenIssue=3" ... --reportfile C:\report.xml
    

--deleteIssue

Deletes a Jira-ticket related to the test result given by --reportfile option. (for this, reporting --user need to have admin rights enabled on the JIRA server.)

7.4.11.2. Examples

  • Here is an example invocation of the xml2jira tool which imports the Squish XML report file C:\report.xml into the specified JIRA server using the user alice and password al1ce for the project SampleProject and the component tests.

    xml2jira --server http://jira:8080 --user alice --password al1ce --project SampleProject --component tests --reportfile C:\report.xml
    

7.4.12. Command Files

Command-line arguments can also be read from a file. These “command” files are plain text files and contain the command-line arguments in a single line or multiple lines. Using a command file can be convenient if a complex command line is required—especially if the same command line needs to be used repeatedly. Different operating systems have different command line length limits, so if this limit is reached, using a command file can circumvent the problem.

A command file has one or more lines of command-line options, written exactly as they would appear in the command line—including quoting for any whitespace. Blank lines are ignored as are comment lines (those beginning with #).

Here is an example command file (in file mycmd.txt):

# mycmd.txt
--reportfile C:\report.xml

This command file could be used with the xml2jira tool as follows:

xml2jira --server http://jira:8080 --user alice --password al1ce --project SampleProject --component tests --commandfile C:\mycmd.txt

7.4.13. configure

If you want to build Squish from source you must begin by running configure so that information on your system can be gathered—for example, where your scripting language interpreters are, where your toolkit(s) are located, and so on.

Although all of configure's command line options are optional, if configure cannot find a component you want to use, you may need to use the command line options to provide the necessary details.

Usage:

configure [options]

Three groups of options are supported: enabling, disabling, and “with” (used to set paths and filenames). Below, we list almost all of the available options (the full list is given by running configure -h).

[--disable-64bit]
[--disable-all]
[--disable-debug]
[--disable-language]
[--disable-examples]
[--disable-explorer]
[--disable-ide]
[--disable-idl]
[--disable-pure-qt4]
[--disable-runner]
[--disable-server]
[--disable-wrappers]
[--enable-64bit]
[--enable-all]
[--enable-debug]
[--enable-language]
[--enable-examples]
[--enable-explorer]
[--enable-ide]
[--enable-idl]
[--enable-pure-qt4]
[--enable-runner]
[--enable-server]
[--enable-wrappers]
[--with-java-home=dir]
[--with-pbsdk=dir]
[--with-perl=path]
[--with-pydir=dir]
[--with-python=path]
[--with-qcdir=dir]
[--with-qtdir=dir]
[--with-qtimplibdir=dir]
[--with-qtnamespace=namespace]
[--with-ruby=path]
[--with-swtjar=path]
[--with-tclconfig=dir]
[--with-tkconfig=dir]

The square brackets are not part of the syntax—they indicate optional items. Here, every option is optional. For the --with-* options, dir means a directory and path means a filename (with full path).

By default, everything (except debug) is enabled, so most of the --enable-* options only make sense if you use --disable-all to disable everything, and then use individual --enable-* options to enable just those things that you want. Most of the --enable-* and --disable-* options are used when doing split builds so that you only build the necessary parts at each stage. To enable or disable a language, specify the language as js (JavaScript), perl, python, or tcl.

The --enable-64bit option is used to make Squish able to test 64-bit applications. The --enable-debug option is used to build a debug version of Squish—something very rarely necessary.

The --with-* options are used to provide directories or paths (filenames with full path) of components that configure failed to find, or where you want to ignore what configure found and specify your own choice. For example, if you are using the Qt toolkit you might have two or more versions of Qt installed and want to tell configure which one you want Squish to use.

The --with-java-home option is used to specify the directory where the Java™ Development Kit (JDK) is installed.

The --with-pbsdk option is used to specify the directory where the PowerBuilder SDK is installed.

The --with-perl option is used to specify the path (filename with full path) where the Perl interpreter (i.e., the Perl executable) is installed.

The --with-pydir option is used to specify the directory where Python is installed. An alternative is to use the --with-python option to specify the path (filename with full path) where the Python interpreter (i.e., the Python executable) is installed.

The --with-qcdir option is used to specify the directory where the Mercury Quality Center libraries are installed.

The --with-qtdir option is used to specify the directory where Qt is installed. In some (unusual) setups, Qt's library (.lib) files are in a non-standard location; in such cases use the --with-qtimplibdir option to specify the appropriate directory.

The --with-qtnamespace option is used to specify the namespace that is used to wrap Qt library code in. This is needed for Qt libraries configured using the -qtnamespace switch.

The --with-ruby option is used to specify the path (filename with full path) where the Ruby interpreter (i.e., the Ruby executable) is installed.

The --with-swtjar option is used to specify the path (filename with full path) where the Java/SWT .jar file is installed.

The --with-tclconfig option is used to specify the directory where the Tcl tclConfig.sh file is installed.

The --with-tkconfig option is used to specify the directory where the Tcl/Tk tkConfig.sh file is installed.