View source for SWTBot/Generator

{{SWTBot}}

== Purpose and limitations ==

=== What it does ===
The test generator can be enabled on any Eclipse-based application at runtime. It monitors at UI events as they are performed by user and the generate some pieces of code that can be reused later in automated tests to playback user actions.

=== Limitations ===
Some conceptual limitations of UI recorders (which are true for SWTBot Generator, but also for [http://seleniumhq.org/ Selenium] or other recorder/playback engines):
* There are several ways to identify a widget, the recorder will choose only one, that may not be the best
* The recorder understand "atomic" UI operation, which may be too fined-grained compared to what you want to test
* The generator is not aware of your code style and tastes, so it may generate code that is not conform to your standards
* The generator doesn't know what to check, it's just a bot: it's your role to add assertions and other checks
All those points mean that the generation of code is only something that makes you save time by replacing some code writting, but the generated code '''always needs to be reviewed and enriched with assertions''' and probably improved.

A limitation that is specific to this recorder and Eclipse is that it does not (yet) support GEF.

=== How to get the maximal benefit from it ===

'''Speed up the process of creating a test:''' instead of writing directly code, start by running your test scenario with the generator enabled. You'll get a huge part of your code already written down, ready to go into a TestCase. Then improve that code is necessary and '''add your assertions and checks'''.

'''Ask users to provide their scenarios as code:''' If possible, when a user has a bug, ask him to start the recorder (you could embed its enablement in a higher-level menu - ''Help > Record usage scenario'' -to prevent end-users from doing complex operations); and ask your users to post the generated code. It will reduce the gap between users reports and unit tests.

== Installation & Configuration ==

The Test recorder and generator is made of 2 parts:
* The "runtime" part which is to be available in the target application (the one where record actions)
* The "IDE" part which can be installed inside the IDE you use in order to develop tests. It provide the UI entries for easier usage of the generator, and some integration with usual components of the IDE.

Depending on your use-case, several installation paths can be taken

=== I'm using an IDE to write test ===

This is the recommended usage scenario. It adds to your IDE menus and wizard to easily start a recording session.

==== Installation ====

In this case, it's recommended to install the SWTBot Generator IDE integration in your IDE, using the [[SWTBot#Update_Sites | update-site/p2 repository]].

==== Configuring a target-platform ====

As SWTBot relies on PDE, it's important to correctly configure the target-platform. This target-platform will be used as the basis to define the "Application Under Test" via IDE. When writing tests, the target-platform should typically contain:
* The application you want to test against
* test dependencies such as SWTBot APIs
In case you want to test against the current IDE, just keep the default target-platform (using current Eclipse installation) with SWTBot installed in it.

This target-platform will be used:
* By SWTBot Recorder to configure the Lauch Configuration (subset of target-platform + startup options)
* By PDE to resolve dependencies in order to compile your tests

==== Startup recording ====

Go to menu ''File > New > Other...'', and look for ''SWTBot > Run test recorder''.

If you choose to start against another application, using the Lauch Configuration, then take care of correctly setting your Lauch Configuration: select the right product, maybe set some system properties... Then you'll see your application starting and the recorder pop-up appear.

=== I want to record on an existing application, without IDE ===

==== Installing generator in the target application ====

The Test recorder and generator runtime is a single plugin to install in any RCP application (may it be your Eclipse IDE, or a bundled RCP application. You can get it from the SWTBot [[SWTBot#Update_Sites | update-site/p2 repository]] (starting from version 2.0.6).

With p2 UI: From the SWTBot Update-site, choose the content for "SWTBot Generator", but avoid everything related to IDE integration (that you won't need and that risk to pollute your target application UI).

With [[Equinox p2 director application|p2 director]], install bundle  '''org.eclipse.swtbot.generator''':
<source lang="bash">
java -jar plugins/org.eclipse.equinox.laucher_*.jar -application org.eclipse.equinox.p2.director -repository <choose_a_SWTBot_p2_repo> -installIU org.eclipse.swtbot.generator
</source>

This will add the necessary plugin to your application

==== Starting application with Generator ====


Ensure '''org.eclipse.swtbot.generator''' bundle is installed in your application (use ''ls'' or [http://www.ibm.com/developerworks/library/os-ecl-osgiconsole/ OSGi console] at runtime to check that).

Set the '''-Dorg.eclipse.swtbot.generator.enable=true''' system property in your config.ini. Example for JBoss Developer Studio, in ''jbdevstudio/studio/jbdevstudio.ini'', line 17:
<source lang="text" line>
-vm
/usr/lib/jvm/java-6-openjdk-amd64/jre/bin/java
-startup
plugins/org.eclipse.equinox.launcher_1.3.0.v20120522-1813.jar
--launcher.library
plugins/org.eclipse.equinox.launcher.gtk.linux.x86_64_1.1.200.v20120522-1813
-product
com.jboss.jbds.product.product
-showsplash
platform\:/base/plugins/com.jboss.jbds.product
--launcher.XXMaxPermSize
256m
--launcher.defaultAction
openFile
-vmargs
-Djboss.discovery.directory.url=https://devstudio.jboss.com/updates/6.0/devstudio-directory.xml
-Dorg.eclipse.swtbot.generator.enable=true
-Xms512m
-Xmx1024m
-Dosgi.instance.area.default=@user.home/workspace
</source>

=== Programatically, from a plugin ===

This is useful to start the recorder from menus, buttons or anything. Just make sure the bundle you're developing depends on '''org.eclipse.swtbot.generator''' and when relevent, invoke the following code to open the recorder Window:
<source lang="java">
org.eclipse.swtbot.generator.ui.StartupRecorder.openRecorder(dialog);
</source>
<br/>
where 'dialog' is one of <code>"org.eclipse.swtbot.generator.dialog.basic"</code> or <code>"org.eclipse.swtbot.generator.dialog.jdt"</code>, or <code>null</code> to use the default that can also be configured with the <code>"org.eclipse.swtbot.generator.dialog"</code> system property.

== Using Recorder ==

When recorder is ready, you see the recorder pop-up appear. Prepare your application for the test (close welcome page and other stuff you don't want to take into account in your test), then on the recorder dialog, click ''Start Recording''. At this point, your UI actions will be recorder and you'll see relevant code appear in the dialog.

When you're done, click ''Stop Recording'' and copy-paste the output where you need (usually in an method in an existing Java Editor). Add the assertions, refactor it if needed. An you have your test ready!

== Extending it ==

=== Rules mechanism ===

The recorder places some SWT listeners that look at events and generate code from each event. A Generator support is just a [http://git.eclipse.org/c/swtbot/org.eclipse.swtbot.git/tree/org.eclipse.swtbot.generator/src/org/eclipse/swtbot/generator/framework/rules/SWTBotGeneratorRules.java set of "rules"] that are classes that process (or not) the current event to generate some code. Processing an event is divided in 2 pieces:
# Create an accessor for the widget (eg: ''bot.button("blah")''
# create an action on the widget (eg: ''.click()'')
There are 2 kinds of rules:
* Simple rules match a single event. Example: [http://git.eclipse.org/c/swtbot/org.eclipse.swtbot.git/tree/org.eclipse.swtbot.generator/src/org/eclipse/swtbot/generator/framework/rules/simple/ComboSelectionRule.java Combo selection]
* Complex rules match several single rules, and then several events. Examples: [http://git.eclipse.org/c/swtbot/org.eclipse.swtbot.git/tree/org.eclipse.swtbot.generator/src/org/eclipse/swtbot/generator/framework/rules/complex/ModifyComboComplexRule.java Combo Text Modify], [http://git.eclipse.org/c/swtbot/org.eclipse.swtbot.git/tree/org.eclipse.swtbot.generator/src/org/eclipse/swtbot/generator/framework/rules/complex/ToolBarMenuComplexRule.java ToolbarMenu]

Those rules are easy to [http://git.eclipse.org/c/swtbot/org.eclipse.swtbot.git/tree/org.eclipse.swtbot.generator.test/src/org/eclipse/swtbot/generator/test/RecordComboTest.java?id=4946c6c9f846cd4c5a81aa397f41ca43259cf8c7 test with JUnit and SWTBot], so please create a similar test-case when creating a rule!

=== Adding and contributing a rule ===

Recommended way to create and contribute a rule is:
# Set up environment as described in the 2 first paragraph of [[SWTBot/Contributing|contribution guide]] : set up target-platform and get source for ''org.eclipse.swtbot.generator'' and ''org.eclipse.swtbot.generator.test'' in IDE
# Write a test for your rule. Use the RecordComboTest as example. Run tests, ensure it's failing.
# Write a rule for the event(s) you're trying to support. Add this rule to the SWTBotGeneratorRules.
# Run your tests and ensure it's now green.
# Contribute test and rule to SWTBot as a [[SWTBot/Contributing#Provide_a_contribution_using_Gerrit|Gerrit patch]].

=== Contribute your own Bot support ===

There is an extension point for that in '''org.eclipse.swtbot.generator'''. We recommend you to [[SWTBot/Contributing#Getting_the_source|get the source]] for the ''org.eclipse.swtbot.generator'' plugin and see what's in it. The default SWTBot support is installed as an extension too, so you can take it as an example.

=== Contributing ===

The contributions tools and process are the same as for any SWTBot part. See [[SWTBot/Contributing]].