Support free tutorials:











vogella training Training Books



SWTBot for testing Eclipse Applications - Tutorial

Lars Vogel

Version 2.3

12.06.2013

Revision History
Revision 0.1 18.09.2010 Lars
Vogel
Created
Revision 0.2 - 2.3 25.09.2010 - 12.06.2013 Lars
Vogel
bug fixes and enhancements

SWTBot

This tutorial describes how to use SWTBot to test Eclipse RCP applications. Within this tutorial Eclipse 4.3 (Kepler) is used.


Table of Contents

1. User interface testing with SWTBot
2. Installation
3. SWTBot API
4. Resetting the workbench in 3.x
5. Prerequisites for this tutorial
6. Exercise: Write SWTBot test
6.1. Installation
6.2. Create project
6.3. Create test
6.4. Adjust launch configuration
6.5. Validate
7. Tutorial: Test Eclipse 3.x RCP applications
7.1. Create project
7.2. Create test plug-in
8. Screenshot
9. Learn more about Eclipse 4 RCP development
10. Support free vogella tutorials
10.1. Thank you
10.2. Questions and Discussion
11. Links and Literature
11.1. Source Code
11.2. SWTBot Resources
11.3. vogella Resources

1. User interface testing with SWTBot

SWTBot is an Eclipse project which supports testing the user interface of an SWT based application.

SWTBot provides an API which allows you to interact with the user interface of the application and to validate certain conditions on the user interface.

The Eclipse or SWT application is started and controlled by SWTBot.

If SWTBot is used to test Eclipse based applications, you need to run the JUnit test with a JUnit Plug-in Test run configuration. A JUnit plug-in test allows you to start and test Eclipse bundles.

2. Installation

Install SWTBot via the Eclipse Update manager which you find under HelpInstall new software. The update site for the SWTBot is: http://download.eclipse.org/technology/swtbot/releases/latest/

Install the SWTBot Eclipse Features and the SWTBot SWT Features.

3. SWTBot API

SWTBot is the base class for testing SWT applications.

The SWTWorkbenchBot class provides API to interact with Eclipse 3.x applications. The SWTWorkbenchBot class extends SWTBot. To test Eclipse 4.x RCP application you use the SWTBot class.

An user interface interaction may take some time, e.g. if the application reads some data. Therefore SWTBot waits, by default, 5 seconds before throwing an exception. You can change the timeout via the following:

// Set the timeout to 6 seconds
SWTBotPreferences.TIMEOUT = 6000; 

For details on the API usage please see SWTBot wiki.

Note

The support for Eclipse 4 RCP application is at the time of this writing fairly new. Therefore this chapter is intentionally short, as improvements and changes are expected in the future. Please see the project homepage for the most recent information.

Warning

Testing an application with a login screen is currently not supported by SWTBot. See SWTBot FAQ.

4. Resetting the workbench in 3.x

JUnit does not require that the tests run in the same order as defined. To ensure that the Eclipse 3.x workbench is in the same state for each test you can use the following command.

bot.resetWorkbench(); 

5. Prerequisites for this tutorial

This tutorial assumes what you have basic understanding of development for the Eclipse platform. Please see Eclipse RCP Tutorial or Eclipse Plug-in Tutorial if you need any basic information.

6. Exercise: Write SWTBot test

6.1. Installation

Ensure to install SWTBot into your Eclipse IDE. See Section 2, “Installation” for detailed information.

6.2. Create project

Create a new plug-in called com.example.e4.rcp.todo.uitest and add the following dependencies to the MANIFEST.MF file:

  • org.eclipse.swt

  • org.junit

  • org.eclipse.swtbot.go

  • org.eclipse.swtbot.junit4_x

  • org.eclipse.swtbot.swt.finder

6.3. Create test

Write the following test class.

package com.example.e4.rcp.todo;

import org.eclipse.swtbot.swt.finder.SWTBot;
import org.eclipse.swtbot.swt.finder.junit.SWTBotJunit4ClassRunner;
import org.eclipse.swtbot.swt.finder.widgets.SWTBotMenu;
import org.junit.AfterClass;
import org.junit.Assert;
import org.junit.BeforeClass;
import org.junit.Test;
import org.junit.runner.RunWith;

@RunWith(SWTBotJunit4ClassRunner.class)
public class ExitHandlerTest {

  private static SWTBot bot;

  @BeforeClass
  public static void beforeClass() throws Exception {
    // don't use SWTWorkbenchBot here which relies on Platform 3.x
    bot = new SWTBot();
  }
  
  @Test
  public void executeExit() {
    // testing on hard-coded String just to have
    // a simple example
    
    
    bot.button("Login").click();
    
    SWTBotMenu fileMenu = bot.menu("File");
    Assert.assertNotNull(fileMenu);
    SWTBotMenu exitMenu = fileMenu.menu("Another Exit");
    Assert.assertNotNull(exitMenu);
    exitMenu.click();
  }

  @AfterClass
  public static void sleep() {
    bot.sleep(2000);
  }
} 

6.4. Adjust launch configuration

Right-click on your test class and select RunJUnit Plug-in Test.

This test run should fail or result in error messages but it creates a launch configuration which you can adjust.

Select RunRun Configurations... and switch to the Main tab.

