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]](images/note.png) | Note |
|---|---|
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. |
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.
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.
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 checkbox in the "Preferences" dialog (Section 17.3.11)'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 checkbox in the "Preferences" dialog (Section 17.3.11)'s Squish pane's Logging pane).w– log the wrapping phase (this is the same as checking the Squish IDE's checkbox in the "Preferences" dialog (Section 17.3.11)'s Squish pane's Logging pane).
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 here:
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--testsuiteand--testcaseoptions'--autoption.)ENVVARS=filenameThis specifies a file that contains one or more lines ofVARIABLE=VALUEpairs 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--testcaseoption when also using the--recordoption, by using the--envvarsoption. Alternatively, again when using the--testcaseoption when also using the--recordoption, it is possible to specify individual additional environment variables using one or more--envvaroptions.)LANGUAGE=languageThis specifies the scripting language used by the test scripts. Currently this must bePython,JavaScript,Perl, orTcl.(This can be overridden on squishrunner's command line using the--testcaseoption's--langoption.)OBJECTMAP=filenameBy default, Squish reads the test suite's object map from theobjects.mapfile 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--testcaseoption when also using the--recordoption, by using the--objectmapoption.)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--testsuiteoption without using the--testcaseoption to specify which ones, every test case will be run. If every test case is run and thisTEST_CASESoption 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--testcaseoption.)WRAPPERS=wrappersThis lists the wrappers which must be loaded for the tests to run successfully. Currently supported areQtandXView. 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--testcaseoption's--wrapperoptions.) 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.
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 16.5.1.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 16.5.1.2).
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.
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 new 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 three other-options:
[--reportgen report-generator[,filename]] |
[--testcase test-case-dir]* |
[--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.
Squish can output a report detailing what happend 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,filename
option. For example, --reportgen xml2,/tmp/results.xml.
(Notice the comma "," which is essential.)
The report-generator can be any one of:
xml2.1 (XML, preferred Squish 4 format, not
available for Squish 3), xml2 (XML, preferred
Squish 3 format), xml (XML, old format, kept for
backward compatibility), xmljunit (same output as JUnit
tests; less informative that Squish's native XML formats, not
available for Squish 3), xls (Excel™) and
stdout (ASCII plain text table). All the generators
output to the console unless a filename is specified, in which case the
output is to the specified file. (If the specified file already exists,
it is preserved and the output is written to a new file which uses the
specified filename but with _1 appended.)
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 using a --testcase
test-case-dir option for every test case
we want executed.
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
(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 16.5.1.2).)
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 16.5.1.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 16.5.1.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 many other-options:
[--useWaitFor] |
[--testdata testdata]* |
[--disableEventCompression] |
[--snoozeFactor factor] |
[--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.
Adding the --useWaitFor option is strongly recommended
since it leads to the recording of calls to the waitForObject function which are more reliable
than using the snooze function.
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.
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),
konqueror (Konqueror).
mozilla (Mozilla), or
safari (Safari).
Additionally, a --webbrowserargs option can be
passed to invoke the chosen web browser with your choice of command line
arguments.
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 16.5.1.2).)
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 Executing Test Cases (Section 16.5.1.3)
and Recording a Test Case (Section 16.5.1.4).
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 16.5.1.1). The
other-options are discussed shortly.
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] |
[--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] |
[--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 exectue, 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.
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 Python,
JavaScript, Perl, 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 happend 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,filename
option. For example, --reportgen xml2,/tmp/results.xml.
(Notice the comma "," which is essential.)
The report-generator can be any one of:
xml2.1 (XML, preferred Squish 4 format, not
available for Squish 3), xml2 (XML, preferred
Squish 3 format), xml (XML, old format, kept for
backward compatibility), xmljunit (same output as JUnit
tests; less informative that Squish's native XML formats, not
available for Squish 3), xls (Excel™) and
stdout (ASCII plain text table).
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.
Unless the Object Map (Section 16.10) is loaded by the test case
itself using the objectMap.load function,
the object map must 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),
konqueror (Konqueror).
mozilla (Mozilla), or
safari (Safari).
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.
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, or
responseTimeout.
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 |
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 16.5.1.7).)
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 16.5.1.7).)
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
to establish communication with the AUT before failing.
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 addInitScript wrapper
script |
--config addWebExtension script |
--config setAUTTimeout seconds |
--config setResponseTimeout seconds |
--config setCursorAnimation on|off |
--config setPauseHotkey key |
--config setDefaultWebBrowser browser |
--config setAttachableAUT aut
[host:]port |
--config removeAttachableAUT aut
[host:]port |
Use the setBaseDir action to create a new wrapper with
the given wrapper name and with
the given base directory.
Use the addInitScript action to specify the filename of
a 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.
For web applications, use the addWebExtension to
specify a JavaScript script file that implements Squish's JavaScript
Extension API. (See How to Use the JavaScript Extension API (Section 15.8).)
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 16.5.1.6).)
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 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 16.5.1.6).)
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 16.5.1.6).)
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),
konqueror (Konqueror).
mozilla (Mozilla), or
safari (Safari).
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.
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). This file can
specify the IP addresses from which connections are allowed using a line
of the form ALLOWED_HOSTS=ip-address1
ip-address2 .... The port number that
squishserver listens to can be changed by adding a line of the form
PORT=port to the squishserverrc
file.
The squishserver has three modes of use: serving, stopping, and configuring, all of which we will cover here.
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.)
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.)
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 new 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 setBrowserPath browser executable |
--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 16.12.2).
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.
Use the setResponseTimeout action to specify how long
Squish should wait before timing out with a test failure when waiting
for a response from the AUT. (This is distinct from the timeout used by
the waitForObject function.)
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),
konqueror (Konqueror).
mozilla (Mozilla), or
safari (Safari),
and the executable should include the full path to the browser's
executable.
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 How to Use the Java Extension API for Custom Widgets (Section 15.9).)
Use the removeConfig action to unregister a custom
.jar file that implements Squish's Java Extension
API. (See How to Use the Java Extension API for Custom Widgets (Section 15.9).)
The squishserver has some other configuration options, specifically,
usesBuiltinHook and setJavaHookMethod;
these are for backward compatibility; they should not be used now.
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 Mac OS X 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 16.5.8).
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 15.7).
The Squish IDE is a GUI tool used to create, record, modify, debug, and run tests.
squishide
This is the new IDE introduced with Squish 4.0. When the Squish IDE is started it restores the previous session—that is is 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.
The Squish IDE is a GUI tool used to create, record, modify, debug, and run tests.
squish [--startclean|--testsuite testsuite]
This is the Classic IDE that is available for all versions of Squish. Users of Squish 4 and later are recommended to use the New IDE instead.
By default, when the Squish IDE is started with no command line options, it restores the previous session—that is is 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.
If the --startclean option is specified the Squish IDE will
start up without reading any of its saved settings and will rely instead
on the default settings. This means that no workspace will be restored.
If the --testsuite testsuite
option is specified, the Squish IDE will read its settings as normal and
start up normally—except that instead of opening the previous
session's test suites, it will only open the specified test suite.
startaut is an application that runs an AUT that is to be attached to by Squish.
Usage:
startaut [--verbose]
--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. Either the --port
option or the --uses-builtin-hook
must be specified. And of course 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 Running Applications (Section 16.8.2) for an explanation of how to make use
of this tool with the --port option, and Attaching to a Running Application with the Built-in Hook (Section 16.12.2.3) for how to use this tool with the
--uses-builtin-hook option.
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.
Command line arguments can also be read in from a file. These “command” files are plain text files that contain the command line arguments in a single line or spread over 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. Also, 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 on the command line—including quoting
for any included whitespace. Blank lines are ignored as are comment
lines (those beginning with #).
Here is an example command file (in file mycmd.txt):
# mycmd.txt -i myheader.h -I /usr/local/include -I "/opt/My App/include"
This command file could be used with the squishidl tool as follows:
squishidl --decl --commandFile mycmd.txt
Note: at the time of this writing, squishidl is the only Squish tool that supports this feature.
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-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-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.