Selectors

A selector only builds an element object and does not look anything up yet; the lookup happens when you call exists / click / getText / getRect. Compared with findElement it can pick the n-th match and include hidden elements, but it does not wait.

At a glance

·Selector names match the values of findElement's first argument one to one
·accessibilityId is the most stable: it does not change with the UI language or copy edits
·xpath is flexible but slow — prefer classChain / predicate when they can express the same thing

client.label#

Match elements whose text is exactly the value.

typescript

client.label(value: string, visibleOnly?: boolean, index?: number): Element;

Parameters

Name	Type	Required	Default	Description
`value`	`string`	Yes	—	The element's text; must match exactly.
`visibleOnly`	`boolean`	No	`true`	Only match visible elements. Pass false to include hidden ones (covered, or scrolled off screen).
`index`	`number`	No	`0`	Which match to take when there are several, counting from 0.

Returns

Type	Description
`Element`	An element object. Nothing is looked up yet — the lookup happens when you call exists / click / getText / getRect.

Example

javascript

var ok = client.label('OK');
if (ok.exists()) {
  ok.click();
}
var second = client.label('Follow', true, 1);   // the second "Follow"

client.labelContains#

Match elements whose text contains the value.

typescript

client.labelContains(value: string, visibleOnly?: boolean, index?: number): Element;

Parameters

Name	Type	Required	Default	Description
`value`	`string`	Yes	—	The text to look for inside the element's text.
`visibleOnly`	`boolean`	No	`true`	Only match visible elements. Pass false to include hidden ones (covered, or scrolled off screen).
`index`	`number`	No	`0`	Which match to take when there are several, counting from 0.

Returns

Type	Description
`Element`	An element object. Nothing is looked up yet — the lookup happens when you call exists / click / getText / getRect.

Example

javascript

var follow = client.labelContains('Follow');
if (follow.exists()) {
  follow.click();
}

client.accessibilityId#

Match by the element's name (its accessibilityIdentifier, set by the app's developer). The most stable way to locate an element: it does not change with the UI language or copy edits.

typescript

client.accessibilityId(value: string, visibleOnly?: boolean, index?: number): Element;

Parameters

Name	Type	Required	Default	Description
`value`	`string`	Yes	—	The element's name. Click the element in the console's inspector to see it.
`visibleOnly`	`boolean`	No	`true`	Only match visible elements. Pass false to include hidden ones (covered, or scrolled off screen).
`index`	`number`	No	`0`	Which match to take when there are several, counting from 0.

Returns

Type	Description
`Element`	An element object. Nothing is looked up yet — the lookup happens when you call exists / click / getText / getRect.

Example

javascript

var submit = client.accessibilityId('submit_button');
if (submit.exists()) {
  submit.click();
}

client.xpath#

Match by XPath. Flexible but slow: the whole element tree is serialised before the query runs, which can take seconds on busy screens.

typescript

client.xpath(value: string): Element;

Parameters

Name	Type	Required	Default	Description
`value`	`string`	Yes	—	The XPath expression. The first match is used; write (//expression)[n] for the n-th.

Returns

Type	Description
`Element`	An element object. Nothing is looked up yet — the lookup happens when you call exists / click / getText / getRect.

Notes

If classChain or predicate can express it, do not use XPath.

Example

javascript

var btn = client.xpath('//XCUIElementTypeButton[@name="OK"]');
if (btn.exists()) {
  btn.click();
}

client.classChain#

Match by an iOS class chain — much faster than XPath.

typescript

client.classChain(value: string, index?: number): Element;

Parameters

Name	Type	Required	Default	Description
`value`	`string`	Yes	—	The class chain, for example **/XCUIElementTypeCell[`label CONTAINS "General"`].
`index`	`number`	No	`0`	Which match to take when there are several, counting from 0.

Returns

Type	Description
`Element`	An element object. Nothing is looked up yet — the lookup happens when you call exists / click / getText / getRect.

Example

javascript

var cell = client.classChain('**/XCUIElementTypeButton[`label == "OK"`]');
if (cell.exists()) {
  cell.click();
}

See also client.predicate、client.xpath

client.predicate#

Match with an NSPredicate expression.

typescript

client.predicate(value: string, index?: number): Element;

Parameters

Name	Type	Required	Default	Description
`value`	`string`	Yes	—	The predicate, for example label BEGINSWITH 'Con' or type == 'XCUIElementTypeButton' AND visible == true.
`index`	`number`	No	`0`	Which match to take when there are several, counting from 0.

Returns

Type	Description
`Element`	An element object. Nothing is looked up yet — the lookup happens when you call exists / click / getText / getRect.

Example

javascript

var btn = client.predicate('type == "XCUIElementTypeButton" AND label CONTAINS "Follow"');
if (btn.exists()) {
  btn.click();
}

client.className#

Match by element type, for example XCUIElementTypeCell or XCUIElementTypeSwitch.

typescript

client.className(value: string, index?: number): Element;

Parameters

Name	Type	Required	Default	Description
`value`	`string`	Yes	—	The element type name.
`index`	`number`	No	`0`	Which match to take when there are several, counting from 0.

Returns

Type	Description
`Element`	An element object. Nothing is looked up yet — the lookup happens when you call exists / click / getText / getRect.

Example

javascript

var firstCell = client.className('XCUIElementTypeCell', 0);
if (firstCell.exists()) {
  firstCell.click();
}