Running GUI tests in parallel on a single host

Last edited on


This article demonstrates how to setup running Squish tests in parallel on a single agent host using TeamCity with Squish plugin installed. This solution takes advantage of the virtual display (Xvfb) and TeamCity feature Shared Resources. Additionally TeamCity is configured with two local agents running on Linux host, however users can setup any number of local or remote agents. For the Squish plugin installation please refer to the Squish JetBrains TeamCity integration documentation.

Xvfb setup

In order to run multiple GUI tests at the same time we must setup a virtual display server, which performs all graphical operations in memory without showing any screen output. The number of running virtual servers must equal the number of tests run in parallel. In our case we are running two tests at the same time, so we are running two Xvfb processes. One is running for display :12 and one is running for display :13.

/usr/bin/Xvfb :13 -screen 0 800x600x24
/usr/bin/Xvfb :12 -screen 0 800x600x24

Project setup - Configuration Parameter

In order to run GUI automated tests in parallel we will setup a TeamCity project with two Build Configurations. Each Build Configuration can contain multiple Squish Runner Build Steps. Next in the Projects Settings, Parameters section we will add the SQUISH_DIR Configuration Parameter whose value is equal to the Squish installation directory (at agent host).

Project Settings -> Parameters

Shared Resources definition

When running Squish GUI Tests two resource types must be shared among all build configurations. For setup that excludes the possibility that two build configurations are using the same resource at the same time (if we run them on the same host). One of the resources is DISPLAY, because two GUI tests can not be run at the same time using only one display. We can add new resource in the Project Settings, Shared Resources section by clicking the Add new resource button.

Adding DISPLAY shared resource

In order to run GUI tests in parallel we must run multiple squishserver processes, each of whom listen on separate port number. The squishserver process will be started automatically on the agent host by the Squish plugin using the correct port and display number.

Build Features

Next, for each Build Configuration we need to add build feature of Shared Resources type. In Build Configuration Settings go to section Build Features and press Add build feature button. We need to add locks of "Lock any value" type for DISPLAY resource.

Adding lock to DISPLAY shared resource

Build Step: Squish Runner

Finally, we can setup the Squish Runner build step for both Build Configurations to be run in parallel. For the Installation root enter %SQUISH_DIR% and for the Display number enter %teamcity.locks.readLock.DISPLAY%. Also ensure the Start/stop squishserver checkbox is selected.

Build Step


We are done 😊