squishserver

The squishserver is responsible for handling the communications between the squishrunner and the application under test. It has has three modes of use: serving, stopping, and configuring.

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: Squish does not create a squishserverrc file. If you need one, create it manually using a plain text editor.

Serving

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

Usage

squishserver [--quiet] [--verbose] [--configfile configfile] [--host address] [--port port] [--local] [--listenfile listenfile] [--daemon [--logfile logfile]] [--disable-presence]

The items in square brackets are optional.

Options

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.

Another useful option is --host address to specify the IP address to listen on. The default is is to accept connections on any IP address assigned to the machine where squishserver is running.

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. Anything that the AUT prints to these channels will be lost, unless also the --logfile with full path to a file name is given. There is no point using the --verbose option when the --daemon option is used without a log file.

The --disable-presence option disables SSDP service discovery. By default, the squishserver advertises that it exists on the LAN using this protocol.

The --local option is used internally by the Squish IDE when starting local squishservers. It is not meant to be used by end users. This option disables SSDP discovery and listens to 127.0.0.1 by default. It chooses a port between 49152 and 65535, and prints it to standard output.

Stopping

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

Usage

squishserver --stop [host address] [port port]

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.

Configuring squishserver

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

Usage

squishserver --config action

Most of these configuration commands operate on the server.ini file by default, which is in ver1 of the Squish User Settings Directory. You can provide the location of a different configuration file by using the --configfile option.

squishserver [--configfile /path/to/myserver.ini] --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.)

Examples

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

This will add the C:\squish\examples\qt\addressbook path to Squish's list of paths in which to look for AUTs.

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).

squishserver --config addAUT addressbook $(SQUISHPATH)/examples/qt/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.

Actions

OptionDescription
addAppPath pathAdds a path to the list of paths in which squishserver looks for applications when starting an AUT.
removeAppPath pathRemoves a path from the list of paths in which squishserver looks for applications when starting an AUT.
addAUT aut pathAdds 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 addAppPath option, specifies the one that Squish should use, thereby avoiding any ambiguity.
removeAUT aut pathRemoves an application mapped to the specified path.
addAttachableAUT aut [host:]portSpecifies an AUT that can be attached to.
removeAttachableAUT aut [host:]portUnregisters an AUT that was previously registered using the addAttachableAUT action.
setWrapperLibs aut lib1[,lib]*The wrapper library or libraries to use with the specified AUT.
setUsesBuiltinHook aut on|offEnables or disables Squish expecting a built-in hook rather than the default non-intrusive hooking. Read Using the Built-in Hook before using this option.
setAUTTimeout secondsHow 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.
setResponseTimeout secondsHow 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 different from the timeout used by the Object waitForObject(objectOrName) function.
setAUTPostMortemTimeout millisecondsHow 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.
setHardExitTimeout millisecondsHow many milliseconds squishserver should maximally wait after sending a SIGTERM to an application, before sending a SIGKILL if the application is still running. The time is added to the value of setSoftExitTimeout. This option does nothing on Windows. The default is 100 milliseconds.
setSoftExitTimeout millisecondsHow many milliseconds squishserver should maximally wait after squishrunner has ended before killing the application if it is still running, when started automatically or with ApplicationContext startApplication(autName). The default is 2000 milliseconds.
setBrowserPath browser executableA browser and the path to its executable: firefox (Firefox), ie (Microsoft Internet Explorer), edge (Microsoft Edge), or safari (Safari), chromium-based (Chromium-based application). 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.

setJavaVM filenameFull path to the location of the Java executable. For example, /usr/lib/jvm/java-6-sun/jre/bin/java on Linux.
setLibJVM filenameFull path to the location of the Java virtual machine. For example, /usr/lib/jvm/java-6-sun/jre/lib/i386/client/libjvm.so on Linux.
setJavaVersion versionThe Java version to use. For example, 1.5.0_11.
setSWTJar filenameFor Java AUTs using the SWT GUI library, the full path to the SWT library .jar file to use. For example, C:\swt\swt.jar on Windows.
setConfig aut pathRegisters a custom .jar file that implements the Java Extension API for custom widgets.
removeConfig aut pathUnregisters a custom .jar file that implements the Java Extension API.

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