Elements

The group scripts use most. Arguments go in order: how to look, what to look for, and how many seconds to wait. A miss returns null or false instead of throwing; only a wrong argument throws INVALID_ARGUMENT.

Кратко о модуле

·The first two arguments are how to look (7 strategies, named like the selectors) and what to look for
·The third argument is the wait in seconds: findElement / getElementText look once by default, clickElement waits up to 10 seconds
·clickElement logs whether it tapped by default (setClickLog turns it off); the fourth argument is the name in the log, the fifth picks where to tap
·The returned element object is used through four methods: exists / click / getText / getRect

findElement#

Find an element. By default it looks once; with a timeout it looks again every 0.5 seconds until the element appears or time runs out. Returns the element object, or null.

typescript

type By =
  | "label" | "labelContains" | "accessibilityId"
  | "xpath" | "predicate" | "classChain" | "className";

findElement(by: By, value: string, timeoutSec?: number): Element | null;

Параметры

Параметр	Тип	Обязательный	По умолчанию	Описание
`by`	`By`	Да	—	How to look: label matches the text exactly, labelContains matches text that contains the value, accessibilityId matches the element's name (set by the app's developer — the most stable choice), and xpath / predicate / classChain / className work like the selectors of the same name. Only these 7 values are accepted; anything else throws INVALID_ARGUMENT, and the message shows the corrected call.
`value`	`string`	Да	—	What to look for — text, a name or an expression, depending on by. Must not be empty.
`timeoutSec`	`number`	Нет	`0`	The longest wait, in seconds. 0 means look once.

Возвращаемое значение

Тип	Описание
`Element \| null`	The element object, or null if it did not appear in time.

Исключения

Исключение	Когда возникает
`WDAError`INVALID_ARGUMENT	A parameter is wrong: by is not one of the 7 values, value is empty, the wait is not a number or exceeds 600 (usually milliseconds passed by mistake), or an old-style {} was passed. A missing element is not an error and never throws.

Примечания

Passing only the text (findElement('Log in')) or an old-style {} throws, and the message contains the corrected line.
With several matches it takes the first visible one. To pick another one, or to include hidden elements, use a selector: client.label('OK', false, 1).

Пример

javascript

if (findElement('label', 'Log in', 3)) {
  logi('login screen detected');
}

var balance = findElement('labelContains', 'Balance');
if (balance) {
  logi(balance.getText());
}

См. также clickElement、getElementText、client.label

clickElement#

Wait for an element and tap it at a random spot inside it. Returns true when tapped and false when it never appeared or could not be tapped — it does not throw.

typescript

clickElement(
  by: By,
  value: string,
  timeoutSec?: number,
  desc?: string,
  position?: "random" | "up" | "center" | "bottom"
): boolean;

Параметры

Параметр	Тип	Обязательный	По умолчанию	Описание
`by`	`By`	Да	—	How to look: label matches the text exactly, labelContains matches text that contains the value, accessibilityId matches the element's name (set by the app's developer — the most stable choice), and xpath / predicate / classChain / className work like the selectors of the same name. Only these 7 values are accepted; anything else throws INVALID_ARGUMENT, and the message shows the corrected call.
`value`	`string`	Да	—	What to look for — text, a name or an expression, depending on by. Must not be empty.
`timeoutSec`	`number`	Нет	`10`	The longest wait, in seconds. Use 1 for pop-ups that may or may not appear, so a miss does not cost 10 seconds.
`desc`	`string`	Нет	—	The element's name in the task log, which records "tapped" or "not found" for it. When omitted the locator is used instead, e.g. label=OK. In tight polling loops turn logging off with setClickLog(false).
`position`	`"random" \| "up" \| "center" \| "bottom"`	Нет	`"random"`	Where to tap: random anywhere inside the element (mostly around the middle), up in the upper third, center near the middle, bottom in the lower third. These match the four tap-position options in the recorder.

Возвращаемое значение

Тип	Описание
`boolean`	True when tapped; false when the element never appeared or the tap failed.

Исключения

