Improve this doc

Selectors

The JsonWireProtocol provides several strategies to query an element. WebdriverIO simplifies these to make it more familiar with the common existing selector libraries like Sizzle. The following selector types are supported:

CSS Query Selector

1
browser.click('h2.subheading a');

Link Text

To get an anchor element with a specific text in it, query the text starting with an equal (=) sign. For example:

1
<a href="http://webdriver.io">WebdriverIO</a>
1
2
console.log(browser.getText('=WebdriverIO')); // outputs: "WebdriverIO"
console.log(browser.getAttribute('=WebdriverIO', 'href')); // outputs: "http://webdriver.io"

Partial Link Text

To find a anchor element whose visible text partially matches your search value, query it by using *= in front of the query string (e.g. *=driver)

1
<a href="http://webdriver.io">WebdriverIO</a>
1
console.log(browser.getText('*=driver')); // outputs: "WebdriverIO"

Element with certain text

The same technique can be applied to elements as well, e.g. query a level 1 heading with the text “Welcome to my Page”:

1
<h1 alt="welcome-to-my-page">Welcome to my Page</h1>
1
2
console.log(browser.getText('h1=Welcome to my Page')); // outputs: "Welcome to my Page"
console.log(browser.getTagName('h1=Welcome to my Page')); // outputs: "h1"

or using query partial text

1
2
console.log(browser.getText('h1*=Welcome')); // outputs: "Welcome to my Page"
console.log(browser.getText('h1[alt*="welcome"]')); // outputs: "Welcome to my Page"

The same works for ids and class names:

1
<i class="someElem" id="elem">WebdriverIO is the best</i>
1
2
3
4
console.log(browser.getText('.someElem=WebdriverIO is the best')); // outputs: "WebdriverIO is the best"
console.log(browser.getText('#elem=WebdriverIO is the best')); // outputs: "WebdriverIO is the best"
console.log(browser.getText('.someElem*=WebdriverIO')); // outputs: "WebdriverIO is the best"
console.log(browser.getText('#elem*=WebdriverIO')); // outputs: "WebdriverIO is the best"

Tag Name

To query an element with a specific tag name use <tag> or <tag />

Name Attribute

For querying elements with a specific name attribute you can either use a normal CSS3 selector or the provided name strategy from the JsonWireProtocol by passing something like [name="some-name"] as selector parameter

xPath

It is also possible to query elements via a specific xPath. The selector has to have a format like for example //BODY/DIV[6]/DIV[1]/SPAN[1]

In near future WebdriverIO will cover more selector features like form selector (e.g. :password,:file etc) or positional selectors like :first or :nth.

Mobile Selectors

For (hybrid/native) mobile testing you have to use mobile strategies and use the underlying device automation technology directly. This is especially useful when a test needs some fine-grained control over finding elements.

Android UiAutomator

Android’s UI Automator framework provides a number of ways to find elements. You can use the UI Automator API, in particular the UiSelector class to locate elements. In Appium you send the Java code, as a string, to the server, which executes it in the application’s environment, returning the element or elements.

1
2
var selector = 'new UiSelector().text("Cancel").className("android.widget.Button")';
browser.click('android=' + selector);

iOS UIAutomation

When automating an iOS application, Apple’s UI Automation framework can be used to find elements. This JavaScript API has methods to access to the view and everything on it.

1
2
var selector = 'UIATarget.localTarget().frontMostApp().mainWindow().buttons()[0]'
browser.click('ios=' + selector);

You can also use predicate searching within iOS UI Automation in Appium, to control element finding even further. See here for details.

iOS XCUITest predicate strings and class chains

With iOS 10 and above (using the XCUITest driver), you can use predicate strings:

1
2
var selector = 'type == \'XCUIElementTypeSwitch\' && name CONTAINS \'Allow\'';
browser.click('ios=predicate=' + selector);

And class chains:

1
2
var selector = '**/XCUIElementTypeCell[`name BEGINSWITH "D"`]/**/XCUIElementTypeButton';
browser.click('ios=chain=' + selector);

Accessibility ID

The accessibility id locator strategy is designed to read a unique identifier for a UI element. This has the benefit of not changing during localization or any other process that might change text. In addition, it can be an aid in creating cross-platform tests, if elements that are functionally the same have the same accessibility id.

  • For iOS this is the accessibility identifier laid out by Apple here.
  • For Android the accessibility id maps to the content-description for the element, as described here.

For both platforms getting an element, or multiple elements, by their accessibility id is usually the best method. It is also the preferred way, in replacement of the deprecated name strategy.

1
browser.click(`~my_accessibility_identifier`);

Class Name

The class name strategy is a string representing a UI element on the current view.

  • For iOS it is the full name of a UIAutomation class, and will begin with UIA-, such as UIATextField for a text field. A full reference can be found here.
  • For Android it is the fully qualified name of a UI Automator class, such android.widget.EditText for a text field. A full reference can be found here.
1
2
3
4
// iOS example
browser.click(`UIATextField`);
// Android example
browser.click(`android.widget.DatePicker`);

Chain Selectors

If you want to be more specific in your query, you can chain your selector until you’ve found the right element. If you call element before your actual command, WebdriverIO starts query from that element. For example if you have a DOM structure like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<div class="row">
  <div class="entry">
    <label>Product A</label>
    <button>Add to cart</button>
    <button>More Information</button>
  </div>
  <div class="entry">
    <label>Product B</label>
    <button>Add to cart</button>
    <button>More Information</button>
  </div>
  <div class="entry">
    <label>Product C</label>
    <button>Add to cart</button>
    <button>More Information</button>
  </div>
</div>

And you want to add product B to the cart it would be difficult to do that just by using the CSS selector. With selector chaining it gets way easier as you can narrow down the desired element step by step:

1
browser.element('.row .entry:nth-child(1)').click('button*=Add');