19.8. Attaching to Running Applications

19.8.1. Overview
19.8.2. Start the AUT
19.8.3. Register the AUT
19.8.4. Attaching from a Script

19.8.1. Overview

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.

19.8.2. Start the AUT

In order for Squish to be able to connect to the AUT, you must start the AUT using Squish's start*aut (Section 19.4.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 start*aut (Section 19.4.6).

Example:

startaut --port=9999 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.

19.8.3. Register the AUT

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 File|Server Settings|Manage AUTs... to pop up the Manage AUTs dialog (Section 20.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 start*aut (Section 19.4.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.

19.8.4. Attaching from a Script

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 start*aut (Section 19.4.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 18.3.11)).

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.

Python
def main():
    attachToApplication("attachableAddressbook")
    snooze(1.0)
JavaScript
function main()
{
    attachToApplication("attachableAddressbook");
    snooze(1.0);
}
Perl
sub main
{
    attachToApplication("attachableAddressbook");
    snooze(1.0);
}
Ruby
# encoding: UTF-8
require 'squish'
include Squish

def main
    attachToApplication("attachableAddressbook")
    snooze(1.0)
end
Tcl
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 17.21.2)).

By default Squish allows the AUT up to 20 seconds from Squish's initial connection to the AUT's first response. This can be changed; see Squish Server Settings dialog (Section 20.3.16). However, in some circumstances you might want to allow more that one attempt to attach to the AUT. Here is how three attempts can be tried:

Python
def main():
    attached = False
    for i in range(3):
        try:
            attachToApplication("attachableAddressbook")
            test.log("Attaching succeeded")
            attached = True
            break
        except:
            test.warning("Attaching failed, retrying...")
            snooze(1)
    if not attached:
        test.fail("Couldn't attach")
        return
    # ...
JavaScript
function main()
{
    var attached = false;
    for (var i = 0; i < 3; ++i) {
        try {
            attachToApplication("attachableAddressbook");
            test.log("Attaching succeeded")
            attached = true;
            break;
        } catch {
            test.warning("Attaching failed, retrying...");
            snooze(1);
        }
    }
    if (!attached) {
        test.fail("Couldn't attach");
        return;
    }
    // ...
}
Perl
sub main
{
    my $attached = 0;
    for (my $i = 0; $i < 3; ++$i) {
        eval {
            attachToApplication("attachableAddressbook");
            test::log("Attaching succeeded")
            $attached = 1;
            last;
        };
        if ($@) {
            test::warning("Attaching failed, retrying...")
            snooze(1)
        }
    }
    if (!$attached) {
        test::fail("Couldn't attach");
        return;
    }
    # ...
}
Ruby
# encoding: UTF-8
require 'squish'
include Squish

def main
    attached = false
    for i in 0...3
        begin
            attachToApplication("attachableAddressbook")
            Test.log("Attaching succeeded")
            attached = true
            break
        rescue
            Test.warning("Attaching failed, retrying...")
            snooze(1)
        end
    end
    if !attached
        Test.fail("Couldn't attach")
        return
    end
    # ...
end
Tcl
proc main {} {
    set attached false
    for {set i 0} {$i < 3} {incr i} {
        if {[catch { attachToApplication "attachableAddressbook" }]} {
            test warning "Attaching failed, retrying..."
            snooze 1
        } else {
            test log "Attaching succeeded"
            set attached true
            break
        }
    }
    if {!$attached} {
        test fail "Couldn't attach"
        return
    }
    # ...
}

Here we make three attempts to attach to the AUT. If an attempt succeeds we break out of the loop and any following Squish commands can then be executed. Otherwise, we note the failure, give the AUT an extra second to wake up (in addition to the 20 seconds that the attachToApplication function allows), and try again—or give up if we've already tried three times.