Window Tester Documentation : WindowTester FAQ- Instantiations Inc.

WindowTester General FAQ

If you have questions you believe should go in here, please let us know by emailing windowtester support.

Answers to FAQ

General

Where can I find documentation?
The latest version of this FAQ, the WindowTester overview, tutorial and javadocs can be found in the Eclipse help system and online.

What Operating Systems does WindowTester support?
WindowTester currently runs on Windows and Linux-GTK. It has some preliminary Mac support. We suggest giving it a try on the Mac and if you run into problems let us know and we'll try to work with you to get things working.

I'm getting errors trying to generate tests, what should I do?
If WindowTester fails to work properly (indicated by throwing a random exception), it is more likely an installation problem. Try the following:

Clean your Eclipse "configuration" directory (found in your eclipse home directory). If you are installing into Eclipse 3.2 or 3.3, delete the "org.eclipse.*" subdirectories in the "configuration" directory (they are recreated at startup). Make sure that you do not delete the config.ini file. Restart Eclipse with the -clean option.
Check that only one version of WindowTester (one set of *com.windowtester.* plugins and features) is installed. If you have an older version also installed (indicated by an earlier version number), delete those plugins and features and repeat step number one above. Make sure that you don't have WindowTester installed both locally within your Eclipse /plugins directory and remotely through a .link file (check your Eclipse /links directory).
Check your project for classpath problems and your code for compilation problems.
Try refreshing and rebuilding your project using the Project > Clean command.
If the problem persists, check your Eclipse ".log" file (found in your <workspace>\.metadata directory) for any recorded exceptions.
If Eclipse locks up repeatedly, you might try running Eclipse with the -debug command line option. You can then press Ctrl+Break in the console to look at the thread dump which may show where the system is locking up. Send that thread dump to us.
If you're still having problems after checking all of the above, send an email to support. Please describe what you were doing when the exception occurred. Also please provide the Eclipse .log file, a test case and/or screen shots as appropriate.

I'm Getting an IllegalStateException Saying my License is not Active, what should I do?
You either did not activate WindowTester or your license expired. To activate WindowTester, use the "Registration and Activation" button in the WindowTester Preference page (Window>Preferences>WindowTester). See the Activation section.

Are there code samples?
The javadocs contain various code snippets and examples. There are also a number of examples posted on the support forum. Finally, we have a few samples in a project here.

I'm using GEF/Draw2D; help!
WindowTester now has basic GEF recording and playback support. This functionality is continuously evolving. Please send us feedback!

What versions of GEF does WindowTester Support?
WindowTester requires GEF version 3.2.100 or more recent.

What about Swing? JGo?
Swing is now fully supported in the WindowTesterPro product. We are researching JGo support for a future release.

How can I get more help?
Start with the the various Getting Started examples. You might also read through the various topics in our support forum. If you still have questions, email us or post a question to our support forum.

What information should I send when contacting support?

Development environment information such as: Hardware Architecture, OS version, Eclipse version, JDK version, WindowTester Build#.
Eclipse .log file located in your <workspace>\.metadata directory.
Additional log for SWT applications under test:
Example location: C:\Eclipse\workspace\.metadata\.plugins\com.windowtester.eclipse.ui\swt-launch-workspace\.metadata
WindowTester screen shots associated with the failing test located in your project's \wintest directory:
If it is an error in test playback, please enable tracing, run your test to generate the runtime log output and send the runtime .log file located usually in your Eclipse installation directory. You can check the location of the log file from your launch configuration's Main tab (Ex:${workspace_loc}/../runtime-contactmanager.product/.metadata). For instructions on how to enable tracing, see How do I enable tracing?.
It would be very helpful if you could send a test case for us to use to re-produce the problem.

Is there a way to generate reports after the tests are run?

If you run your tests using Ant you can generate such a report using the JUnit task. Try our sample Ant scripts.

See this article for more information: http://junit.sourceforge.net/doc/faq/faq.htm#running_6

How do I use Ant to create HTML test reports?

(Submitted by: Eric Armstrong and Steffen Gemkow)

Ensure that Ant's optional.jar file is either in your CLASSPATH or exists in your $ANT_HOME/lib directory.
Add an ANT property for the directory containing the HTML reports:

<property name="test.reports" value="./reports" />

Define the Ant task for running JUnit and generating reports:

<target name="test-html">
  <junit fork="yes" printsummary="no" haltonfailure="no">
    <batchtest fork="yes" todir="${test.reports}" >
      <fileset dir="${classes}">
        <include name="**/*Test.class" />
      </fileset>
    </batchtest>
    <formatter type="xml" />
    <classpath refid="test.classpath" />
  </junit>

  <junitreport todir="${test.reports}">
    <fileset dir="${test.reports}">
      <include name="TEST-*.xml" />
    </fileset>
    <report todir="${test.reports}" />
  </junitreport>
