Install

Releases for WebdriverIO v5 are released on the v5 branch, while releases for WebdriverIO v6 are releases on the master branch.

Check the releases here, the releases for WebdriverIO v6 are prefixed with 6-, while releases for WebdriverIO v5 are prefixed with 5-.

npm install -D [email protected]          # WebdriverIO v6
npm install -D [email protected]          # WebdriverIO v5

Table of Contents

• TSDoc
• Mobile Selectors
  • Combining selectors
  • Custom Selectors
• Usage in Action

TSDoc

You can find documentation for the individual methods here: https://martinfrancois.github.io/wdio-mobile-utils/

Mobile Selectors

In cases where you cannot use accessibilityIds, it is recommended to use ios predicate for iOS and UiSelector for Android. wdio-mobile-utils provides an abstraction to build mobile selectors easily which are cross-platform. This means you can build your selectors using mobile$ and mobile$$ and wdio-mobile-utils will automatically convert this into an ios predicate for iOS and UiSelector for Android for you automatically, depending on which platform the test is running on.

To select one element, use mobile$, which is the equivalent to $ in WebdriverIO. To select all elements use mobile$$, which is the equivalent to $$ in WebdriverIO.

You can find all of the different Selectors you can use in the TSDoc for Selector.

For example, to select a button which works on both Android and iOS, we can use the following selector with wdio-mobile-utils:

mobile$(Selector.type(Type.BUTTON));

Internally, it will convert this into the following ios predicate and UiSelector selectors, depending on the platform the test is running on:

// UiSelector
$('android=new UiSelector().className("android.widget.Button")');

// ios predicate
$("-ios predicate string:type == 'XCUIElementTypeButton'");

Combining selectors

You can also use multiple selectors together, combining them either with an AND (&&) or an OR (||) condition:

Selector.and(selector1, selector2); // AND (&&) condition
Selector.or(selector1, selector2); // OR (||) condition

For example, to select a button with the text Login which works on both Android and iOS, we can use the following selector with wdio-mobile-utils:

// compact form
mobile$(Selector.and(Selector.type(Type.BUTTON), Selector.text('Login')));

// long form
mobile$(
    Selector.and(
       Selector.type(Type.BUTTON),
       Selector.text('Login')
    )
);

Internally, it will convert this into the following ios predicate and UiSelector selectors, depending on the platform the test is running on:

// UiSelector
$('android=new UiSelector().className("android.widget.Button").text("Login")');

// ios predicate
$("-ios predicate string:type == 'XCUIElementTypeButton' && label == 'Login'");

Custom Selectors

If you can't find a selector you're looking for, if it's generic enough to be useful for others, consider contributing with a PR here.

If you need to use a very specific selector or one that may only work on one platform and you still want to make use of the easy fluent API of wdio-mobile-utils, you can use a custom selector.

For example:

mobile$(
    Selector.custom(
        AndroidSelector.of(ANDROID_UISELECTOR_PROPERTIES.RESOURCE_ID, 'URL'),
        IosSelector.of(IOS_PREDICATE_ATTRIBUTES.VALUE, IOS_PREDICATE_COMPARATOR.EQUALS, 'URL')
    )
);

To create a selector which only works on one platform, set one of the selectors to null, like so:

mobile$(
    Selector.custom(
        null, // no selector on Android
        IosSelector.of(IOS_PREDICATE_ATTRIBUTES.RECT, IOS_PREDICATE_COMPARATOR.EQUALS, 'URL')
    )
);

Note that when creating a selector which only works on one platform (for example, only for iOS), if a test is executed on the other platform (for example, Android), it will throw an error. This also applies in cases where a selector which only works on one platform is combined with a cross-platform selector, which is used on the other platform.

Usage in Action

Check out the recording and the slides of my presentation at SauceCon Online 2020 for detailed information on how to use the library.