Table of Contents
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 .zip
file.
![]() | Note |
---|---|
This add-on must be bought separately. Contact
|
The 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 .tar.gz
or .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.
The
| menu item
Inside the Local Options dialog, click the .squishtcm
file extension with the
squishTcmAgent executable.
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™.
The .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:
Key | Value | Example |
---|---|---|
testCase | Name of the test case | testCase = "tst_adding" |
configFile | Name of the used configuration file | configFile = "master_win32" |
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 testCase
key.
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
configFile
key.
The configuration file describes the general settings which are used to execute a Squish test case.
Key | Value | Required | Example |
---|---|---|---|
squishDir | Path to the Squish root directory | yes | squishDir = "C:\\Squish" |
testCaseResolverPath | Absolute path to the
testCaseResolver which is responsible for providing
the absolute path of the test case folder to the plugin on stdout | yes |
or:
|
testCaseResolverScript | Absolute path to a script which is executed by the testCaseResolver which is specified by the testCaseResolverPath key.
This key is only required if the testCaseResolver requires a script as argument e.g. if Python is specified at testCaseResolverPath
the Python script to be executed must be specified by using this key.
| yes / no |
testCaseResolverScript = "C:\\myTestCaseResolver.py"
|
wrapper | The wrapper Squish needs to use | yes | wrapper = "Qt" |
aut | This can be omitted if the test case uses the startApplication function to start the
AUT; otherwise the AUT must be specified | no | aut = "addressbook" |
cwd | This can be omitted if the default behavior of using the
current working directory is acceptable; otherwise see the
--cwd option at Executing a Test Case (Advanced) (Section 7.4.3.25)
for alternatives | no | cwd = "@server" |
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 | host = "192.168.0.42" |
port | This can be omitted if the default behavior of using any random free port is acceptable; otherwise specify a port | no | port = "4711" |
objectMapPath | The absolute path to the object map which is used by the test case | no | objectMapPath = "C:\\Squish\\examples\\qt4\\suite_addressbook_py\\objects.map" |
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 | preExecutable = "C:\\preTask.exe" |
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 | postExecutable = "C:\\postTask.bat" |
pythonExecutable | Absolute path to a Python interpreter. This is only required if the Squish package specified
by the squishDir key is not shipped with a Python interpreter. Python 2.4, 2.5, 2.6 or 2.7 is required.
| yes / no | pythonExecutable = "C:\\Python27\\python.exe" |
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 C:\Squish\examples\qt4\addressbook\suite_py
.
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 stdout
:
import sys testCaseName = sys.argv[1] 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:
testCase="tst_adding" configFile="master_win32"
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
C:\helixalm.bat
:
set SQUISH_TCM_CONFIGDIR=C:\ "C:\Program Files\Perforce\HelixALM\TestTrack Client.exe"
which assumes that Helix ALM™ is installed at C:\Program Files\Perforce\HelixALM
.
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:
Now click the C:\test_a.squishtcm
description file:
Close the Select Scripts dialog by clicking the Squish test select the recently added script in the tab and click the button. This will cause the test to be run and the Script File Status dialog to appear.
button and apply the changes by clicking the button. To run theAfter the test has finished the results file can be shown by clicking the Script File Status dialog's
button:A Squish Tests Results inside Helix ALM™
The results shown are only stored temporarily; as soon as the Script File Status dialog's 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:
Filename | Description |
---|---|
test_a.squishtcm | A copy of the Squish description file. |
test_a.trjob | An interface file for synchronizing Helix ALM™ and the squishTcmAgent. |
report.html | The test results in HTML format. |
report.xml | The test results in XML format. |
squishTcmAgent.log | The squishTcmAgent program's log file. |
server.log | The squishserver's log file. |
runner.log | The squishrunner's log file. |