</target>

Run the test:

ant test-html

Refer to the JUnit Ant Task for more information. For a working sample, see our Ant example.

Does WindowTester Pro support testing with Non US Keyboards?

Yes. See the International Keyboard Support section of the docs.

How do I determine if the Welcome screen is open so I can close it?

Sometimes when I record I don't get the Welcome screen but when I run my tests the welcome screen is open which causes my tests to fail. How do I determine if the Welcome screen is open so I can close it?

To address this issue in our tests, we use this common setUp() method:

	protected void setUp() throws Exception {
		closeWelcomePageIfNecessary();
	}

	protected void closeWelcomePageIfNecessary() throws WidgetSearchException {
		IWidgetLocator[] welcomeTab = getUI().findAll(new CTabItemLocator("Welcome"));
		if (welcomeTab.length == 0)
			return;
		// TODO: compute x based on tab width to avoid font dependencies
		int x = 78;
		getUI().click(new XYLocator(welcomeTab[0], x, 12));
	}

How do I print the Component hierarchy to the console?

WindowTester has a function that you could call during a test and it will dump the hierarchy to the console.
new com.windowtester.swt.util.DebugHelper().printWidgets();

How do I test a deployed RCP application?

See the tutorial on Testing deployed RCP application.

Does WindowTester support JUnit4 tests?

JUnit4 Support is being actively researched. The current show-stopper is due to a bug in the Eclipse Test Framework. If this feature is valuable to you, consider voting for the bug.

I uninstalled/upgraded/deleted/moved a previous installation and now I can't see the recorder control and there is no WindowTester Preference(Eclipse 3.4 only). What happened?

See the Eclipse 3.4 cache problem workaround.

Recording

What is the minimal set of plugins required in the recording launch configuration?
The recording launch configuration requires the following plugins:

com.instantiations.common.core
com.instantiations.common.ui
com.instantiations.eclipse.debug
com.instantiations.eclipse.util
com.windowtester.runtime
com.windowtester.swing.runtime
com.windowtester.swt.recorder
com.windowtester.swing.recorder
com.windowtester.swt.runtime
com.windowtester.swt.platform.ext

The rest can safely be excluded (unless they are required by the application under test).

What should I do if the recorder control does not appear?
Open your recording configuration and on the Plug-ins tab, include the minimal set of plug-ins required and click on the Add Required Plug-ins button:

The recorder is not finding a widget and I'd like to hand-code a WidgetLocator; any pointers?

If the source of the component in question is under your control, your best bet is to name the widget. Alternatively, see this entry on writing widget entries by hand.

Does WindowTester support native dialogs like File Open, File Save, etc.?

Not at the moment. You can try workarounds like entering the complete path name instead of using the Browse button.

What types of widgets are currently not supported by the WindowTester Recorder?

We're in the process of making a number of fixes in this area. As it stands, known recorder limitations include:

