9.8. Helix ALM integration

Table of Contents

9.8.1. Obtaining the Helix ALM™ Plugin
9.8.2. Installing the Helix ALM™ Plugin
9.8.3. Configuring the Helix ALM™ Plugin
9.8.4. The .squishtcm description file
9.8.5. The configuration file
9.8.6. Example: How to run a Squish test case

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.

9.8.1. Obtaining the Helix ALM™ Plugin

The plugin is supplied as a .zip file.

[Note]Note

This add-on must be bought separately. Contact for details.

9.8.2. Installing the Helix ALM™ Plugin

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.

9.8.3. Configuring the Helix ALM™ Plugin

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 Tools|Local Options... to invoke the Local Options dialog.

The Tools|Local Options... menu item

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

9.8.4. The .squishtcm description file

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:

KeyValueExample
testCaseName of the test casetestCase = "tst_adding"
configFileName of the used configuration fileconfigFile = "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.

9.8.5. The configuration file

The configuration file describes the general settings which are used to execute a Squish test case.

KeyValueRequiredExample
squishDirPath to the Squish root directoryyessquishDir = "C:\\Squish"
testCaseResolverPathAbsolute path to the testCaseResolver which is responsible for providing the absolute path of the test case folder to the plugin on stdoutyes

testCaseResolverPath = "C:\\HelixALM\\ScriptAgents\\defaultTestCaseResolver.exe"

or:

testCaseResolverPath = "C:\\Python27\\python.exe"

testCaseResolverScriptAbsolute 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"
wrapperThe wrapper Squish needs to useyeswrapper = "Qt"
autThis can be omitted if the test case uses the startApplication function to start the AUT; otherwise the AUT must be specifiednoaut = "addressbook"
cwdThis 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.23) for alternativesnocwd = "@server"
hostThis 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 runningnohost = "192.168.0.42"
portThis can be omitted if the default behavior of using any random free port is acceptable; otherwise specify a portnoport = "4711"
objectMapPathThe absolute path to the object map which is used by the test casenoobjectMapPath = "C:\\Squish\\examples\\qt4\\suite_addressbook_py\\objects.map"
preExecutableThe 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. nopreExecutable = "C:\\preTask.exe"
postExecutableThe 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. nopostExecutable = "C:\\postTask.bat"
pythonExecutableAbsolute 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 / nopythonExecutable = "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.)

9.8.6. Example: How to run a Squish test case

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:

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:

FilenameDescription
test_a.squishtcmA copy of the Squish description file.
test_a.trjobAn interface file for synchronizing Helix ALM™ and the squishTcmAgent.
report.htmlThe test results in HTML format.
report.xmlThe test results in XML format.
squishTcmAgent.logThe squishTcmAgent program's log file.
server.logThe squishserver's log file.
runner.logThe squishrunner's log file.