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);
            }
        }