SWT instrumentation

Some special setup is required for testing SWT based applications with QF-Test/swt. Because SWT was not written with testability in mind, applications need to be run with a few slightly modified SWT classes in which we have added the necessary hooks for event filtering and component tracking to enable testing. The changes are transparent so that the behavior of an application is not changed, regardless of whether it is run inside or outside of QF-Test.

4.5+ If the SUT is run with the QF-Test agent and the option Connect without SWT instrumentation enabled, the required classes are exchanged by the agent during startup of the SUT. This works for all SWT versions on Windows and for SWT 4.8 and higher on Linux. Older versions on Linux still need to be instrumented as described below. It is generally a good idea to include a call to the SWT instrumentation procedure into your startup sequence with the parameter forceInstrumentation set to false. That way QF-Test can determine dynamically based on options settings and SWT version, whether instrumentation is required or the agent can do its job.

If you use QF-Test's Quickstart Wizard to create the setup sequence for your SUT (see chapter 3), it will take care of SWT instrumentation as well. For those with an aversion to wizard dialogs, the manual way is described next.

The standard library qfs.qft, which is part of the QF-Test distribution and described in detail in the tutorial, contains a 'Procedure' with which to perform the SWT instrumentation. It is named setup and located in the 'Package'qfs.swt.instrument. Insert a 'Procedure call' node before the start node for your SUT in your setup sequence. Set its 'Procedure name' attribute to qfs.qft#qfs.swt.instrument.setup and in the 'Variable definitions' set the parameter sutdir to the installation directory of your application. The plugin parameter can be left empty except when you are testing an Eclipse/RCP application that does not follow the standard plugin directory layout. In that case you can specify the plugin file to instrument directly via the plugin parameter. That's all. In case you want to know what goes on behind the scenes, all manual steps are described further on in this section.

Preparation for manual SWT instrumentation

Supported architectures for SWT testing are 32 and 64 bit Windows and 32 and 64 bit Linux with Gtk. The instrumentation files are provided in directories called .../qftest-7.1.5/swt/$ARCH/$VERSION where $ARCH is either win32, win32-64, linux-gtk or linux-gtk-64 and $VERSION is one of the supported SWT versions.

First you need to determine whether your application is a standalone SWT application or is based on eclipse. To do so, simply take a look at the directory structure of your application. If you find a directory called plugins containing a file called org.eclipse.swt.win32.win32.x86_X.Y.Z.jar (on Windows) or org.eclipse.swt.gtk.linux.x86_X.Y.Z.jar (on Linux), with X.Y.Z representing a version number like 3.2.0, your application is based on eclipse. For a standalone SWT application you should find a file called swt.jar, typically inside a directory called lib.

Manual SWT instrumentation for eclipse based applications

Simply replace the SWT plugin jar with one instrumented by QF-Test. To create the instrumented plugin you must run the 'Procedure' qfs.qft#qfs.swt.instrument.setup described above once with your original plugin (or a copy thereof) specified in the plugin parameter. QF-Test will create a backup copy of the original jar named _org.eclipse.swt....jar.orig. Next copy the instrumented plugin to the plugin directory of your application.

Finally, start your application once from the command line with the -clean command line argument to have it rebuild its plugin cache, e.g.

eclipse -clean

Your application's binary name may be different from eclipse, but all eclipse based applications should support the -clean argument.

Manual instrumentation for standalone SWT applications

For standalone SWT applications, replace the swt.jar file with the one provided with QF-Test. You may want to create a backup of the original first.

NoteIf you are launching the client application by means of a 'Start Java SUT client' node, you can set the classpath to point to the corresponding .../qftest-7.1.5/swt/$ARCH/$VERSION/swt.jar archive and leave your original file untouched.