Исключение	Когда возникает
`WDAError`INVALID_ARGUMENT	A parameter is wrong, including a position outside the 4 values. Argument mistakes are the script's fault, so they throw instead of being reported as a miss. Passing text as the third argument (where the old API put the name) also throws, with a hint to move it to the fourth.

Пример

javascript

clickElement('label', 'OK');
clickElement('labelContains', 'Skip', 1);         // optional pop-up, wait 1 second at most
clickElement('label', 'OK', 10, 'OK button');     // shown as "OK button" in the log
clickElement('accessibilityId', 'publish', 5, null, 'center');

См. также findElement、element.click、setClickLog

getElementText#

Read an element's text, or one of its attributes. Returns null when the element is missing or nothing can be read.

typescript

getElementText(by: By, value: string, timeoutSec?: number, attr?: string): string | null;

Параметры

Параметр	Тип	Обязательный	По умолчанию	Описание
`by`	`By`	Да	—	How to look: label matches the text exactly, labelContains matches text that contains the value, accessibilityId matches the element's name (set by the app's developer — the most stable choice), and xpath / predicate / classChain / className work like the selectors of the same name. Only these 7 values are accepted; anything else throws INVALID_ARGUMENT, and the message shows the corrected call.
`value`	`string`	Да	—	What to look for — text, a name or an expression, depending on by. Must not be empty.
`timeoutSec`	`number`	Нет	`0`	The longest wait, in seconds. 0 means look once.
`attr`	`string`	Нет	—	Omit it to read the text; name an attribute such as value, enabled or name to read that instead.

Возвращаемое значение

Тип	Описание
`string \| null`	The text or attribute value, or null.

Исключения

Исключение	Когда возникает
`WDAError`INVALID_ARGUMENT	A parameter is wrong: by is not one of the 7 values, value is empty, the wait is not a number or exceeds 600 (usually milliseconds passed by mistake), or an old-style {} was passed. A missing element is not an error and never throws.

Пример

javascript

var balance = getElementText('accessibilityId', 'balance', 3);
if (balance !== null) {
  logi('balance: ' + balance);
}

var enabled = getElementText('accessibilityId', 'submit', 0, 'enabled');

См. также element.getText

element.exists#

Whether the element is on screen right now. Checks once without waiting. findElement and the selectors (client.label and friends) all return this kind of element object.

typescript

element.exists(): boolean;

Возвращаемое значение

Тип	Описание
`boolean`	True when present, false otherwise.

Пример

javascript

var ok = client.label('OK');
if (ok.exists()) {
  ok.click();
}

См. также findElement、client.label

element.click#

Tap somewhere inside the element — mostly around the middle, clear of the edges, and different every time.

typescript

element.click(): object;

Возвращаемое значение

Тип	Описание
`object`	The raw WDA response; rarely needed.

Исключения

Исключение	Когда возникает
`WDAElementNotFoundError`WDA_ELEMENT_NOT_FOUND	The element is not on screen at the moment of the call. These methods do not wait — to wait, use findElement with a timeout first.

Пример

javascript

var btn = findElement('label', 'OK', 5);
if (btn) {
  btn.click();
}

См. также clickElement

element.getText#

Read the element's text.

typescript

element.getText(): string;

Возвращаемое значение

Тип	Описание
`string`	The element's text.

Исключения

Исключение	Когда возникает
`WDAElementNotFoundError`WDA_ELEMENT_NOT_FOUND	The element is not on screen at the moment of the call. These methods do not wait — to wait, use findElement with a timeout first.

Пример

javascript

var el = findElement('labelContains', 'Balance');
if (el) {
  logi(el.getText());
}

См. также getElementText

element.getRect#

The element's position and size in points, ready to pass to client.click.

typescript

element.getRect(): { x: number; y: number; width: number; height: number };

Возвращаемое значение

Тип	Описание
`{ x, y, width, height }`	The top-left corner and the size, in points.

Исключения

Исключение	Когда возникает
`WDAElementNotFoundError`WDA_ELEMENT_NOT_FOUND	The element is not on screen at the moment of the call. These methods do not wait — to wait, use findElement with a timeout first.

Пример

javascript

var r = client.accessibilityId('avatar').getRect();
client.click(r.x + r.width / 2, r.y + r.height / 2);

См. также client.click