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 Edit|Server Settings|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 Edit|Server Settings|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.

See also, the Manage AUTs panel (Section 8.3.22.1).

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 7.3.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 started with startApplication(), it receives the environment that squishserver provides for it.

To specify additional environment variables, open the Squish IDE's Test Suite Settings view (Section 8.2.16), 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.

Squish vs. AUT Environment Variables

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 Section 7.3.8, “Using an environment variable” in Wrapping custom Java™ classes (Section 7.3.8.2).) 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 7.5) for more about these environment variables, and also for details of how test scripts can access an AUT's environment variables. It is also possible for test scripts to access environment variables; see How to Read Environment Variables inside Test Scripts (Section 5.17.3).

Unix-specific

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 7.3.2) for details.

On Unix and macOS 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.

See also Record / Replay on Sub-Processes started by the AUT (Section 7.7) and Attaching to Running Applications (Section 7.8).

Squish hooks into Java™ applications by providing a customized Java VM shared library, the Squish Java VM. To make the standard Oracle 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 Oracle 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, we would do this instead:

eclipse.exe -vm "%JDK_ALTERNATE_VM%" -noSplash

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.

By default, when picking an object, Squish will show the generated object name in a tooltip of the object being hovered with the mouse. However this may drag when the user interface is quite complex. Therefore it is possible to override this behavior. The option is called ObjectPickerTooltip and must be under section Java Wrapper. E.g.

[Java Wrapper]
ObjectPickerTooltip = "ClassName"

to only show the object its Java™ class name. Alternatively, tooltips can be turned off entirely by using Off.

By default, Squish 3 wraps a predefined set of Java™ classes. Scripts can access static class members only for these wrapped classes. Classes of wrapped Java™ objects automatically get wrapped by Squish. That happens e.g. when using findObject, waitForObject or accessing a class member that returns an object.

Squish 4 extend's Squish 3's functionality in this area by wrapping more classes, and also by dynamically wrapping AUT classes.

No matter which version of Squish is being used we might need to access a class that for some reason isn't wrapped by default. One way of doing this is to extend the list of wrapped classes, making additional classes accessible just like the predefined wrapped classes. This is done by creating a .ini file that lists the classes that must be wrapped, and then telling Squish's wrapper for the Java™ process where to find this file. This is discussed in a moment— Creating the .ini file (Section 7.3.8.2.1).

The easiest way to access unregistered classes is to use Java's introspection capabilities. This is done in a few easy steps:

