Alex Ruiz's Blog

Lately, I noticed that one of the main topics in the FEST mailing list is violation of Swing’s threading policy in UI tests. Surprisingly, this subject is not really referenced directly. Most of the time, it appears in the form of questions, code snippets or test cases not related to Swing threading at all. It seems like we are still not fully aware of the event dispatch thread (EDT,) even though it has been around for many years (10+ maybe?)

In this blog entry, I’ll try my best to explain how to write EDT-safe UI tests. Some of the ideas are pretty general, and can be practiced even when not using FEST.

Brief explanation of Swing’s threading policy

Swing is a single threaded UI toolkit. Since it is not thread-safe, all Swing code must be executed in the EDT. As the official documentation states, invoking Swing code from multiple threads risks thread interference or memory consistency errors.

Swing’s threading policy basically states the following:

1. Swing components must be created in the EDT
2. Swing components must be accessed in the EDT, unless calling methods documented as “thread safe”

Pretty simple, eh? Unfortunately, it is too easy to break these rules. Swing does not provide any run-time checks for correct EDT usage and, most of the time, we can get away with an apparently “well behaved” Swing UI that breaks these rules.

As a side note, the 3rd-party Swing L&F, Substance, checks for violations of Swing threading rules at run-time, and it’s tastefully beautiful.

UI tests and the EDT

Writing EDT-safe UI tests is a little different than writing UI production code. The main difference is that calls in the EDT must always be synchronous. The thread running the test (either a TestNG or JUnit one) must wait for the code executed in the EDT to finish in order to continue its execution, to prevent unexpected results.

The following image illustrates how a test that involves verifying that the text of some JLabel changes when selecting a JCheckBox needs to be executed.

Tips for writing EDT-safe UI Tests with FEST

1. Use FEST’s FailOnThreadViolationRepaintManager to detect EDT-access violations
   FailOnThreadViolationRepaintManager, based on the work of Scott Delap and Alexander Potochkin, will make UI tests fail if there is any EDT-access violation in both UI tests and production code. The best place to use it is the “set up” method marked with the annotation @BeforeClass:

   @BeforeClass public void setUpOnce() {
      FailOnThreadViolationRepaintManager.install();
   }

   Alternatively, UI tests can subclass FEST’s FestSwingTestngTestCase or FestSwingJunitTestCase, which already install FailOnThreadViolationRepaintManager.

2. Use FEST’s GuiActionRunner to execute code in the EDT synchronously
   When writing FEST, we originally tried to use SwingUtilities‘ invokeAndWait to make calls in the EDT synchronously. Unfortunately, we ended up with too many OutOfMemoryErrors when running our UI tests. Instead we wrote our own GuiQuery and GuiTask.

   GuiQuery is useful when creating Swing components or reading properties from a Swing component. GuiTask is similar to GuiQuery, but its purpose is to perform some action (or task) in the EDT without returning any value.

   The following example shows how to use a GuiQuery to create a JLabel:

   JLabel myLabel = GuiActionRunner.execute(new GuiQuery<JLabel>() {
     public JLabel executeInEDT() {
       return new JLabel("A Test");
     }
   });

   The following example shows how to use a GuiTask to select a JCheckBox:

   // static import of GuiActionRunner.execute
   execute(new GuiTask() {
     public void executeInEDT() {
       myCheckBox.setSelected(true);
     }
   });

   The following example shows how to use a GuiQuery to read the text of a JLabel:

   String text = execute(new GuiQuery<String>() {
     public String executeInEDT() {
       return myLabel.getText();
     }
   });

   Both GuiTask and GuiQuery should be used when accessing Swing components directly from our tests.

3. Always call waitForIdle in FEST’s Robot after using GuiActionRunner

   The method waitForIdle will pause the test until all events have been processed in the EDT (step #3 in the figure above.)

4. To improve performance, consolidate as many method calls in GuiActionRunner as possible
   We have found that we can greatly improve performance in our UI tests by consolidating as many calls in the EDT as possible. For example, instead of

   String text = execute(new GuiQuery<String>() {
     public String executeInEDT() {
       return myLabel.getText();
     }
   });
   Dimension size = execute(new GuiQuery<Dimension>() {
     public Dimension executeInEDT() {
       return myLabel.getSize();
     }
   });

   we can consolidate both calls into a single trip to the EDT

   Pair<String, Dimension> textAndSize = execute(new GuiQuery<Pair<String, Dimension>>() {
     public Pair<String, Dimension> executeInEDT() {
       return new Pair<String, Dimension>(myLabel.getText(), myLabel.getSize());
     }
   });

   where Pair is a class in the package org.fest.swing.util.

5. Do not use FEST’s GuiActionRunner to call “thread safe” Swing methods

   For example, all the methods that add event listeners to Swing components are synchronized. There is not need to take care of threading in this case.

6. Do not use FEST’s GuiActionRunner to call FEST’s API
   All methods in FEST are already EDT-safe.

Comments/suggestions are always welcome :)

Enjoy!