Squish's default behavior is to automatically start the application you want to test, and to terminate the application once the test case is finished. But it is also possible to test an already running application by attaching to it. One important difference when attaching is that at the end of the test case Squish does not terminate the application it attached to.

One benefit of attaching is that it allows you to test your application with the squishserver running on another machine. However, the attaching approach also suffers from an important limitation: you can have only one squishserver attached to your application at a time.

Using the attaching approach is a three step process: first start the AUT; second, register the AUT; and finally, attach to the AUT from a script. We'll now discuss each of these steps in turn.

In order for Squish to be able to connect to the AUT, you must start the AUT using Squish's startaut (Section 16.5.6) command line tool.

Usage:

startaut --port=port aut [aut-command-line-options]

You must specify a network port number as the argument to the --port option. The AUT listens on this port number for a connection from the squishserver.

It is important that the --port option is given before the AUT because any aut-command-line-options options specified after the AUT are passed as options to the AUT and are not used by startaut (Section 16.5.6).

Example:

startaut --port=5900 addressbook

Once the AUT is running we are ready to connect to it. But first we must register the attachable AUT in order to be able to access it from test scripts.

Just the same as with AUTs that are started and terminated by Squish, AUTs that are attached to must be registered. This is easily done using the Squish IDE. For Squish 4, click Squish+Manage AUTs... to pop up the "Manage AUTs" dialog (Section 17.3.4). For Squish 3, click Edit+Preferences to pop up the Preferences dialog, then click the Server Settings tab. Select the Attachable AUTs entry (which might be near the bottom of the tree view), and press the Add... button. This will pop up the Add Attachable AUT dialog. Use this dialog to enter the name of the AUT you want to be able to attach to—the name is just an acronym to stand for the AUT and for use in test scripts. Also, you must set the port number to the same one that you used when starting the AUT with startaut (Section 16.5.6). In addition, you can specify the hostname—this is necessary only if you want to run the AUT on a different machine from the one that runs the squishserver.

squishserver --config  addAttachableAUT addressbook 5900

First you must tell Squish not to automatically start the AUT you wish to attach to when a test case is run. For Squish 4, click the Suite Settings item in the project tree, and in the Application Under Test (AUT) section, change the Application combobox's item to the <No Application> item. For Squish 3, click Test Suite+Settings to pop up the Test Suite Settings dialog, and on the General tab, change the Application combobox's item to the <No Application> item.

Now Squish will not start up the AUT for test cases in this test suite. We have already seen earlier how to start the AUT using the startaut (Section 16.5.6) application. But to be able to connect to the application and interact with it our test script must attach to it. This is done by putting a call to the attachToApplication function in the test script, and passing it the arguments it needs to attach to the AUT. In fact, the only mandatory argument is the name we gave the AUT when we registered it.

Just as we use the attachToApplication function to attach to a running application, similarly we can use the startApplication function to start an application. And both these functions return an application context object (see Application Context (Section 16.1.3.10)).

It is possible to record a test script if you are attached to an AUT. But since Squish did not start the AUT, it isn't possible to simply click the Record toolbar button. Instead you must write a tiny test script that just has a simple main function and a call to the attachToApplication function.

def main:
    attachToApplication("attachableAddressbook")
    snooze(1.0)

function main()
{
    attachToApplication("attachableAddressbook");
    snooze(1.0);
}

sub main
{
    attachToApplication("attachableAddressbook");
    snooze(1.0);
}

proc main {} {
    attachToApplication "attachableAddressbook"
    snooze 1.0
}

Now place a breakpoint on the line with the snooze function. If you now play back the test script, Squish will attach to the AUT and start executing the test script. But as soon as Squish reaches the call to the snooze function it pauses execution thanks to the breakpoint. Now you can choose Record to extend the test script by recording whatever actions you like. When you are finished, simply press the Stop Recording toolbar button in Squish's control bar and the new test script will become visible in Squish's editor. (see How to Record After a Breakpoint (Section 15.2.2)).