Difference between revisions of "SWTBot/UsersGuide"

From Eclipsepedia

Jump to: navigation, search
m
(updated userguide to the latest update.)
Line 15: Line 15:
 
SWTBot can run on all platforms that SWT runs on. Very few other testing tools provide such a wide variety of platforms.
 
SWTBot can run on all platforms that SWT runs on. Very few other testing tools provide such a wide variety of platforms.
 
==Quick Start==
 
==Quick Start==
 +
 +
=== 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'''.
 +
 +
[[Image:Swtbot-create-project.gif]]
 +
 
===Configuration===
 
===Configuration===
  
 
* Add the following to your classpath:
 
* Add the following to your classpath:
 +
  org.eclipse.swtbot.eclipse.finder
 
   org.eclipse.swtbot.finder
 
   org.eclipse.swtbot.finder
 +
  org.eclipse.swtbot.junit4_x
 +
  org.hamcrest
 
   org.apache.commons.collections
 
   org.apache.commons.collections
 +
  org.junit4
 
   org.apache.log4j
 
   org.apache.log4j
* These are useful if you are using SWTBot to test Eclipse plugins
+
 
  org.eclipse.swtbot.eclipse.finder
+
[[Image:Swtbot-setup-dependencies.gif]]
  
 
===Getting started with SWTBot===
 
===Getting started with SWTBot===
  
 
SWTBot requires that tests run on a non-UI thread. If you run tests on the UI thread, they will eventually block the UI at some point in time. More info on this behavior available in the [[SWTBot/FAQ|FAQ]].
 
SWTBot requires that tests run on a non-UI thread. If you run tests on the UI thread, they will eventually block the UI at some point in time. More info on this behavior available in the [[SWTBot/FAQ|FAQ]].
 
===Getting started with SWTBot for SWT applications===
 
 
Because SWTBot tests need to [[SWTBot/FAQ#Why_do_tests_run_on_a_non-UI_thread.3F|run in a non-UI thread]], it is essential that the application starts off in another thread. The example below uses a simple mechanism to start the tests in another thread. You could use any other mechanism to do this instead.
 
 
<source lang="java">
 
import org.eclipse.swtbot.swt.finder.SWTBotTestCase;
 
import org.eclipse.swtbot.swt.finder.utils.SWTUtils;
 
import org.eclipse.swtbot.swt.finder.widgets.TimeoutException;
 
 
import org.eclipse.swt.widgets.Display;
 
 
public class FooBarTest extends SWTBotTestCase {
 
 
  // pull this up into your own superclass that extends SWTBotTestCase and extend from your superclass instead
 
  static {
 
    startApplicationInAnotherThread();
 
  }
 
 
  protected void setUp() throws Exception {
 
    super.setUp();
 
    waitForDisplayToAppear(5000); // wait for the display to appear before you do anything
 
  }
 
 
  public void testClicksOnAButton() throws Exception {
 
    bot.button("click me").click();
 
    bot.button("you just clicked me!").click();
 
  }
 
 
  public void testThisFails() throws Exception {
 
    bot.button("this does not exist").click();
 
  }
 
 
  private void waitForDisplayToAppear(long timeOut) throws TimeoutException, InterruptedException {
 
    long endTime = System.currentTimeMillis() + timeOut;
 
    while (System.currentTimeMillis() < endTime) { // wait until timeout
 
      try {
 
        Display display = SWTUtils.display();
 
        if (display != null)
 
          return;
 
      } catch (Exception e) {
 
        // did not find a display? no problems, try again
 
      }
 
      Thread.sleep(100); // sleep for a while and try again
 
    }
 
    throw new TimeoutException("timed out");
 
  }
 
 
  private static void startApplicationInAnotherThread() {
 
    new Thread(new Runnable() {
 
      public void run() {
 
        new MyApplication().main(new String[] { "some", "command", "line", "arguments for your application" });
 
      }
 
    }).start();
 
  }
 
 
}
 
</source>
 
  
 
===Getting started with SWTBot for Eclipse Plugins===
 
===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.
+
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.
 
    
 
    
  org.eclipse.swtbot.swt.finder
 
  org.eclipse.swtbot.eclipse.finder
 
  org.junit4
 
 
 
Now you can start using SWTBot. Below you can find a sample SWTBot testcase:
 
Now you can start using SWTBot. Below you can find a sample SWTBot testcase:
  
 
<source lang="java">
 
<source lang="java">
import junit.framework.TestCase;
+
package org.eclipsecon.swtbot.example;
  
 
import org.eclipse.swtbot.eclipse.finder.SWTEclipseBot;
 
import org.eclipse.swtbot.eclipse.finder.SWTEclipseBot;
import org.eclipse.swtbot.swt.finder.exceptions.WidgetNotFoundException;
+
import org.eclipse.swtbot.swt.finder.junit.SWTBotJunit4ClassRunner;
import org.eclipse.swtbot.swt.finder.widgets.SWTBotTree;
+
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 {
* This is a sample swtbot testcase for an eclipse application.
+
*
+
*/
+
public class TestSampleDialog extends TestCase {
+
  
  /**
+
private static SWTEclipseBot bot;
  * In future you will not need to create this instance.
+
  * You need to extend SWTBotEclipseTestCase which holds an instance of
+
  * SWTEclipseBot.
+
  */
+
  protected SWTEclipseBot bot = new SWTEclipseBot();
+
  
  /**
+
@BeforeClass
  * This testcase will create a new java project in
+
public static void beforeClass() throws Exception {
  * your workspace.
+
bot = new SWTEclipseBot();
  */
+
bot.view("Welcome").close();
  public void testCreateJavaProject() {
+
}
  
    try {
 
      bot.view("Welcome").close() ;
 
    } catch (WidgetNotFoundException e) {
 
      fail("Welcome window not found.");
 
    }
 
   
 
    //This will open the the menu File > New > Project wizard
 
    bot.menu("File").menu("New").menu("Project...").click();
 
    bot.sleep(1000);
 
   
 
    //Select the java project from the wizard tree.
 
    SWTBotTree projectSelectionTree = bot.tree();
 
    projectSelectionTree.select("Java Project");
 
    bot.sleep(1000);
 
   
 
    //Click Next button
 
    bot.button("Next >").click();
 
    bot.sleep(1000);
 
   
 
    //'com.swtbot.test.project' is the java project name to create
 
    bot.textWithLabel("Project name:").setText("com.swtbot.test.project");
 
    bot.sleep(1000);
 
   
 
    //Click the Finish button
 
    bot.button("Finish").click();
 
    bot.sleep(1000);
 
   
 
    //Now the project is created in your workspace.
 
  }
 
 
 
  /**
 
  * This testcase will set the focus on a view.
 
  */
 
  public void testFocusView() {
 
    try {
 
      bot.view("Welcome").close() ;
 
    } catch (WidgetNotFoundException e) {
 
      fail("Welcome window not found.");
 
    }
 
  
    //This will set focus on the Problems view
+
@Test
    //The view is identified using the title of the view.
+
public void canCreateANewJavaProject() throws Exception {
    bot.view("Problems").setFocus();
+
bot.menu("File").menu("New").menu("Project...").click();
  
    //The sleep command can be used to slow down the testcase
+
SWTBotShell shell = bot.shell("New Project");
    //execution so that you can see it or you can wait for a
+
shell.activate();
    //background process to complete.
+
bot.tree().select("Java Project");
    bot.sleep(2000);
+
bot.button("Next >").click();
  }
+
}
+
</source>
+
  
You can find one more SWTBot Testcase snippet below,
+
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);
 +
}
  
<source lang="java">
 
// subclassing SWTBotTestCase gives you an instance of
 
// SWTBot that offers a lot of convinience api
 
// this class also has a lot of assertions that are suited for ui operations
 
public class FooTest extends SWTBotEclipseTestCase {
 
 
  // stuff you can do with Eclipse
 
  public void testDoSomethingInterestingWithEclipse() throws Exception {
 
    bot.view("Package Explorer").close();
 
    bot.editor("HelloWorld.java").save();
 
    bot.editor("FooBar.java").close();
 
 
    bot.activeEditor().typeText("public static void main ()...");
 
    bot.activeEditor().quickfix("Rename in file");
 
 
    // will insert "System.out.println();" in the currently open editor
 
    bot.activeEditor().autoCompleteProposal("sys", "sysout - print to standard out");
 
  }
 
 
  // stuff you can do with SWT
 
  public void testDoSomethingInterestingWithSWT() throws Exception {
 
 
    // there are two parts to SWTBot:
 
    // one to find a control (the subject)
 
    // and the action to be performed on the control (the verb)
 
    bot.shell("Address Book - Untitled").activate();
 
    bot.button("Hello World").click();
 
    bot.menu("File").menu("New").click();
 
    bot.captureScreenshot("myscreenshot.png");
 
 
    bot.listWithLabel("My Items").select(new String[] { "foo", "bar", "baz" });
 
 
    // there are a lot of assertions that are very useful
 
    assertEnabled(bot.button("Foo Bar"));
 
    assertVisible(bot.checkBox("This should not visible"));
 
    assertTextContains("I just love this!", bot.textWithLabel("Comments"));
 
  }
 
 
}
 
}
 
</source>
 
</source>
Line 219: Line 94:
 
===Executing SWTBot Tests for Eclipse Plugins===
 
===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 > Run Configurations...
+
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'''
  
 
[[Image:run-as-option.jpg]]
 
[[Image:run-as-option.jpg]]
 
 
Create a new test under SWTBot Test. Ensure that you're using JUnit 3
 
 
[[Image:run-as-config-create.jpg]]
 
 
  
 
Select the application that you want to test
 
Select the application that you want to test
  
 
[[Image:run-as-config-options.jpg]]
 
[[Image:run-as-config-options.jpg]]

Revision as of 04:04, 1 July 2009


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

Note that this page is for naive and 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

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.finder
  org.eclipse.swtbot.finder
  org.eclipse.swtbot.junit4_x
  org.hamcrest
  org.apache.commons.collections
  org.junit4
  org.apache.log4j

Swtbot-setup-dependencies.gif

Getting started with SWTBot

SWTBot requires that tests run on a non-UI thread. If you run tests on the UI thread, they will eventually block the UI at some point in time. More info on this behavior available in the FAQ.

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.SWTEclipseBot;
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 SWTEclipseBot	bot;
 
	@BeforeClass
	public static void beforeClass() throws Exception {
		bot = new SWTEclipseBot();
		bot.view("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().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