Difference between revisions of "SWTBot/UsersGuide"

From Eclipsepedia

Jump to: navigation, search
(Mix it with GEF/GMF to perform checks)
(Tips and tricks)
Line 166: Line 166:
 
TODO: create an example that ensure that creation of a specific element is not possible on mainEditPart
 
TODO: create an example that ensure that creation of a specific element is not possible on mainEditPart
  
== Tips and tricks ==
+
= Tips and tricks =
  
=== Use another DISPLAY ===
+
== Use another DISPLAY on Linux ==
  
 
SWTBot requires tested application to have focus in order to work well. If it happens on the DISPLAY you're working on, then you have to wait for tests to end before you can go on working. It's a waste of time. On Linux, you can run your test on another DISPLAY, so you can keep on working while tests are running. You can use '''Xephyr''' for that, since it allows you to see what is happening in another window. You'll also need to have a Window Manager started on this Xephyr. we recommand to run Metacity, but any other WM should run (twm is successfully used too).
 
SWTBot requires tested application to have focus in order to work well. If it happens on the DISPLAY you're working on, then you have to wait for tests to end before you can go on working. It's a waste of time. On Linux, you can run your test on another DISPLAY, so you can keep on working while tests are running. You can use '''Xephyr''' for that, since it allows you to see what is happening in another window. You'll also need to have a Window Manager started on this Xephyr. we recommand to run Metacity, but any other WM should run (twm is successfully used too).

Revision as of 09:51, 20 July 2012


SWTBot
Website
Update Sites
Community
Mailing List
Forums/Newsgroups
IRC
Contribute
Open Bugzilla tickets
Open Gerrit reviews
Browse Source
Continuous Integration


Contents

SWTBot Users Guide

Information on this page may be outdated, see this page for a more detailed user guide or the cheat sheet

Note that this page is for first time users. Advanced Users click here.

Introduction

SWTBot is an open-source Java based functional testing tool for testing SWT and Eclipse based applications.

SWTBot provides APIs that are simple to read and write. The APIs also hide the complexities involved with SWT and Eclipse. This makes it suitable for functional testing by everyone. SWTBot also provides its own set of assertions that are useful for SWT. You can also use your own assertion framework with SWTBot.

SWTBot can record and playback tests and integrates with Eclipse, and also provides for ant tasks so that you can run your builds from within CruiseControl or any other CI tool that you use.

SWTBot can run on all platforms that SWT runs on. Very few other testing tools provide such a wide variety of platforms.

Quick Start

A Screencast

Videos speak louder than pictures and words put together:

Creating A Project

Create a new project by clicking on File>New>Project. On the New Project Dialog, search for "plug-in", select New Plug-in Project and click Next. Create a new plugin project named org.eclipsecon.swtbot.example.

Swtbot-create-project.gif

Configuration

  • Add the following to your classpath:
  org.eclipse.swtbot.eclipse.core
  org.eclipse.swtbot.eclipse.finder
  org.eclipse.swtbot.junit4_x
  org.hamcrest
  org.apache.commons.collections
  org.junit4
  org.apache.log4j
  org.eclipse.ui

Swtbot-setup-dependencies.gif

Getting started with SWTBot

SWTBot requires that tests run on a non-UI thread, so that PlatformUI.getWorkbench() will return you null and that traditional unit-test code won't work. If you run tests on the UI thread, they will eventually block the UI at some point in time. Take a look into the FAQ for explanations and workaround.

Getting started with SWTBot for Eclipse Plugins

To use SWTBot along with your eclipse plugin application you have to add the below plugins to your dependencies. You can download the example from the swtbot download site http://download.eclipse.org/technology/swtbot/docs/eclipsecon2009/examples.zip.

Now you can start using SWTBot. Below you can find a sample SWTBot testcase:

package org.eclipsecon.swtbot.example;
 
import org.eclipse.swtbot.eclipse.finder.SWTWorkbenchBot;
import org.eclipse.swtbot.swt.finder.junit.SWTBotJunit4ClassRunner;
import org.eclipse.swtbot.swt.finder.widgets.SWTBotShell;
import org.junit.AfterClass;
import org.junit.BeforeClass;
import org.junit.Test;
import org.junit.runner.RunWith;
 
