Package org.eclipse.swtbot.swt.finder

Provides convenience API that most users would like to start with.

See:
Description

Interface Summary

ApplicationRunner

Starts the application under test.

Class Summary

SWTBot	This class contains convenience API to find widgets in SWTBot.
SWTBotAssert	The SWTBotAssert provides extra capabilities for comparing widgets and other UI items.
SWTBotInfo	Dumps information useful for providing debug info.
SWTBotTestCase	The SWTBotTestCase extends the JUnit TestCase to provide extra capabilities for comparing widgets and other UI items.

Enum Summary

ReferenceBy

Annotation Types Summary

Style
SWTBotWidget	Marks a SWTBot widget so tools recognise them.

Package org.eclipse.swtbot.swt.finder Description

Provides convenience API that most users would like to start with.

Most common usage of SWTBot API

Most users would start off as follows:

    SWTBot bot = new SWTBot();

    bot.button("hello world").click();

    // in case you have two edit buttons in two different groups
    // say an edit button in the "Address" section,
    // and another in "Bank Account" section, you can do the following
    // to click on the "Edit" button on the "Bank Account" section.
    // This is the recommended way to use SWTBot, instead of finding widgets based on its index.
    bot.buttonInGroup("Edit", "Bank Account").click();

For finding widgets using custom matchers:

    SWTBot bot = new SWTBot();
    //
    // find a button within the currently active shell:
    //
    SWTBotButton button = new SWTBotButton((Button) bot.widget(aMatcher)); // or
    SWTBotButton button = new SWTBotButton((Button)bot.widget(aMatcher, 3)); // for the 4th widget
    //
    // to find a button within a particular parent composite:
    //
    SWTBotButton button = new SWTBotButton((Button) bot.widget(aMatcher, parentComposite)); //or
    SWTBotButton button = new SWTBotButton((Button) bot.widget(aMatcher, parentComposite, 3)); //for the 4th widget

Using matchers to find widgets using SWTBot

In case the convenience API provided by the SWTBot class does not suit your needs, you can create a matcher using a combination of matchers provided by SWTBot, or write your own matcher. SWTBot provides the following matchers for use. Matchers can be instantiated using the factory provided in WidgetMatcherFactory:

withText -- Finds widgets with the exact text.

withMnemonic -- Finds widgets ignoring all mnemonics (&), accessors etc. Finding a button Edit will match buttons with text &Edit, or E&dit.

withLabel -- Finds widgets with a label before it.

withRegex -- Finds widgets using a regex.

inGroup -- Finds widgets in a particular SWT Group with the specified text.

widgetOfType -- Finds widgets of a particular type(class).

withStyle -- Finds widgets with a particular style bit. Useful, for e.g. to distinguish between RadioButtons, CheckBoxes, and PushButtons

withId -- In case nothing else works! Set the id on the widget using Widget#setData(key, value) and find the widget using that id.

In addition you can use the hamcrest matchers provided by org.hamcrest.Matchers.

To make a combination of matchers, you'll need to static import:

import static org.hamcrest.Matchers.*;
import static org.eclipse.swtbot.swt.finder.matcher.WidgetMatcherFactory.*;

The following will match all buttons that start with foo or belong to group bar:

Matcher matcher = allOf(widgetOfType(Button.class), anyOf(withRegex("^foo.*"), inGroup("bar")));

Some matchers even consume other matchers, the following will match the Edit button in the Bank Account section of the Employer:

Matcher matcher = allOf(widgetOfType(Button.class), withText("Edit"), inGroup(allOf(withText("Bank Account"), inGroup("Employer"))));

+-- Personal Details -------------+
| ...                             |
|  +-- Employee ---------------+  |
|  |  ...                      |  |
|  |  +- Bank Account ------+  |  |
|  |  | ...                 |  |  |
|  |  | #Edit#              |  |  |
|  |  | ...                 |  |  |
|  |  +---------------------+  |  |
|  |                           |  |
|  |  +-- Employer ---------+  |  |
|  |  |...                  |  |  |
|  |  |  +- Bank Account +  |  |  |
|  |  |  | ...           |  |  |  |
|  |  |  | #Edit#        |  |  |  |
|  |  |  | ...           |  |  |  |
|  |  |  +---------------+  |  |  |
|  |  +---------------------+  |  |
|  +---------------------------+  |
+---------------------------------+

Writing your own matchers

Writing your own matchers is simple, you create a subclass of org.hamcrest.BaseMatcher. The following is an example of the WithId matcher:

    public class WithId extends BaseMatcher {
        private final String    key;
        private final String    value;

        public WithId(String key, String value) {
            this.key = key;
            this.value = value;
        }

        public boolean matches(Object obj) {
            if (obj instanceof Widget)
                return value.equals(((Widget) obj).getData(key));
            return false;
        }

        public void describeTo(Description description) {
            description.appendText("with key: ").appendText(key).appendText(" having value: ").appendText(value);
        }
    }