The AUT Path is a variable in squishserver's settings which specifies a list of paths (just like the operating system's own PATH environment variable). When the squishserver is given the name of an AUT to start, it searches all of the paths in the AUT Path variable, and as soon as it finds a path that contains an executable with the name it was given, it starts it running.

To add a path to the squishserver's AUT Path variable, execute:

squishserver --config addAppPath <path>

To remove a path from the AUT Path variable, execute:

squishserver --config removeAppPath <path>

The same can be done using the Squish IDE's Manage AUTs dialog (click Squish|Manage AUTs... to invoke it). To add a path to the AUT Path, click on the AUT Paths item, then click the Add... button and choose a path from the file dialog that pops up. Similarly, to remove an AUT Path, expand the AUT Paths item, click the unwanted path, then click the Remove button.

Instead of having the squishserver look through all the AUT Path's paths for an AUT's executable, we can create mappings that directly relate AUT names to their corresponding paths. If we do this, when the squishserver is given the name of an AUT to execute, it starts by seeing if the name is mapped to a path—and if it is, squishserver starts the application directly using the mapped path. This avoids the (usually insignificant) overhead of searching all the AUT Path's paths.

An additional benefit of using the mapping approach is that it prevents the possibility of accidentally executing the wrong AUT. (Without using a mapping this could happen if two different executables have the same name and when trying to execute one of them the other is unintentionally executed because its path comes earlier in the AUT Path list.)

To map the application myapplication to the path /home/jane/bin/, execute:

squishserver --config addAUT myapplication /home/jane/bin

This way, if squishserver is given the name myapplication to start, it will not search all the paths in the AUT Path list, but instead will use the mapped path and directly execute /home/jane/bin/myapplication.

It is just as easy to remove a mapping:

squishserver --config removeAUT myapplication /home/jane/bin

When a new test suite is created using the Squish IDE and the AUT is specified in the New Test Suite wizard, behind the scenes, the Squish IDE calls the squishserver with the addAUT option to add the new AUT as a mapped AUT.

The same can be done using the Squish IDE's Manage AUTs dialog (click Squish|Manage AUTs... to invoke it). To add a mapped AUT to the Mapped AUTs, click on the Mapped AUTs item, then click the Add... button and choose an AUT from the file dialog that pops up. Similarly, to remove a mapped AUT, expand the Mapped AUTs item, click the unwanted mapping, then click the Remove button.

In some cases an application needs a special environment to be set up before it can be started successfully. This might include setting some environment variables, running a helper application, or checking for some other conditions (e.g., if there is enough memory available). Usually this is done by using a shell script or Windows batch file to do this pre-initialization work and which then starts the actual application. More information about such shell scripts and batch files is given in the section, Shell Scripts and .bat-Files as AUT (Section 16.4.4).

However, if all that is required to run an application successfully is to set up some environment variables, there is no need to create a shell script or batch file at all, since this can be handled by Squish. And in fact, the preferred approach when only environment variables are needed, is to let Squish take care of them.

Note that when the AUT is run it receives the environment that Squish provides for it, and in addition Squish always adds two additional environment variables: SQUISH_TESTSUITE_NAME and SQUISH_TESTCASE_NAME.

To specify additional environment variables, open the Squish IDE's Settings view (Section 17.2.13), and scroll to the Environment area, as shown in the screenshot.

The Squish IDE's Test Suite Settings Environment section

The values may themselves be or contain references to other environment variables using the syntax $(NAME), as the screenshot illustrates.

The table always shows a blank row into which a new key (environment variable name) and value can be entered. Just click a cell in the table to start adding or editing a key or value. To delete a row, delete the key and click elsewhere.

Now, whenever the squishserver is told to run the AUT, it will first set up the environment in the normal way, then add the environment variables that identify the suite and test case, and then add any environment variables that we have set here, so that when the AUT starts it has the context we want.

Note

Squish recognizes its own set of environment variables which can be set to affect aspects of Squish's behavior. Those that are used to control aspects of running and recording tests can be set in the Test Suite Settings dialog's Environment tab as described above. (For an example of such an environment variable, see Using an environment variable (Section 16.4.7.2.2) in Wrapping custom Java™ classes (Section 16.4.7).) However, those environment variables that affect how Squish's IDE and command line tools behave must be set before running the Squish IDE or tools, and so cannot be set in the Test Suite Settings dialog; see Environment Variables (Section 16.6) for more about these environment variables, and also for details of how test scripts can access an AUT's environment variables.

