View source for SWTBot/Automate test execution

{{SWTBot}}

= Environment requirements =

On Mac and Windows, you can only run SWTBot tests in the main UI session, and you have to wait for tests to finish before you can keep on working.
On Linux, you need to have a X session started with a Window Manager. GTK must be installed.

== Locally ==

=== Linux hints ===

==== use another DISPLAY to save time ====
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'''.
<pre>
$ Xephyr -screen 1024x768 :51 &
$ export DISPLAY=:51
$ metacity --sm-disable --replace &
$ ...command that runs SWTBot tests...
</pre>

The DISPLAY can be set from Eclipse Run configuration, in the Environment tab.

=== Windows hints ===

==== Use Cygwin/X ====

Never tested...

== On Jenkins ==

=== Linux hints ===
* Use [https://wiki.jenkins-ci.org/display/JENKINS/Xvnc+Plugin Xvnc] or [https://wiki.jenkins-ci.org/display/JENKINS/Xvfb+Plugin Xvfb] Jenkins plugin in you job to start on X session on a new DISPLAY.
* Invoke a "Shell build step" to start a window manager: ''metacity'' is recommended, some other may work too, but the oldest ones (such as twm) are known to make some tests failing

=== Windows hints ===
* Do Not install Jenkins as a service: it causes focus issues that prevent SWTBot from working well.

= With Maven and Tycho = 

Tycho tests can be run in SWTBot as normal surefire test. The only difference is SWTBot requires '''<useUIHarness>true</useUIHarness>''' and '''<useUIThread>false</useUIThread>'''

<source lang="xml">
<build>
    <plugins>
        <plugin>
            <groupId>org.eclipse.tycho</groupId>
            <artifactId>tycho-surefire-plugin</artifactId>
            <version>${tycho.version}</version>
            <configuration>
              <useUIHarness>true</useUIHarness>
              <useUIThread>false</useUIThread>
              <product>org.eclipse.sdk.ide</product>
              <application>org.eclipse.ui.ide.workbench</application>
            </configuration>
        </plugin>
    </plugins>
</build>
</source>

Debug can be enabled using the tycho-surefire-plugin [http://www.eclipse.org/tycho/sitedocs/tycho-surefire/tycho-surefire-plugin/test-mojo.html#debugPort -DdebugPort] flag on command-line.

Examples:
* Eclipse EGit is running swtbot tests using Maven 3.0 and Tycho :
** http://wiki.eclipse.org/EGit/Contributor_Guide#During_Maven_Build
** [http://egit.eclipse.org/w/?p=egit.git;a=blob;f=org.eclipse.egit.ui.test/pom.xml;h=6bfc5e6aafdc939110f5fe1dbf18ab7668e8d789;hb=da053e043f3224c714774746f1f3aa9f639e3fe1 org.eclipse.egit.ui.test/pom.xml for egit ui test bundle]
** [http://egit.eclipse.org/w/?p=egit.git;a=blob;f=pom.xml;h=df22dd38eb89f40d05d01f7caf9233bda5706d0f;hb=da053e043f3224c714774746f1f3aa9f639e3fe1 egit parent pom.xml]

= With Ant or Command-Line =


SWTBot allows for tests to be executed from ant or command-line. Here are some steps that you need to perform in order to run tests in a 'headless' way.

== A Screencast ==

Videos speak louder than pictures and words put together: 
* [http://download.eclipse.org/technology/swtbot/docs/videos/beginners/SWTBotGettingStartedIn5Minutes A 5 minute quick quick tutorial on how to get started with swtbot]
* [http://download.eclipse.org/technology/swtbot/docs/videos/beginners/SWTBotHeadlessTestingForNovices Running SWTBot tests from the command line]

== Installing headless Testing Framework ==

=== With p2 (recommanded) ===

From your favourite RCP application using p2, run, by replacing SWTBot site by the SWTBot update site of the version you want to use
<pre>
SWTBOT_SITE=...
java -jar plugins/org.eclipse.equinox.laucher_*.jar -application org.eclipse.p2.director -consolelog -repository $SWTBOT_SITE -installIU org.eclipse.swtbot.eclipse.test.junit.feature.group -installIU org.hamcrest
</pre>

See [[Equinox/p2/Director_application|Director app wiki page]] for details.

=== or unzipping manually (deprecated) ===

This approach is deprecated because installing bundles just by unzipping does not ensure a successful installation. Using p2 is much better as it will generally work, and if it does not, it tells you why. Please also note that this approach is not supported/tested since SWTBot 2.1.0.

* Download the '''Headless Testing Framework''' for running tests from within ant. This file is called named something like org.eclipse.swtbot.eclipse.test-2.0.0.187-dev.zip
* You'll need the following plugins from swtbot (you don't need all the swtbot packages)
** org.eclipse.swtbot.swt.finder
** org.eclipse.swtbot.eclipse.finder
** org.hamcrest
** org.junit4(recommended) you may also use org.junit
** org.apache.log4j

=== Setup ===

Your folder structure should look like the following:

<pre>
ECLIPSE_HOME
 + plugins
  | - com.yourplugins
  | - ...
  | - ...
  | - org.eclipse.swtbot.swt.finder
  | - org.eclipse.swtbot.eclipse.finder
  | - org.hamcrest (and other dependencies)
  | - ...
  | - ...
  | - org.eclipse.swtbot.ant.optional.junit4 (or junit3, but not both) (from the Headless Testing Framework)
  | - org.eclipse.swtbot.eclipse.junit4.headless (or junit3.headless, but not both) (from the Headless Testing Framework)
  | - org.junit4 (or org.junit, but not both)
 + features
</pre>

== Executing ==

The key is to run the org.eclipse.swtbot.eclipse.junit4.headless.swtbottestapplication

=== Command-line ===
Here's a command line argument that's used to execute the tests:

<pre>

$ ECLIPSE_HOME=/path/to/your/application
$ TEST_CLASS=com.yourcompany.product.test.AllTessts # see http://github.com/ketan/swtbot/blob/master/org.eclipse.swtbot.eclipse.finder.test/src/org/eclipse/swtbot/eclipse/finder/AllTests.java for an example
$ TEST_APPLICATION_ID=com.yourcompany.example.application # the id of the application that needs to be tested
$ WORKSPACE=/path/to/your/workspace
$ TEST_PRODUCT_ID=com.yourcompany.product # optional, if you're not using a product, please do not add the -product argument in the command below
$ TEST_PLUGIN_ID=com.yourcompany.product.test # the id of the plugin containing SWTBot tests

$ OS=[macosx | win32 | linux]
$ WS=[[cocoa|carbon] | gtk | win32] # for macosx, linux, and windows respectively.
$ ARCH=[x86|x86_64] # for 32 bit and 64 bit swt binaries.

$ $JAVA_HOME/bin/java \
 -Xms256M -Xmx768M -XX:MaxPermSize=512M \
 -classpath $ECLIPSE_HOME/plugins/org.eclipse.equinox.launcher_1.0.200.v20090128-1500.jar \
 org.eclipse.core.launcher.Main \
 -application org.eclipse.swtbot.eclipse.junit4.headless.swtbottestapplication \
 -testApplication $TEST_APPLICATION_ID
 -product $TEST_PRODUCT_ID \ # optional, only if you're working with a product
 -data $WORKSPACE \
 formatter=org.apache.tools.ant.taskdefs.optional.junit.XMLJUnitResultFormatter,$ECLIPSE_HOME/$TEST_CLASS.xml \
 formatter=org.apache.tools.ant.taskdefs.optional.junit.PlainJUnitResultFormatter \
 -testPluginName $TEST_PLUGIN_ID \
 -className $TEST_CLASS \
 -os $OS -ws $WS -arch $ARCH \
 -consoleLog -debug
</pre>

This will run the test specified by TEST_CLASS and generate the test output in ECLIPSE_HOME/TEST_CLASS.xml. This output can be parsed using junitreport ant task.

=== Ant ===

<source lang="xml">
<echo>SWTBot test</echo>
<java dir="${eclipse.home}" fork="true" output="${eclipse.test.home}/output.txt" logError="true" classname="org.eclipse.core.launcher.Main" failonerror="false">
	<classpath>
		<fileset dir="${eclipse.home}/plugins">
			<include name="org.eclipse.equinox.launcher_*.jar"/>
		</fileset>
	</classpath>
	<jvmarg line="-Xms256M -Xmx768M -XX:MaxPermSize=512M"/>
	<arg line="-application org.eclipse.swtbot.eclipse.junit4.headless.swtbottestapplication"/>
	<arg line="ARGUMENTS"/>
	<arg line="FROM"/>
	<arg line="COMMAND LINE"/>
	<arg line="EXAMPLE ABOVE"/>
</java>
</source>		

====Pre-prepared ant tasks====
The script at http://github.com/ketan/swtbot/blob/master/org.eclipse.swtbot.releng/test-sandbox/org.eclipse.swtbot.eclipse.finder.test.xml shows an example of how you can use the standard ant task available with SWTBot:

<source lang="xml">
<ant target="swtbot-test" antfile="${library-file}" dir="${eclipse-home}">
	<property name="data-dir" value="${temp-workspace}" />
	<property name="plugin-name" value="${plugin-name}" />
	<property name="classname" value="org.eclipse.swtbot.eclipse.finder.AllTests" />
	<property name="vmargs" value=" -Xms128M -Xmx368M -XX:MaxPermSize=256M ${jvmOption}" />
</ant>
</source>

The ${library-file} is part of the '''Headless Test Framework''' and can be viewed at http://github.com/ketan/swtbot/blob/master/org.eclipse.swtbot.eclipse.junit4.headless/library.xml. This ant script performs the actual launch for the tests using the command line above.

=== Debugging from Eclipse ===

You can enable debug using standard JVM debug flags on your test process ''-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=y'' and then using Eclipse debug "Remote Java Application", bind it to port 8000 (as specified by ''socket'' in command-line).

= On an already packaged RCP application =

== Alter an RCP application to install and run your tests ==

# Your tests must be available in a p2 repository/update-site
# Use p2 UI or [http://help.eclipse.org/indigo/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/p2_director.html p2 director] in install SWTBot + your test bundles from update-sites into you application
# Use the command-line described earlier to start SWTBot test execution on your application (think about setting the '''-product''' and/or '''-application''' parameters)

You can debug this from Eclipse using the command-line arguments described earlier.

== Or, use your IDE to run tests on an existing application ==

# Install SWTBot in your IDE to access the SWTBot configuration menus
# Create a Target Platform made of your application + SWTBot runtime.
# Import your test bundles as projects in your workspace
# Then use the "SWTBot tests" wizard to configure the execution: think about including all Target Platform + SWTBot + your tests bundles; and configure product to refer to your application.
You'll also be able to use Debug.