Running UI Tests While Debugging Your Application in Eclipse

Motivation

You and your team are developing a Java application using Eclipse. You have a Continuous Integration (CI) process set up which builds your application and runs your battery of Squish tests after each code change.

So far so good. Now, after your latest changes to your application, the automated Squish tests start failing on one or more verifications. So you try to fix the application, push the fix and let your CI system re-run the Squish tests.

That's fine, but wouldn't it be nice if you could run the failing tests right on the application as you fix it, that is, while it is running and being debugged in Eclipse?

You can.

Solution

Because Eclipse has control over starting the application, Squish cannot start the Application Under Test (AUT) itself. Instead, the AUT needs to be made "attachable", so Squish (a local Squish install is assumed) can interact with it. In general, this can be achieved using the startjavaaut utility shipped with Squish. The approach of how to let Eclipse invoke startjavaaut is described in a Knowledge Base article. It has its limitations though, so we take a slightly different route.

Implementation, part I

First, we need to set some environment variables before starting Eclipse. For this, we use a short shell script. It prepares the environment and starts Eclipse afterwards. Most variables are specific to Squish. The last one is later used inside Eclipse:

Linux/eclipse_java_attachable.sh

#!/bin/sh

# Change this as needed

export SQUISH_PREFIX=/opt/squish-for-java-6.6.2
# Maybe configure this, should be a good default though

export SQUISH_ATTACHABLE_PORT=4444
# Do not change these

export TRACELIB_NO_SIGNALHANDLERS=1

export SQUISH_NO_CRASHHANDLER=1

export SQUISH_JAVA_OPTIONS='"-Dsquish.wrapper=${env_var:SQUISH_PREFIX}/lib/libsquishjavawrapper.so" "-javaagent:${env_var:SQUISH_PREFIX}/lib/squishagent.jar=${env_var:SQUISH_PREFIX}/lib" "-Xverify:none" "-Dsquish.tmpdir=/tmp/frogtemp" "-Dsquish.bcel=${env_var:SQUISH_PREFIX}/lib/bcel.jar" "-Djava.security.policy=file:/tmp/frogtemp/squish.policy"'
# Change this as needed

/opt/eclipse/eclipse

• SQUISH_PREFIX should point to the Squish installation.
• SQUISH_ATTACHABLE_PORT can be adjusted if required (needs to be between 1024 and 65535).

Windows/eclipse\_java\_attachable.bat

A batch file to achieve the same Eclipse would look like this:

bat

:: Change this as needed:

set SQUISH_PREFIX=C:\users\myuser\squish-for-java-6.6.2
:: Maybe configure this, should be a good default though:

set SQUISH_ATTACHABLE_PORT=4444
:: Do not change these:

set TRACELIB_NO_SIGNALHANDLERS=1

set SQUISH_NO_CRASHHANDLER=1

set PATH=%PATH%;%SQUISH_PREFIX%\bin

set SQUISH_JAVA_OPTIONS='"-Dsquish.wrapper=${env_var:SQUISH_PREFIX}/lib/libsquishjavawrapper.so" "-javaagent:${env_var:SQUISH_PREFIX}/lib/squishagent.jar=${env_var:SQUISH_PREFIX}/lib" "-Xverify:none" "-Dsquish.tmpdir=/tmp/frogtemp" "-Dsquish.bcel=${env_var:SQUISH_PREFIX}/lib/bcel.jar" "-Djava.security.policy=file:/tmp/frogtemp/squish.policy"'
:: Change this as needed:

C:\Users\myuser\Eclipse\eclipse.exe

Implementation, part II

With Eclipse started using the above shell script, we now have to adjust the Run/Debug Configuration. For this, open the Debug Configuration Dialog (Run -> Debug Configurations) and choose the Configuration that the AUT uses. In the 'Environment' tab we have to define the _JAVA_OPTIONS variable, which the Java VM picks up, upon AUT startup. Choose the 'Add' button next to the list of environment variables. The name should be _JAVA_OPTIONS and the value needs to be set to ${env_var:SQUISH_JAVA_OPTIONS}. Close the dialog with 'OK'. The variable should then show up in the list.

After applying the changes, run the AUT using this Configuration. The AUT should show up and be ready to be connected to with Squish.

In the Squish IDE, we have to configure the "attachable AUT". To do this, we navigate to Edit -> Server Settings… In the dialog, select 'Manage AUTs' in the left pane. In the right pane, select 'Attachable AUTs' and click 'Add…'. The name can be chosen freely, the host should already be set to 'localhost'. The port number needs to match the port number that SQUISH_ATTACHABLE_PORT in the shell script points to.

After closing the dialog, use 'Run' > 'Launch AUT'. The list of AUTs lists the new entry now. Select it, and close with 'OK'. Squish connects to the already started AUT now.

In test scripts you would use the attachToApplication() function to attach to the running AUT.

Limitations

The described approach only works with Java 9 and upward. Note: new Java releases might include technical changes that require adjustments to the outlined approach.

An alternative approach described in our Knowledge Base would touch the Java installation, which might not be feasible in a lot of cases. Since it uses the startjavaaut utility, the only requirement for new Java versions (if at all) would be to update Squish.

Wrap up

With either solution, in the end, we are able to run Squish tests and inspect the AUT, while developing and debugging it with Eclipse. We can even make use of Eclipse's 'Hot deploy' feature.