The plugin is supplied as a .zip file.

	Note
	This add-on must be bought separately. Contact <sales@froglogic.com> for details.

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

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:

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.

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:

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: