Helix ALM integration
Helix ALM, formerly known as TestTrack TCM, is a test management tool from Perforce. (For more about Helix ALM, see perforce.com.)
Squish tests can be executed from within Helix ALM by a program called squishTcmAgent. This script agent will process a
.squishtcm description file which contains all the information necessary to run a Squish test.
The plugin is supplied as a
Note: This add-on must be bought separately. Contact email@example.com for details.
zip file contains the plugin compiled for Linux and for Windows. For Linux use the file which ends with
.tar.gz, for Windows use the file which ends with
.zip. To install the plugin unzip the respective
.zip file and copy the squishTcmAgent executable and the defaultTestCaseResolver executable into the Helix ALM's script agent directory. The default directory is called
ScriptAgents and is located inside the Helix ALM installation directory.
To run Squish tests within Helix ALM it is necessary to associate the
.squishtcm file with the Squish script agent. This can be done inside Helix ALM by clicking to invoke the Local Options dialog.
Inside the Local Options dialog, click the View File item in the list shown on the left to invoke the View File Settings dialog. Use this dialog to associate the
.squishtcm file extension with the squishTcmAgent executable.
The View File Settings dialog
Note that the path to the executable may be different from that shown in the screenshot, so adapt the path as necessary depending on where you installed Helix ALM.
.squishtcm file describes the Squish test which should be executed. The file is formatted as plain text with one
key/value item per line. Two
key/value pairs must be specified:
|testCase||Name of the test case|
|configFile||Name of the used configuration file|
For maximum flexibility, the test case folder which is needed to run a Squish test is provided by a program called testCaseResolver. The default testCaseResolver which is shipped with the plugin ( defaultTestCaseResolver ) simply echos the value which has been assigned to the
testCase key of the
.squishtcm file. Thus to use the default testCaseResolver the absolute path to the test case folder has to be assigned to the
An alternative is to write a custom testCaseResolver program. When executed the program is passed the value which has been used for the
testCase key of the
.squishtcm file, as its sole command line argument. The plugin expects that the testCaseResolver will respond by outputting the absolute test case path to
stdout. The path to the testCaseResolver must be specified inside the configuration file.
The plugin uses the environment variable
SQUISH_TCM_CONFIGDIR to search for the configuration file which is named inside the
.squishtcm file for the
The configuration file describes the general settings which are used to execute a Squish test case.
|squishDir||Path to the Squish root directory||yes|
|testCaseResolverPath||Absolute path to the testCaseResolver which is responsible for providing the absolute path of the test case folder to the plugin on ||yes|
|testCaseResolverScript||Absolute path to a script which is executed by the testCaseResolver which is specified by the ||yes / no|
|wrapper||The wrapper Squish needs to use||yes|
|aut||This can be omitted if the test case uses the ApplicationContext startApplication(autName) function to start the AUT; otherwise the AUT must be specified||no|
|cwd||This can be omitted if the default behavior of using the current working directory is acceptable; otherwise see the ||no|
|host||This can be omitted if the squishserver should be started locally; otherwise set this to the IP Address or host name of the remote PC where squishserver is running||no|
|port||This can be omitted if the default behavior of using any random free port is acceptable; otherwise specify a port||no|
|objectMapPath||The absolute path to the object map which is used by the test case||no|
|preExecutable||The absolute path to an executable which will be executed at the beginning of a test case. The current working directory where the result and log files are stored is passed as argument.||no|
|postExecutable||The absolute path to an executable which will be executed at the end of a test case. The current working directory where the result and log files are stored is passed as first argument and the test run ID is passed as second argument.||no|
|pythonExecutable||Absolute path to a Python interpreter. This is only required if the Squish package specified by the ||yes / no|
As the table shows, the paths to the Squish directory and to the testCaseResolver program are required, as is the wrapper to use, while the other
key/value pairs are—or can be—optional.
Note that if Windows-style paths are used each backslash must be escaped and the paths quoted; however, on all platforms, forward slashes can be used instead and these do not require escaping. (Paths that contain spaces must be quoted though.)
This example shows how to setup the configuration and
.squishtcm files to run a Squish test in Helix ALM. It uses the test case
tst_adding from the test suite
suite_py of a Squish for Qt package. Squish is assumed to be installed at
C:\Squish, the test suite is located inside the Squish folder at
First of all we decide to not use the default testCaseResolver as we don't want to specify the absolute path to the test case folder inside the
.squishtcm file. If we would use the absolute path, every time the location of the test case folder changes we would have to touch the
.squishtcm file attached to the Helix ALM test. This can happen for example if the test should be executed on another host.
For this example we'll create a Python script at
C:\myTestCaseResolver.py and use it as testCaseResolver. The Python script is quite simple, it just prepends the absolute path to the test suite to the test case name and prints this path to
import sys testCaseName = sys.argv print "C:\\Squish\\examples\\qt4\\addressbook\\suite_py\\" + testCaseName
The next step is to create the configuration file. The configuration file can have any file extension or none. For the example we'll create the configuration file at
C:\master_win32 with no file extension:
squishDir="C:\\Squish" testCaseResolverPath="C:\\Squish\\python\\python.exe" testCaseResolverScript="C:\\myTestCaseResolver.py" wrapper="Qt" objectMapPath="C:\\Squish\\examples\\qt4\\addressbook\\suite_py\\objects.map"
We have to specify where Squish is installed by the
squishDir key. As we want to use a Python script as testCaseResolver we specify the script by the
testCaseResolverScript key and as the plugin needs to know how to run a Python script we need to specify a Python interpreter too by the
testCaseResolverPath key. Fortunately the default Squish packages for Windows are shipped with a Python interpreter inside the Squish sub folder
C:\Squish\python so we can use that one. Finally we need to specify the wrapper and the absolute path to the object map as the test case
tst_adding uses symbolic names which are stored inside the object map.
After the configuration file has been created we need the
.squishtcm file which will be attached to the Helix ALM test later. For the example we'll create the
.squishtcm file at
C:\test_a.squishtcm. The content consists of two lines:
The first line specifies the test case we want to execute. As we're using our Python script as testCaseResolver which prepends the absolute path to the test suite, we can just enter the name of the test case. The second line specifies the configuration file we want to use. Here we've to enter only the file name of the configuration file but not its absolute path. In which path the plugin will search for configuration files will be configured by using the environment variable
SQUISH_TCM_CONFIGDIR. The reason for this is similiar to why we're not putting an absolute path into the
.squishtcm file. If the test case should be executed on a different host which installed Squish e.g. at
S:\tools\squish we only have to create a separate configuration file for this host in which the Squish installation path of the
squishDir key is adapted. Again, the
.squishtcm file which resides inside Helix ALM has not to be touched for this.
Before starting Helix ALM we need to setup the environment variable
SQUISH_TCM_CONFIGDIR to tell the plugin where to search for configuration files. To do this we can either setup the environment variable inside Windows or create a batch file which does this for us. Let's create a batch file at
set SQUISH_TCM_CONFIGDIR=C:\ "C:\Program Files\Perforce\HelixALM\TestTrack Client.exe"
which assumes that Helix ALM is installed at
After the custom testCaseResolver, configuration and
.squishtcm files have been created and Helix ALM is started by using the batch file
C:\helixalm.bat create a test case inside Helix ALM and switch to the test case's Files tab:
The Edit Helix ALM Test Case view
Now click the Select Scripts... button to choose the
C:\test_a.squishtcm description file:
The Select Scripts dialog
Close the Select Scripts dialog by clicking the OK button and apply the changes by clicking the Apply button. To run the Squish test select the recently added script in the Files tab and click the Run Script... button. This will cause the test to be run and the Script File Status dialog to appear.
The Script File Status dialog
After the test has finished the results file can be shown by clicking the Script File Status dialog's View Results... button:
A Squish Tests Results inside Helix ALM
The results shown are only stored temporarily; as soon as the Script File Status dialog's OK button is clicked the results are deleted. This happens because Helix ALM associates executed tests with test runs which have to be generated for the test case.
The temporary results are written to the
ScheduledScripts directory inside the Helix ALM installation path. The directory contains the following files after running a Squish test:
|A copy of the Squish description file.|
|An interface file for synchronizing Helix ALM and the squishTcmAgent.|
|The test results in HTML format.|
|The test results in XML format.|
|The squishTcmAgent program's log file.|
|The squishserver's log file.|
|The squishrunner's log file.|
© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.