Note

Unix-only: Even when using a shell script as the AUT, it is still necessary to make the actual executable that will be run known to Squish. The reason for this is that Squish will only hook into programs started by the AUT that are white-listed, and when using a shell script as the AUT, the actual application binary, which Squish must hook into, will be started by the script and not directly by Squish. White-listing is easily done by simply adding the executable as known AUT to Squish by mapping its path or by adding its path to the AUT Path list—either method can be done in the Squish IDE or by using Squish's command line tools; see AUT Paths and Mapped AUTs (Section 16.4.2) for details.

On Unix and Mac OS X using a shell script works as expected—assuming the actual application's executable is known to Squish as mentioned in the note above.

On Windows, once the batch file is created, it is necessary to make one small adjustment to the line where the application is started. To allow Squish to hook into the application, the AUT must be started with a small wrapper application called dllpreload.exe.

The change is easy to make. Let's assume that the application we want to test is called myapp.exe. Normally we could run it simply by putting its name in the batch file on a line of its own like this:

myapp.exe

But to make it accessible to Squish we must run it from the wrapper, so we must change the line to this:

%SQUISH_PREFIX%\bin\dllpreload.exe myapp.exe

The environment variable, SQUISH_PREFIX, is set if the AUT was started through squishserver; it points to Squish's base directory.

This will start myapp.exe and allow Squish to hook into it. But in practice you only want to do this when testing the application, otherwise the application should be started normally. This can be done by putting the following code into the batch file at the point where the application binary should be started:

IF "%1"=="-testing" (
	%SQUISH_PREFIX%\bin\dllpreload.exe myapp.exe
) ELSE (
	myapp.exe
)

By default, myapp.exe will be run normally. To make it run inside Squish's wrapper we must specify -testing as an argument in the Test Suite Settings dialog's Arguments field, so that it will be passed to the AUT (the batch file in this case) by Squish on startup.

Squish hooks into Java™ applications by providing a customized Java VM shared library, the Squish Java VM. To make the standard Sun Java™ launchers (java, java.exe, javaw.exe, javaws, and javaws.exe) use the Squish Java VM, Squish sets the environment variable JDK_ALTERNATE_VM to the directory of the Squish Java VM shared library file. The standard Sun Java™ launchers support this environment variable.

Unfortunately, Eclipse does not support the JDK_ALTERNATE_VM mechanism, and so must be explicitly told which VM to use. This is easily done by calling Eclipse with the -vm option.

For example, on Windows, instead of executing eclipse.exe myapp, we would do this instead:

eclipse.exe -vm "%JDK_ALTERNATE_VM%" myapp

Note that the -vm option should be passed before any other option.

There is no need to use the -vm option when running an Eclipse/RCP application using eclipse.exe from within Squish, since Squish will automatically pass the appropriate -vm itself.

The .ini file's format is illustrated by the example below, which asks Squish to wrap two classes, com.example.product.Example, and com.example.product.Main.

[general]
AutClasses="com/example/product/Example", "com/example/product/Main"

The class names must be relative to the CLASSPATH. Note also, that it is possible to wrap classes in Java™'s standard libraries if they aren't wrapped by default, for example:

[general]
AutClasses="java.util.Calendar","java.util.Date",\
"java.text.DateFormat","java.text.SimpleDateFormat"

When an extra class is wrapped, all super classes, classes from method arguments and return type classes will be wrapped as well.

In some cases it is possible that the wrapping could fail. If this happens the class that failed to be wrapped will be identified as having type Unknown in the Spy tool.

Additionally, an extra CLASSPATH can be set that might be needed if the application extends its CLASSPATH during execution. For example, when testing Java™ applets with Squish for Web, the CLASSPATH is extended by the ARCHIVE attribute of the APPLET HTML tag. So, continuing from the first example, a CLASSPATH setting can be added as shown below.

[general]
AutClasses="com/example/product/Example", "com/example/product/Main"
AutClassPath="demo.jar"
AutClassBaseUrl="http://www.example.com/product/"

The AutClassPath entry uses the same syntax as the CLASSPATH environment variable, with ';' (Windows) or ':' (Mac/Linux/Unix) used as separators. The entire value must be quoted, as shown in the example.

It is also possible to set an AutClassBaseUrl. This is optional, but when set it adds a prefix to all paths in the AutClassPath entry and the AutClassBaseUrl itself is added to the CLASSPATH.