squishrunner is used to execute and record test cases and test suites, and to set and retrieve the settings that squishrunner uses at runtime. squishrunner's command line interface looks like this:
squishrunner [server options] command [command specific options]
The optional server options are:
--host <hostname>
By default squishrunner connects to the squishserver on the local host (127.0.0.1). If squishrunner should connect to a squishserver running on a different machine, this can be specified with this option.
--port <port>
By default squishrunner tries to connect to the squishserver on port 4322 which is also the default port squishserver listens to. If you set up squishserver to listen on another port, use this option to tell squishrunner which port it should use for connecting to squishserver.
After the server options one of the following commands must be specified:
In this mode squishrunner executes a test suite or records a
test case in a test suite. In this mode a settingsGroup to be used can
be specified before the --testsuite switch using
--settingsGroup <settingsGroup>.
Example:
squishrunner --testsuite /home/reggie/squish_addressbook_py --testcase tst_add_address
The first argument after this command must be the directory that
contains the test suite. In this mode, squishrunner reads the file
suite.conf in the test suite's root
directory. The following settings are read:
AUT=<application [args]>
The application which will be started for each test case and optional
command line arguments which will be used when executing the AUT.
LANGUAGE=<lang> The
scripting language which is used for interpreting the test
scripts. Currently this may be Python,
JavaScript or
Tcl.
WRAPPERS=<wrappers> List of
wrappers which must be loaded for the tests. Currently supported:
Qt and XView. Additionally a
number of bindings libraries (application wrappers) to be loaded my be
specified.
ENVVARS=<parameter> File
which should be read and parsed to set environment variables before
executing the AUT. The file must contain
VARIABLE=VALUE pairs which define the environment
variables.
There are two different usages of this mode of squishrunner.
To execute all of a test suite's test cases, no more arguments
need to be specified. If only specified test cases from the suite
should be executed, a sequence of one or more --testcase
<testcase> options must be specified, where
<testcase> identifies a particular test case.
To influence the delay triggered by snooze
script calls can be specified with --snoozeFactor
<factor>. A value smaller than 1 will cause shorter
delays; a value greater than 1 will cause longer delays. A factor of 0
will lead to the fastest possible execution.
Optionally a different report generator to process the test
results can be specified with the --reportgen
<[reportgen],[filename]> option,
e.g. --reportgen xml,/tmp/results.xml.
The possible values for [reportgen] are
xml (XML), xls (Excel)
and stdout (ASCII table).
To record a test case in a test suite, --record
<testcase> must be specified where <testcase>
is the name of the test case which should be generated. The name
must start with the prefix
tst_.
If the test case needs some test data, the test data files can
be specified with --testdata <file>, where
file must exist either in the shared testdata directory or the test
case's testdata directory.
Optionally, event compression during recording, which detects
common event sequences and generates high-level API calls, can be
switched off with --disableEventCompression. This
is not recommended.
In this mode squishrunner executes or records one specified test case.
Example:
squishrunner --testcase tst_add_address --wrapper Qt --aut addressbook
The first argument after this command must be the test case's directory.
If you want to record a test case, specify the
--record option after the
--testcase option. If a test case is to be
recorded and requires test data, the test data files can be specified
with --testdata <file>, where <file>
must exist in the shared testdata directory or in the test suite's
testdata directory, or in the test case's testdata directory.
The next options must specify which application should be
started to execute or record the test case and the wrappers to be
used. This is done with the --aut
<application> and one or more --wrappers
<wrapper> options.
If some environment variables should be set before executing the
AUT, it is possible to specify a file which defines these variables
with the --envvars <filename> option. The
file must contain VARIABLE=VALUE pairs which
define the environment variables. Alternatively environment variables
can be specified directly on the command line via --envvar
VAR=value.
If you are recording a test case, event compression during
recording, which detects common event sequences and generates
high-level API calls, can be switched off with
--disableEventCompression. This is not
recommended.
To influence the delay triggered by snooze
script calls can be specified with --snoozeFactor
<factor>. A value smaller than 1 will cause shorter
delays; a value greater than 1 will cause longer delays. A factor of 0
will lead to the fastest possible execution.
If you are executing a test case and want to use a different
report generator to process the test results, this can be specified
with the --reportgen <[reportgen],[filename]>
option, e.g. --reportgen
xml,/tmp/results.xml.
The possible values for [reportgen] are
xml (XML), xls (Excel)
and stdout (ASCII table).
If you specify the --debug switch,
squishrunner will start an interactive command line script debugger
which allows setting break points, stepping through the code, etc. The
interface is similar to gdb's but is currently
internal and not documented. We recommend using the Squish IDE to debug
test scripts as described in Script Debugger (Section 16.8.1) in the
Squish User's Guide (Chapter 16).
In this mode squishrunner can be queried for various information.
Example:
squishrunner --info applications
The second argument defines what squishrunner will be asked about:
wrappers Prints out a list of
installed wrappers,
applications Connects to the
squishserver and prints out a list of all the applications which are
located in the squishserver's application paths and can be tested by
Squish with the current settings.
AUTTimeout Prints out how many
seconds squishrunner will wait before timing out with a test failure
if the AUT doesn't respond after being started.
cursorAnimation Returns whether
the mouse cursor should be animated (visually moved between positions)
during script playback.
pauseHotkey Returns the hotkey
which should be used to pause test execution.
settingsKey Prints out the
settings key for this Squish installation.
This option allows squishrunner's settings to be changed.
Example:
squishrunner --config setAUTTimeout 600
The following arguments are recognized:
setBaseDir <wrapper>
<dir> Creates a new wrapper called <wrapper>
with the base directory <dir>.
addInitScript <wrapper>
<script> Adds the script <script> as an init
script for the wrapper <wrapper>. <script> must be either
an absolute file name or relative to the wrapper's base directory. All
the init scripts for a wrapper are executed before the test script of
a test case which uses the wrapper.
setAUTTimeout <seconds>
Specifies how many seconds squishrunner will wait before timing out
with a test failure if the AUT doesn't respond after being started.
setCursorAnimation [on|off]
Specifies whether the mouse cursor should be animated (visually moved
between positions) during script playback.
setPauseHotkey <key>
Specifies the hotkey which should be used to pause test
execution.
In this mode squishrunner starts an interactive command line spy.
Example:
squishrunner --spy --testsuite /home/reggie/squish_addressbook_py
The spy shell is started on the already running AUT given its ID
via --aut <aut-id> or by starting the AUT
of the test suite given by --testsuite
<suite_dir>.
The interactive commandline Spy frontend is internal and we recommend using the Spy via the Squish IDE as described in Spy (Section 16.8.3) in the Squish User's Guide (Chapter 16).
squishserver, is responsible for the communication between the squishrunner and the application under test. squishserver must run on the same machine as the AUT, although squishrunner can run on a different machine.
If 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 allow connections from
other hosts, those hosts must be specified. For this purpose,
squishserver reads a file called squishserverrc
in /etc (on Unix/Linux/Mac) or
C:\ (on Windows). This file can specify the IP
addresses from which connections are allowed using the line
ALLOWED_HOSTS=<ip-addr1> <ip-addr2>
... <ip-addrn>. The port number that squishserver
listens to can be changed by creating a
PORT=<port> line in the squishserverrc
file.
The following command line options are supported by squishserver:
--port <port> Specifies the
port which squishserver should listen to. This will override any
PORT=<port> setting in the squishserverrc
file.
--config If squishserver is
started with this option, it will simply update its configuration and
terminate; it will not listen for connections.
In this mode a settingsGroup to be used can be specified before
the --config switch using
--settingsGroup <settingsGroup>
The following arguments are recognized after
--config:
addAppPath <path> Adds
<path> to the list of paths in which squishserver will look
for applications when starting an AUT.
addAUT <aut> <path>
Adds the application <aut> to be mapped with the fixed path
<path> to be known by squishserver.
removeAppPath <path>
Removes <path> from the list of paths in which squishserver
will look for applications when starting an AUT.
removeAUT <aut>
<path> Removes the application <aut> which has
been mapped with the fixed path <path> to be known by
squishserver.
--stop The server will be asked
to shut itself down. Unless overridden with --port
the server will be contacted at the default port.
--daemon The server will be run
in the background. This means it will detach itself from the
controlling terminal and stop printing anything to standard output and
standard error. Note that anything the AUT prints to these channels
will currently get lost, too.
This switch is supported on Linux \em only right now. Please enquire with support if you need this feature on other platforms as well.
squishidl is a tool which parses C++ header files and
generates C++ introspection and automation code. For each C++ header
file one .h and .cpp file
with the automation and introspection code will be created. For this
reason, squishidl must be run on every header file twice.
To generate the header file, run squishidl with the
--decl option, and specify the C++ header that
must be parsed with the -i option. For example:
squishidl --decl -i myapp.h -o generated.h
To generate the cpp file, run squishidl with the
--impl option, and specify both the C++ header
using -i, and the generated header using
-h. For example:
squishidl --impl -i myapp.h -h generated.h -o generated.cpp
All the other options can be used with both
--decl and --impl, and they
are all optional.
-o <outputfile> By default
the output is written to stdout. With this option
the output will be written to the specified file.
--dump [<dumpfile>]
squishidl creates an intermediate format after parsing the C++
header which is then processed by the output generator. For debugging
purposes this intermediate data structure can be dumped to
stdout, or to a file if specified.
-D <macro> and -U
<macro> In a similar way to the C++ compiler, macros
can be defined and undefined on the command line. The same macro
definitions as passed to the C++ compiler when compiling the input
file should be passed to squishidl. This option can be specified
multiple times.
-I <includepath> In a
similar way to the C++ compiler, include search paths can be added on
the command line. The same include paths as passed to the C++ compiler
when compiling the input file should be passed to squishidl. This
option can be specified multiple times.
--includePrefix [<prefix>]
Specifies the prefix which should be used when generating
#include statements. An empty <prefix>
means the same as specifying the current directory.
--strict If this option is on,
parse errors when parsing the C++ header file will result in fatal
errors. Otherwise, parse errors are just interpreted as
warnings.
--extraInclude [<include>]
Specifies an include file which should be included in the generated
file via an #include statement. This option can
be specified multiple times.
--filter [<expr>] Specifies
to not generate introspection and automation code for a class, global
function, class member function or template instantiation matching
<expr>. This option can be specified multiple times.
--nocache By default squishidl
caches the intermediate format and only parses the C++ header file
again if its timestamp changed. Use this option to switch off
squishidl's caching.
Arguments can also be read from Command Files (Section 17.2.5) via the
--commandFile option.
The Squish IDE is a graphical environment to record, develop, edit, debug and run tests. There are a few options supported by this GUI application.
--startclean Starts the Squish IDE
without reading any settings using default settings.
--testsuite <testsuite>
Starts the Squish IDE by opening only the test suite
<testsuite>.
Command line arguments can also be read in from a file. These so-called command files are plain text files that contain the arguments in a single line or spread over multiple lines. Sometimes this may just be a convient way to specify a complex list of arguments. In other cases this approach might be become a necessity because the maximum command line length of the underlying operating system is exceeded.
Command files can contain comments if they are prefixed with a # character as the first character of a line. Arguments containing whitespace character can be surrounded by single or double quotes as can be seen in the following example:
# mycmd.txt -i myheader.h -I /usr/local/include -I "/opt/My App/include"
An invocation using above command file could like this:
squishidl --decl --commandFile mycmd.txt
Note: as of the time of writing squishidl is the only tool supporting this feature.