Getting Started

FEST (Fixtures for Easy Software Testing) is an open source project (Apache 2.0 license) that aims at making software testing simpler. This guide explains how to get started with FEST's Swing module, which makes creation and maintenance of robust GUI functional tests easy.

Before you start

Before starting to write any test, please do the following:

1. Download the latest version of the Swing module from the project's download page. The filename should be similar to fest-swing-{VERSION}.zip, where {VERSION} is the latest version of the module.
2. Include the file fest-swing-{VERSION}.jar and its dependencies (jar/zip files, located in the 'lib' folder in the downloaded zip file) in your classpath.

Writing your first GUI test

When writing GUI tests, please use the fixtures in the package org.fest.swing.fixture. These fixtures provide specific methods to simulate user interaction with a GUI component and also provide assertion methods that verify the state of such GUI component. Although you could work with the FEST Robot (org.fest.swing.core.Robot) directly, the Robot is too low-level and requires considerably more code than the fixtures.

There is one fixture per Swing component. Each fixture has the same name as the Swing component they can handle ending with "Fixture." For example, a JButtonFixture knows how to simulate user interaction and verify state of a JButton.

For our first test, let's assume we have a very simple JFrame that contains a JTextField, a JLabel and a JButton. The expected behavior of this GUI is: when user clicks on the JButton, the text of the JTextField should be copied to the JLabel.

The following sections describe the steps necessary to test our GUI.

1. Create a fixture for a Frame or Dialog

Create a fixture to handle either a Frame or a Dialog (depending on the GUI to test) in the "setUp" method of your test. The "setUp" method is the method that initializes the test fixture before running each test method:

• setUp method (JUnit 3.8.x)
• any method marked with @Before (JUnit 4.x)
• any method marked with @BeforeMethod (TestNG)

Example:

  private FrameFixure window;

  @BeforeMethod public void setUp() {
    window = new FrameFixture(new MyFrame());
    window.show(); // shows the frame to test
  }

2. Clean up resources used by FEST-Swing

FEST-Swing forces sequential test execution, regardless of the testing framework (JUnit or TestNG.) To do so, it uses a semaphore to give access to the keyboard and mouse to a single test. Clean up resources after running each test method to releases the lock on such semaphore. To clean up resources simply call the method cleanUp in the FEST-Swing fixture inside:

• tearDown method (JUnit 3.8.x)
• any method marked with @After (JUnit 4.x)
• any method marked with @AfterMethod (TestNG)

Example:

  @AfterMethod public void tearDown() {
    window.cleanUp();
  }

3. Write methods to test the GUI behavior

Start using the FEST-Swing fixture to test your GUI. FEST-Swing fixtures simulate a user interacting with a GUI in order to verify that such GUI behaves as we expect. For our example, we need to verify that the text in the JTextField is copied to the JLabel when the JButton is clicked:

  @Test public void shouldCopyTextInLabelWhenClickingButton() {
    window.textBox("textToCopy").enterText("Some random text");
    window.button("copyButton").click();
    window.label("copiedText").requireText("Some random text");
  }

Putting everything together

The following code listing shows the whole test that verifies the described GUI is behaving correctly:

  import org.testng.annotations.*;
  import org.fest.swing.fixture.FrameFixture;

  public class FirstGUITest {

    private FrameFixure window;

    @BeforeMethod public void setUp() {
      window = new FrameFixture(new MyFrame());
      window.show(); // shows the frame to test
    }

    @AfterMethod public void tearDown() {
      window.cleanUp();
    }

    @Test public void shouldCopyTextInLabelWhenClickingButton() {
      window.textBox("textToCopy").enterText("Some random text");
      window.button("copyButton").click();
      window.label("copiedText").requireText("Some random text");
    }
  }