@RunWith(SWTBotJunit4ClassRunner.class)
public class MyFirstTest {
 
	private static SWTWorkbenchBot	bot;
 
	@BeforeClass
	public static void beforeClass() throws Exception {
		bot = new SWTWorkbenchBot();
		bot.viewByTitle("Welcome").close();
	}
 
 
	@Test
	public void canCreateANewJavaProject() throws Exception {
		bot.menu("File").menu("New").menu("Project...").click();
 
		SWTBotShell shell = bot.shell("New Project");
		shell.activate();
		bot.tree().expandNode("Java").select("Java Project");
		bot.button("Next >").click();
 
		bot.textWithLabel("Project name:").setText("MyFirstProject");
 
		bot.button("Finish").click();
		// FIXME: assert that the project is actually created, for later
	}
 
 
	@AfterClass
	public static void sleep() {
		bot.sleep(2000);
	}
 
}

Executing SWTBot Tests for Eclipse Plugins

Now that you've written the great test that you'd always wanted to, lets now see it run. In order to run the test, right click on the test and select Run As > SWTBot Test

Run-as-option.jpg

Select the application that you want to test

Run-as-config-options.jpg

Test a GEF application

Intro

SWT has a plugin that allows to manipulate GEF/GMF diagrams, editors and editParts as easily as you can manipulate SWT widgets with SWTBot. Then you can easily create some repeatable user-level UI interations and check their effects on the diagram

Configuration

The configuration is similar to the one describe before for SWTBot, except that you also have to add org.eclipse.swtbot.eclipse.gef.finder plugin and some other dependencies, such as org.eclipse.ui. In most case, you'll also like to use GEF and/or GMF plugins to make some checks on diagram.

Getting started with examples

If you like to get started with working examples, you can take a look at the following URL, or check them out in your workspace.

Example folders: http://dev.eclipse.org/viewcvs/index.cgi/trunk/examples/gef/?root=Technology_SWTBot
Example test case: http://dev.eclipse.org/viewcvs/index.cgi/trunk/examples/gef/org.eclipse.gef.examples.logic.test/src/org/eclipse/gef/examples/logic/test/OpenGefEditorTest.java?root=Technology_SWTBot&view=markup

General principles

Everything is almost the same as using SWTBot, except that some classes change in order to give you the ability to manipulate DiagramEditors. The SWTBotTestCase superclass must be replaced by SWTBotGefTestCase. From the inside of your SWTBotTestCase, you can access your SWTGefBot bot field to play with your GEF editor. Then you retrieve a SWTBotGefEditor by using bot.getEditor("label of my editor tab").

Once you have your SWTBotGefEditor, you can perform high level user operations programatically:

Creation of elements

	// retrieve editor
	SWTBotGefEditor editor = bot.gefEditor("test.logic"); // editor must be already open
	// Simulate creation of element from palette
	editor.activateTool("Circuit");  // "Circuit" is the label of the tool in palette
	editor.mouseDrag(55, 55, 150, 100);
	editor.activateTool("Circuit");
	editor.mouseMoveLeftClick(150, 150);
	editor.activateTool("Connection");
	editor.mouseMoveLeftClick(150, 150);
	editor.mouseMoveLeftClick(55, 55);

Direct edition of editParts

	SWTBotGefEditPart editPart = editor.getEditPart("edit part label"); // select edit part by label
	editPart.click();
	editor.directEditType("new edit part label");

Perform a drag'n'drop

	editor.mouseDrag(fromXPosition, fromYPosition, toXPosition, toYPosition)

Mix it with GEF/GMF to perform checks

TODO: create an example that ensure that creation of a specific element is not possible on mainEditPart

Tips and tricks

Use another DISPLAY on Linux

SWTBot requires tested application to have focus in order to work well. If it happens on the DISPLAY you're working on, then you have to wait for tests to end before you can go on working. It's a waste of time. On Linux, you can run your test on another DISPLAY, so you can keep on working while tests are running. You can use Xephyr for that, since it allows you to see what is happening in another window. You'll also need to have a Window Manager started on this Xephyr. we recommand to run Metacity, but any other WM should run (twm is successfully used too).

$ Xephyr -screen 1024x768 :51 &
$ export DISPLAY=:51
$ metacity --sm-disable --replace &
$ ...command that runs SWTBot tests...