Custom widget subclasses are also not fully supported (http://www.instantiations.com/forum/viewtopic.php?t=1330).

What should I do if ui.close() is causing TimeOutException?

The close call essentially calls close() on the underlying shell. In this case, it does not seem to be the right thing to do. In fact, in general, we discourage calling close() unless absolutely necessary. (Note that you also generally don't need to explicitly call the exit menu action either as the PDE test runner closes the workspace for you already.) To avoid recording the close action, you might click the pause button on the recorder controller before exiting the application under test. In case you do record it, you can safely remove the calls from the generated class.

See this forum entry: http://www.instantiations.com/forum/viewtopic.php?t=904

Why are keystrokes like Ctrl+A and Ctrl+S not being recorded?

Keystrokes (such as Ctrl+S) are captured and consumed by a global key event handler to which there is no easy access. As a result these events go unrecognized by the recorder. See "How can I simulate keyboard events" for examples on how keystrokes can be manually added to the test script.

Why is the recorder not visible when I try to record?

1. If you're recording a plug-in or RCP application, in your record launch configuration's Plug-ins tab, make sure to select "Launch with all workspace and enabled external/target plug-ins."

2. If your RCP application has external dependencies like dlls and/or other libraries, in your record launch configuration's Arguments tab, make sure the Working directory is the same as the RCP application launch configuration's Working directory.

3. If you change the target platform, see this FAQ entry.

Why is the recorder not visible and playback of generated JUnit test code fails when the target platform is changed?

The reason the WT plugins are not loaded in the target platform( even if WindowTester has been installed in the target platform eclipse installation) is because WT is loaded using link files. WT is usually installed in the default directory \Program Files\Instantiations and then .link files are created in the eclipse installation directory to point to the WT plugins. This scheme does not work when the eclipse installation is pointed to as a target platform.

Here's what you need to do to be able to set the Target Platform to a different installation of eclipse.

Get the WindowTester installation zip file for your eclipse version and unzip into the Target platform eclipse installation. This should take care of things and load the WindowTester plugins.

Drag and Drop from a Viewer onto a Canvas misses the Selection (DragSource). What can I do?

Native drag and drop is tricky and the recorder is at times a bit finnicky. To ensure that the start of your drag is properly noticed, explicitly click the drag source item (mouse up and down) before beginning the drag.

Runtime/Playback

How do I enable tracing?
To enable tracing, open your launch configuration, switch to the Tracing tab, check Enable tracing for the selected plug-ins; click the Select All button and click Apply.

I'm getting a MultipleWidgetsFoundException when I wasn't before, what gives?
This happens in cases where the widget hierarchy is different at the time of playback than it was at recording. This presents a problem because the information that the recorder used to disambiguate the widget at recording-time is no longer sufficient to uniquely identify the widget. To remedy this, you have several alternatives. You can:

Re-record the snippet of the test in question.
Write a more descriptive locator by hand (see: this entry for more).
If the source for the widget in question is your own, you can name the widget. This name will be used in widget identification. For more on naming, see this entry.

How do I name a widget?
Widgets can be named using the setData(key,value) method on widgets. That is, if a widget has been named like this:

 widget.setData("name", "named.button");

in a test case, the following will work:

 Widget found = ((WidgetReference)ui.find(new NamedWidgetLocator("named.widget")).getWidget();
 //In the old API: Widget found = ui.find("named.button");
 assertEquals(widget, found);

Naming widgets is the most robust way to identify widgets at runtime.

I'd like to test the state of a widget in my test but I keep getting an SWTException (Invalid thread access). Help!
As described in the Assertions section, you're seeing this exception because many of the methods on org.eclipse.swt.Widget and its subclasses require that they be called from the UI thread. WindowTester tests, however, are run in a non-UI thread. To remedy this, you can wrap your calls in a runnable and pass it to the display to be executed by the UI. See the Assertions section for more details.

How can I simulate keyboard events like "Ctrl+A" and "Backspace"?
You can do this by sending key events directly in your test case.

For example:

 IUIContext ui = ...;
 ui.keyClick(SWT.CTRL, 'a'); //send ctrl-a  
 ui.keyClick(SWT.BS);        //send backspace

Screenshots are captured on test failures? Where are they?
Screenshots are emitted to a "wintest/" subdirectory of the working eclipse base directory. For instance, if your eclipse is located C:\dev\eclipse\3.1.1\eclipse, screenshots would appear in C:\dev\eclipse\3.1.1\eclipse\wintest.

Screenshots? How can I take my own?
You can capture a new Screenshot at any time during a test using the ScreenCapture utility class.

Every once in a while an unexpected dialog pops up and breaks my test. What can I do?
Create shell condition and handler for the dialog and register it with the shell monitor. See this tip for more.

What are Conditions and how do I use them?
See the Conditions section for more details.

When are Conditions Processed?
See the Conditions section for more details.

What are WidgetLocators?
Widget locator are abstractions used to identify widgets at runtime.

What is a ShellMonitor and how do I use it?
See the Conditions section for more details.

I want to write my own WidgetLocator by hand. How do I do it?
The trick is to understand the way widget search is performed. See this entry on searching for more on that.

How does the widget finding algorithm work?
The widget finder searches the current active window for matches. Locators might match mutiple widgets (whether this case is exceptional depends on whether you use IUIContext.find(..) or IUIContext.findAll(..)). As a simple example, new ButtonLocator("OK") identifies a Button labeled "OK" in the current active window. If there is more than one such button in the active window, you can disambiguate the search by embellishing the locator with information about the Button's location in the widget containment hierarchy. For instance, if the "OK" button of interest is the child of a Composite (and none other is), new ButtonLocator("OK", new SWTWidgetLocator(Composite.class)) will uniquely identify it. Whereever possible, you should name widgets that require disambiguation. See .... for more on this. For more on matching by containment look at the SWTWidgetLocator javadocs.

What is a WidgetNotFoundException?
WidgetNotFoundExceptions are thrown when a search is performed for a widget that cannot be found in the application under test. Note that only visible widgets can be found.

How do I slow down playback?

If you would like to slow down the playback, choose the menu item Window > Preferences and do the following:

on the left tree view, expand the WindowTester and select Playback
on the right, check Delay and Highlighting
click the Apply button
click OK to close the dialog

The next time you play back a test, the play back should go a lot slower.

How do I find a widget using regular expression?

WindowTester supports wild cards based on the regular experssion support provided by Java. For more on String comparison, see the StringComparator javadoc.

For an example of how this looks in the wild here is a snippet from one of our helper tests:

  //linux safe  
  ui.click(new MenuItemLocator("&New\t(Shift\\+Alt|Alt\\+Shift)\\+N/P&roject...");
  ui.wait(new ShellShowingCondition("New Project"));
  ui.click(new TreeItemLocator("(Simple|General)/Project")); //3.* safe path

We aren't using a clean workspace for our test runs. How do you do that?
Go to the test's launch configuration (Run>Run...) and in the Main tab for your test, select "Clear workspace data before launching".

My test passes but I see an error in the console (Exception in thread "WorkbenchTestable" java.lang.NullPointerException), is this a problem?
This exception appears to be caused in cases where the workspace is being shut down by test code (e.g., by selecting the Exit menu item or closing the main Shell) at the same time as the PDE test runner is itself also closing down the application. Note that you do not need to explicitly exit the application at the end of your tests since that will be done for you by the test runner. If this describes your case, remove the explicit calls to exit the application and you should be OK. If it doesn't tell us more!

Can WindowTester tests be run from the command line?
The short answer is yes, since WindowTester tests are just JUnit plugin tests, they can be run the same way that eclipse plug-in tests are run using the Eclipse Testing Framework. To get started with the Eclipse Testing Framework, see this article. We've put together a script and a sample project that can be used as a jumping off point that can be found here.

What should I do if I encounter an UnsatisfiedLinkError when trying to playback my tests?

The Eclipse SWT DLL (which can be found in the $ECLIPSE$\plugins\org.eclipse.swt.win32_x.x.x\os\win32\x86\ directory or in the org.eclipse.swt.win32.win32.x86_3.x.x.jar file) needs to be on your path. Placing it into your windows/system32 directory is the easiest thing to do.

For Linux, you need to locate the corresponding Eclipse SWT *.so files contained in the SWT GTK plugin.

Does WindowTester support closing and re-starting applications?

Currently no. If you need to run multiple tests, you need to keep your application running.

Why does my test stop playing after it opens the "Confirm Exit" dialog?

When you close Eclipse using the X button after a recording session, you get the confirm exit dialog. WindowTester records these events but when you play it back it opens the dialog but does not recognize the pressing of the OK button. The script generated looks something like this:

ui.wait(new ShellShowingCondition("Confirm Exit"));
ui.click(new ButtonLocator("OK"));
ui.wait(new ShellDisposedCondition("Confirm Exit"));
ui.wait(new ShellDisposedCondition("Eclipse SDK"));

The eclipse testing framework tears down the application (eclipse) when the tests are done running. This means that the attempt to close the app in the test is not succeeding. And so, the shell you are waiting for is never showing up.

Sadly, this is just a fact of life.

You can either remove these lines from the test or not record them at all by clicking on the pause button in the recorder before exiting.

Why is my working directory different when I run my tests?

Normally, when you launch your application, Eclipse sets the working directory to the directory containing the application (typically the "eclipse" directory itself). When you launch a JUnit Plugin Test, Eclipse sets the working directory to the project containing the test being executed. This is default Eclipse behavior. If you want to change the working directory when launching your JUnit Plugin Test, open your test launch configuration. Switch to the Arguments tab, under the Working directory section, select Other and enter the directory you want.

Why is my test throwing WidgetNotFoundException when a nested dialog is closed?

When a button is clicked within the first dialog it opens another dialog. After closing the second dialog, the test stops and throws a WidgetNotFoundException. This happens because the first dialog does not get the focus back. Make sure when the second dialog is closed the focus goes back to the first dialog.

How do I delete the contents of a Text widget?

You can simulate a Shift+click+Delete key like so...

ui.click(2, new LabeledTextLocator("textLabel"), WT.SHIFT);
ui.keyClick(WT.DEL);

How do I make menu selections generic across different versions of Eclipse?

Some menu items across different versions of Eclipse are slightly different e.g. Window > Preferences... in 3.3 vs Window > Preferences (without the dots) in 3.4. If you want to be able to run your tests in 3.3 and 3.4 you need to modify your test script like so...

ui.click(new MenuItemLocator("Window/&Preferences(...)?"));