Select that your product should be started similar to the following screenshot.

Select the product which should be started

6.5. Validate

Run your test and verify that the test runs successfully. If you have used different text in your menu, adjust the test until it runs successfully.

7. Tutorial: Test Eclipse 3.x RCP applications

7.1. Create project

Create a new Eclipse RCP application called de.vogella.swtbot.app based on the "Eclipse application with a view" template.

Change the class View to the following.

package de.vogella.swtbot.app;

import org.eclipse.swt.SWT;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Label;
import org.eclipse.swt.widgets.Text;
import org.eclipse.ui.part.ViewPart;

public class View extends ViewPart {
  public void createPartControl(Composite parent) {
    Label label = new Label(parent, SWT.NONE);
    label.setText("My Label");
    Text text = new Text(parent, SWT.SINGLE | SWT.LEAD | SWT.BORDER);
    text.setText("This is my text");

    // Define another text field but also assign an ID to this field for
    // SWTBot
    text = new Text(parent, SWT.SINGLE | SWT.LEAD | SWT.BORDER);
    text.setText("This text has an ID");
    text.setData("org.eclipse.swtbot.widget.key", "text1");

  }

  
/** * Passing the focus request to the viewer's control. */
public void setFocus() { } }

This view defines two text fields, one of them will be identified by SWTBot via the label and the other through an SWTBot specific ID.

7.2. Create test plug-in

Create another Eclipse plug-in called de.vogella.swtbot.tests.

Add the following dependencies to the MANIFEST.MF file for your test project.

  • org.eclipse.ui

  • org.junit4

  • org.hamcrest

  • org.eclipse.swtbot.swt.finder

  • org.eclipse.swtbot.eclipse.finder

Create the following class which defines the JUnit test.

package de.vogella.swtbot.tests;

import static org.junit.Assert.assertTrue;

import org.junit.Test;

public class UserInterfaceTester {
  @Test
  public void test() {
    assertTrue(true);
  }

} 

Right-click on the test and select Run As SWTBot Test. In the launch configuration maintain your application and add the de.vogella.swtbot.tests and de.vogella.swtbot.app plugins as well as their dependencies to the launch configuration.

If everything runs correctly, you should get a green test. Change your test() method to the following to do some real testing.

package de.vogella.swtbot.tests;

import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertNotNull;
import static org.junit.Assert.assertTrue;

import org.eclipse.swtbot.eclipse.finder.SWTWorkbenchBot;
import org.eclipse.swtbot.eclipse.finder.widgets.SWTBotView;
import org.eclipse.swtbot.swt.finder.widgets.SWTBotText;
import org.junit.Test;

public class UserInterfaceTester {
  private final SWTWorkbenchBot bot = new SWTWorkbenchBot();

  @Test
  public void test() {
    // find the text after the label "My Label"
    SWTBotText textWithLabel = bot.textWithLabel("My Label");
    // Set the focus and write a text into the text field
    textWithLabel.setFocus();
    assertEquals(textWithLabel.getText(), "This is my text");
    textWithLabel.selectAll();
    textWithLabel.typeText("Java rules them all");
    assertEquals(textWithLabel.getText(), "Java rules them all");

    // find the text with with the assigned id
    SWTBotText textWithId = bot.textWithId("text1");
    assertEquals(textWithId.getText(), "This text has an ID");

    // now lets find a view part
    SWTBotView viewById = bot.viewById("de.vogella.swtbot.app.view");
    assertNotNull(viewById);

    // Select the exit menu
    // bot.menu("/File").menu("Exit").click();

    assertTrue(true);
  }
} 

Run your test again and verify that the test runs ok. Change, for example, the content of one text field, re-run the test and verify that the test fails.

8. Screenshot

SWTBot can automatically generate screenshots of the running application if a test fails. To use this feature include the plug-in org.eclipse.swtbot.junit4_x into the dependencies of your test project. Annotate your class test with @RunWith(SWTBotJunit4ClassRunner.class). This will automatically generated screenshots in the screenshots folder or your test projects. If you do not see this folder in your project, try refreshing the project (F5).

You can trigger a screenshot in your code via the method bot.captureScreenshot(fileName).

9. Learn more about Eclipse 4 RCP development

I hope you enjoyed this tutorial. You find this tutorial and much more information also in the Eclipse 4 RCP book from this author.

10. Support free vogella tutorials

Maintaining high quality free online tutorials is a lot of work. Please support free tutorials by donating or by reporting typos and factual errors.

10.1. Thank you

Please consider a contribution if this article helped you.

Flattr this

10.2. Questions and Discussion

If you find errors in this tutorial, please notify me (see the top of the page). Please note that due to the high volume of feedback I receive, I cannot answer questions to your implementation. Ensure you have read the vogella FAQ as I don't respond to questions already answered there.

11. Links and Literature

11.1. Source Code

Source Code of Examples

11.2. SWTBot Resources

SWTBot homepage

SWTBot FAQ

11.3. vogella Resources

vogella Training Android and Eclipse Training from the vogella team

Android Tutorial Introduction to Android Programming

GWT Tutorial Program in Java, compile to JavaScript and HTML

Eclipse RCP Tutorial Create native applications in Java

JUnit Tutorial Test your application

Git Tutorial Put all your files in a distributed version control system