Globals

Objects and functions injected before a script runs: the device client, script parameters, task and device IDs, the stop signal, and the shared error codes.

client#

The device client, injected automatically. Gestures, apps, screen access and selectors are all its methods — client.click, client.session, client.label and so on.

typescript

declare const client: WDA.Client;

반환값

타입	설명
`WDA.Client`	A client connected to the device's WebDriverAgent; it attaches to WDA's current session on its own.

예제

javascript

client.session('com.apple.Preferences');
var size = client.windowSize();

관련 항목 client.session、client.click

params#

The script's parameters, injected automatically. Parameters added to a script in the console's Script Manager are read directly as params.name — no call needed.

typescript

declare const params: Record<string, string | number | boolean>;

반환값

타입	설명
`Record<string, string \| number \| boolean>`	An object mapping parameter names to values. Each value follows the parameter's type: number parameters arrive as numbers, boolean parameters as true / false, string parameters as strings.

주의사항

A parameter that does not exist reads as undefined, so a default is easy to add: var rounds = params.rounds || 10.
A run in the Code Playground uses the saved parameters of the script that is currently open; code that has not been saved as a script has no parameters.
In a script someone shared with you, the values are the ones you filled in, not the owner's.

예제

javascript

var keyword = params.keyword;
var rounds = params.rounds || 10;
logi('search ' + keyword + ', ' + rounds + ' rounds');

getScriptConfig#

Read the extra configuration filled in for this script on the parameter page.

typescript

getScriptConfig(scriptName: string): unknown | null;

매개변수

이름	타입	필수	기본값	설명
`scriptName`	`string`	예	—	The script name.

반환값

타입	설명
`unknown \| null`	The extra configuration, or null on failure (an error is logged).

예제

javascript

var cfg = getScriptConfig('daily-like');

getTaskId#

The current task's ID; getScriptId() returns the current script's ID.

typescript

getTaskId(): string;
getScriptId(): string;

반환값

타입	설명
`string`	The task ID / script ID.

주의사항

They are injected only when the script runs as a task. When unsure, check typeof getTaskId === 'function' first.

예제

javascript

logi('task=' + getTaskId());

getDeviceId#

This device's ID in the system.

typescript

getDeviceId(): string;

반환값

타입	설명
`string`	The device ID.

예제

javascript

logi('device=' + getDeviceId());

shouldStop#

Whether the task has been asked to stop. Long loops must check it; otherwise pressing Stop in the console only takes effect when the script finishes on its own.

typescript

shouldStop(): boolean;

반환값

타입	설명
`boolean`	True once a stop has been requested.

주의사항

Stopping is cooperative: it only sets a flag and never interrupts the script by force. sleep and the waits inside lookup functions return immediately once a stop is requested.

예제

javascript

for (var i = 0; i < 100; i++) {
  if (shouldStop()) {
    return false;
  }
  client.swipeUp();
  sleep(randomFloat(1, 3));
}

WDA.ErrorCode#

Every error carries a stable code in e.code. Branch on the code, never on the message text — the text is written for people and its wording changes. The full list is in the table at the end of this page.

typescript

declare const WDA: {
  ErrorCode: {
    ELEMENT_NOT_FOUND: "WDA_ELEMENT_NOT_FOUND";
    INVALID_ARGUMENT: "INVALID_ARGUMENT";
    FEATURE_UNAVAILABLE: "FEATURE_UNAVAILABLE";
    // …见下表 / see the table below
  };
};

주의사항

Lookup functions (findElement, findImage, findText and so on) return null or false on a miss and do not throw; exceptions are reserved for real errors such as wrong arguments or device and WDA failures.

예제

javascript

try {
  client.label('OK').click();
} catch (e) {
  if (e.code === WDA.ErrorCode.ELEMENT_NOT_FOUND) {
    loge('OK button not found');
  } else {
    throw e;
  }
}

Error codes

Code (e.code)	Constant	When it happens
INVALID_ARGUMENT	WDA.ErrorCode.INVALID_ARGUMENT	An argument is wrong: a bad locator, a wait that is not a number or was given in milliseconds, a malformed region, an old-style {} and so on. It is the script's own mistake, and the message shows the corrected call.
WDA_ELEMENT_NOT_FOUND	WDA.ErrorCode.ELEMENT_NOT_FOUND	An element object's click / getText / getRect was called while the element was not on screen.
FEATURE_UNAVAILABLE	WDA.ErrorCode.FEATURE_UNAVAILABLE	The app on the device is too old for this feature (colour and image matching, text recognition, photos); update the app.
WDA_UNKNOWN	WDA.ErrorCode.UNKNOWN	An unclassified WDA error.
WDA_BAD_GATEWAY	WDA.ErrorCode.BAD_GATEWAY	WDA returned 502, usually because the WebDriverAgent process died; retry once it is back up.
WDA_EMPTY_RESPONSE	WDA.ErrorCode.EMPTY_RESPONSE	WDA returned an empty response.
WDA_REQUEST_FAILED	WDA.ErrorCode.REQUEST_FAILED	WDA rejected the request, for example because a value was not accepted or the operation is unsupported.
WDA_INVALID_SESSION	WDA.ErrorCode.INVALID_SESSION	The session is gone (the app was closed or WDA restarted). The client reattaches to the current session on its own.
WDA_APP_CRASHED	WDA.ErrorCode.APP_CRASHED	The app under automation has probably crashed.
WDA_KEYBOARD_NOT_PRESENT	WDA.ErrorCode.KEYBOARD_NOT_PRESENT	An operation needed the keyboard but it was not up.
WDA_INVALID_ELEMENT_STATE	WDA.ErrorCode.INVALID_ELEMENT_STATE	The element's current state does not allow the operation, for example it is disabled or not editable.
API_FAILED	WDA.ErrorCode.API_FAILED	A platform API call failed, for example while reading script parameters or resolving template names.
IMAGE_FAILED	WDA.ErrorCode.IMAGE_FAILED	A colour or image operation failed (unclassified).
IMG_BAD_HANDLE	WDA.ErrorCode.IMAGE_BAD_HANDLE	The screenshot was already released (after releaseScreen) or the handle is invalid.
IMG_TOO_MANY_HANDLES	WDA.ErrorCode.IMAGE_TOO_MANY_HANDLES	Too many screenshots are held at once (the limit is 4). Release a frozen screen with releaseScreen when done.
IMG_CAPTURE_FAILED	WDA.ErrorCode.IMAGE_CAPTURE_FAILED	Taking the screenshot failed, usually because WDA is not running.
TPL_NOT_FOUND	WDA.ErrorCode.TEMPLATE_NOT_FOUND	The template image cannot be obtained: this script has no uploaded image with that file name, or the download failed.
TPL_TOO_LARGE	WDA.ErrorCode.TEMPLATE_TOO_LARGE	The template is larger than the search area — it was probably captured at another resolution.
OCR_LANG_UNSUPPORTED	WDA.ErrorCode.OCR_LANG_UNSUPPORTED	This device's Vision framework does not support the requested recognition language.
OCR_FAILED	WDA.ErrorCode.OCR_FAILED	Text recognition failed.