Here is an example (taken from the examples/java/paymentform/suite_*/tst_card_mode test case) where we want to use the java.text.SimpleDateFormat class even though Squish doesn't wrap it by default and even though it isn't used in the AUT (and so doesn't get dynamically wrapped).

    java_lang_Class.forName("java.text.SimpleDateFormat")
    formatter = java_text_SimpleDateFormat()
    formatter.applyPattern("yyyy-MM-dd")
    test.verify(formatter.format(model.getStart()) ==
                formatter.format(date))

    java_lang_Class.forName("java.text.SimpleDateFormat");
    var formatter = new java_text_SimpleDateFormat();
    formatter.applyPattern("yyyy-MM-dd");
    test.verify(formatter.format(model.getStart()) == 
                formatter.format(threeYearsAgo));

    java_lang_Class::forName("java.text.SimpleDateFormat");
    my $formatter = new java_text_SimpleDateFormat();
    $formatter->applyPattern("yyyy-MM-dd");
    test::verify($formatter->format($model->getStart()) eq
                 $formatter->format($date));

    LC::Java_lang_Class.forName("java.text.SimpleDateFormat")
    formatter = LC::Java_text_SimpleDateFormat.new
    formatter.applyPattern("yyyy-MM-dd")
    Test.verify(formatter.format(model.getStart()) ==
    formatter.format(date))

    invoke java_lang_Class forName "java.text.SimpleDateFormat"
    set formatter [construct java_text_SimpleDateFormat]
    invoke $formatter applyPattern "yyyy-MM-dd"
    set minimumAllowed [invoke $formatter format [invoke $model getStart]]
    set minimumDate [invoke $formatter format [invoke $calendar getTime]]
    test compare $minimumAllowed $minimumDate

Another example of this technique is shown in How to Create Semi-Automatic Tests that Query for User Input (Section 5.14).

If this approach is used there is no need to create or register classes using a .ini file. However, if you need to access a lot of different unwrapped classes, using a .ini file might prove more convenient.

7.3.8.2.1. Creating the .ini file

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"

	Applications using custom ClassLoaders
	For applications like Eclipse, either using an ini file or using forName might load the class in the wrong classloader instance or the default classloader cannot find the class. In these cases use application class loaders to get a Java™ class wrapped into Squish.

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.

7.3.8.2.1.1. Excluding properties

The automatic addition from public getter function as property (see How to Access Java™ Object Properties (Section 5.4.3)) to the wrapped class is not always desirable. When traversing the application object tree these properties will be fetched. That will subsequently call the getter method.

To exclude a certain property use JavaWrappingBlackList. This config option takes a list of one of more class.property names. The class package separator must be a slash. E.g.

[general]
JavaWrappingBlackList="java/awt/Component.locationonscreen"

Squish can be told about native Windows controls simply by putting some information into a suitable .ini file. (This is very similar in principle to how Java™ classes are handled; see Wrapping custom Java™ classes (Section 7.3.8.2).)

It isn't necessary to create the file from scratch. Instead, copy the winwrapper.ini file from Squish's etc folder, and then modify this file as described in the following sections.

Registering the new INI file

Once you have copied and modifed the winwrapper.ini file, you must let Squish know that the file exists so that Squish will read it when necessary. This is done by registering the file for each AUT that you want to be able to make use of it. (See AUT .ini file for Wrapper (Section 7.3.8).) Using a copy of the winwrapper.ini file rather than the original ensures that you can always refer to the original file—for example, to see the default values of the various configuration items. And, of course, when you upgrade Squish, your copied file won't get overwritten (so long as you don't keep it in Squish's directory).

If you already have an .ini file (perhaps because you created one to work with Squish for Java™—as described in Wrapping custom Java™ classes (Section 7.3.8.2)), you can use the existing file, and simply add new Windows-specific lines to it. (Squish doesn't care what the file's name is or where it is located, so long as it is a .ini file that has the right information in the right format.)

By default, Squish will only record actions on native controls—such as embedded ActiveX controls—if it can clearly identify the controls as such. However, with Java™, it's not possible for Squish to be certain whether something is a native control or a Java™ control. In view of this, it is necessary to tell Squish about the native controls being used, so that Squish can correctly record actions on them.

For example, to inform Squish that a control called MyCalendarCtrl is a native control, create a configuration file as described in Creating an INI file for Squish to recognize native Windows controls (Section 7.3.9.1) with the following contents:

[Windows Wrapper]
Whitelist="MyCalendarCtrl"

	Native Control Names
	If you don't know the native control's class name, you will need to ask the application's developers. Alternatively, you can use a tool like Spy++ (which is supplied with Microsoft Visual Studio) or AutoIt Window Info.

It is possible to have more than one class listed in the Squish whitelist—just separate them with commas, and always put each name in quotes. For example:

[Windows Wrapper]
Whitelist="MyCalendarCtrl","AnotherControl","InternetExplorerCtrl"

It is also possible to tell Squish to record events on native Windows programs which are launched by your application. To do this, you must tell Squish the window title bar caption used by the Windows application which is launched, so that Squish knows that it belongs to your main application. This is done by adding an Extra Windows entry to your .ini file, for example:

[Windows Wrapper]
Whitelist="MyCalendarCtrl","AnotherControl","InternetExplorerCtrl"
Extra Windows="Microsoft Word"

	Extra Windows
	The Extra Windows's values must be quoted and comma-separated. Either the exact window title must be specified, or wildcards must be used. (* matches any number of characters, ? matches any single character.)

Squish can be used to access all the properties exposed by ActiveX-based controls. This ActiveX functionality is also used to automate the controls supplied by various third-party vendors, such as Infragistics and Exontrol. This feature is disabled by default since it may incur a small runtime cost in performance and test stability, but it is easy to to activate it.

To activate the recognition of ActiveX controls—in fact, recognition of all COM controls—edit the .ini file described in Creating an INI file for Squish to recognize native Windows controls (Section 7.3.9.1) to add a COM Object Detection entry, and give this entry a value of 1 to turn it on.

[Windows Wrapper]
COM Object Detection=1

The winwrapper.ini's [Windows Wrapper] section supports a number of key=value pairs, as described below in alphabetical order.

The Blacklist key is used to identify window class names that the Windows wrapper should not attempt to record or playback. The matching is based on the class name, although wildcards (* to match zero or more of any characters) are also supported.

[Windows Wrapper]
Blacklist="#76423", "Outlook*"

The Blacklisted Objects key is used to identify objects that the Windows wrapper should not attempt to record or playback. Such objects are identified using Squish real (multi-property) names.

[Windows Wrapper]
Blacklisted Objects="{type='WindowsControl' text='OK'}", "{type='WindowsControl' text='Cancel'}"

	Not all object names can be used
	For performance reasons, only object names using type='WindowsControl' (or object names specifying no type at all, e.g. {class='QWidget' text='Hello'} can be used.

The Blacklisted Processes key is used to identify executables that the Windows wrapper should not attempt to record or playback. The matching is done on the filename of the executable (but case-insensitively).

[Windows Wrapper]
Blacklisted Processes="notepad.exe"

The COM Object Detection key is described above: Accessing the properties of ActiveX-based and COM controls (Section 7.3.9.3).

The Extra Windows key is used to make it possible for Squish to hook into additional arbitrary processes based on their window titles. The value may use simple glob-style wildcards (* for zero or more of any character, ? for any single character). For example, to match any OpenOffice window or the Calculator window we could use:

[Windows Wrapper]
Extra Windows="*OpenOffice*", "Calculator"

The Whitelist key is used to identify window class names that the Windows wrapper should record and playback. The matching is based on the class name, although wildcards (* to match zero or more of any characters) are also supported.

[Windows Wrapper]
Whitelist="#31482", "Notepad++"

The Whitelisted Objects key is used to identify objects that the Windows wrapper should record and playback. Such objects are identified using Squish real (multi-property) names.

[Windows Wrapper]
Whitelisted Objects="{type='WindowsControl' text='OK'}", "{type='WindowsControl' text='Cancel'}"

	Not all object names can be used
	For performance reasons, only object names using type='WindowsControl' (or object names specifying no type at all, e.g. {class='QWidget' text='Hello'} can be used.