Utilities

Logging, waiting, time, random numbers, Base64 and HTTP requests. All three log levels are uploaded to the task log and show up in the console in real time.

At a glance

·Three log levels — logd / logi / loge; the console shows debug in grey and errors in red
·randomInt / randomFloat / randomChoice add randomness to waits, taps and wording
·httpGet / httpPost never throw on failure and always return { ok, status, text, json, headers, error }

logd#

A debug log line: the details you look at while troubleshooting. It is uploaded too and shows in grey in the log panel.

typescript

logd(message: any): void;

Parameters

Name	Type	Required	Default	Description
`message`	`any`	Yes	—	What to log. Objects are serialised to JSON; anything else is converted to a string.

Notes

Keep it out of tight loops: the server keeps only the most recent part of each task's log, and noise pushes out what matters.

Example

javascript

logd(client.windowSize());

logi#

An info log line: which step the script reached and what it got.

typescript

logi(message: any): void;

Parameters

Name	Type	Required	Default	Description
`message`	`any`	Yes	—	What to log. Objects are serialised to JSON; anything else is converted to a string.

Example

javascript

logi('step 1 done');

loge#

An error log line for failures. It is highlighted in red in the log panel.

typescript

loge(message: any): void;

Parameters

Name	Type	Required	Default	Description
`message`	`any`	Yes	—	What to log. Objects are serialised to JSON; anything else is converted to a string.

Example

javascript

loge('the login button never appeared');

setClickLog#

Turn click logging on or off. clickElement / clickImage / clickText record taps and misses in the task log by default; turn it off in busy loops so the log stays readable.

typescript

setClickLog(on: boolean): boolean;

Parameters

Name	Type	Required	Default	Description
`on`	`boolean`	Yes	—	true to log, false to stay quiet.

Returns

Type	Description
`boolean`	The previous setting.

Notes

Only these three functions are affected. Coordinate taps such as client.click never log.

Example

javascript

setClickLog(false);
for (var i = 0; i < 50; i++) {
  clickElement('label', 'Next', 1);
}
setClickLog(true);

See also clickElement、clickImage、clickText

sleep#

Wait for the given number of seconds. Returns immediately when the task is stopped.

typescript

sleep(seconds: number): void;

Parameters

Name	Type	Required	Default	Description
`seconds`	`number`	Yes	—	How many seconds to wait; fractions are allowed.

Example

javascript

sleep(1.5);

getNowTimestamp#

The current Unix timestamp in seconds (an integer).

typescript

getNowTimestamp(): number;

Returns

Type	Description
`number`	The number of seconds since 1970-01-01 00:00:00 UTC.

Notes

To measure elapsed time, store the timestamp at the start and subtract it later to get the seconds that passed. For milliseconds use Date.now().

Example

javascript

var start = getNowTimestamp();
sleep(2);
logi(getNowTimestamp() - start);

getNowTime#

The current time as 2026-10-01 14:05:09, in the device's local time zone.

typescript

getNowTime(): string;

Returns

Type	Description
`string`	"YYYY-MM-DD HH:MM:SS", with month, day, hour, minute and second zero-padded to two digits.

Notes

For the date only take the first 10 characters: getNowTime().slice(0, 10); for hours and minutes only: getNowTime().slice(11, 16).

Example

javascript

logi('started at ' + getNowTime());

randomInt#

A random integer with both ends included: randomInt(1, 6) is a die roll.

typescript

randomInt(min: number, max: number): number;

Parameters

Name	Type	Required	Default	Description
`min`	`number`	Yes	—	The lower bound (inclusive).
`max`	`number`	Yes	—	The upper bound (inclusive).

Returns

Type	Description
`number`	An integer in [min, max]. Swapped bounds are handled.

Example

javascript

var n = randomInt(1, 6);

randomFloat#

A random decimal with both ends included, kept to 1 decimal place by default: randomFloat(1.5, 3) may give 1.5, 2.3 or 3. For example, pause for a random while between rounds: sleep(randomFloat(1.5, 3)).

typescript

randomFloat(min: number, max: number, digits?: number): number;

Parameters

Name	Type	Required	Default	Description
`min`	`number`	Yes	—	The lower bound (inclusive).
`max`	`number`	Yes	—	The upper bound (inclusive).
`digits`	`number`	No	`1`	How many decimal places to keep; an integer from 0 to 10.

Returns

Type	Description
`number`	A decimal in [min, max] with digits decimal places. Swapped bounds are handled.

Throws

Error	Raised when
`WDAError`INVALID_ARGUMENT	digits is not an integer from 0 to 10.

Notes

When the range is too narrow to hold two different values at that precision, more places are kept automatically: at 1 decimal place randomFloat(0.45, 0.55) could only ever be 0.5, so it returns two-decimal values such as 0.47 or 0.52. The result always stays inside [min, max].
For values that need to be fine-grained, such as screen-ratio coordinates, pass the precision: client.click(randomFloat(0.3, 0.7, 3), randomFloat(0.4, 0.6, 3)). At 1 decimal place the tap could only land on 0.3, 0.4 and so on.

Example

javascript

sleep(randomFloat(1.5, 3));
var x = randomFloat(0.2, 0.8, 3);

See also randomInt、randomChoice、sleep

randomChoice#

Pick one item from an array at random, each with an equal chance.

typescript

randomChoice<T>(list: T[]): T | null;

Parameters

Name	Type	Required	Default	Description
`list`	`T[]`	Yes	—	The candidates.

Returns

Type	Description
`T \| null`	The chosen item, or null for an empty array.

Throws

Error	Raised when
`WDAError`INVALID_ARGUMENT	The argument is not an array — for example, the candidates were passed as separate arguments.

Example

javascript

var greeting = randomChoice(['Hello', 'Good morning', 'Hi']);
logi(greeting);

base64Encode#

Encode text as Base64 using UTF-8, so non-ASCII text survives.

typescript

base64Encode(text: string): string;

Parameters

Name	Type	Required	Default	Description
`text`	`string`	Yes	—	The text.

Returns

Type	Description
`string`	The Base64 string.

Example

javascript

var b64 = base64Encode('hello');

base64Decode#

Decode Base64 back to text (UTF-8).

typescript

base64Decode(base64: string): string;

Parameters

Name	Type	Required	Default	Description
`base64`	`string`	Yes	—	The Base64 string.

Returns

Type	Description
`string`	The decoded text.

Example

javascript

var text = base64Decode('aGVsbG8=');

httpGet#

Send a GET request.

typescript

httpGet(url: string, timeoutSec?: number, headers?: Record<string, string>): HttpResult;

type HttpResult = {
  ok: boolean;
  status: number;
  text: string;
  json: any;
  headers: Record<string, string>;
  error: string;
};

Parameters

Name	Type	Required	Default	Description
`url`	`string`	Yes	—	The full address, starting with http:// or https://. Put query parameters in the address; non-ASCII text and spaces are encoded for you.
`timeoutSec`	`number`	No	`15`	The longest wait, in seconds.
`headers`	`Record<string, string>`	No	—	Request headers, for example { Authorization: 'Bearer xxx' }.

Returns

Type	Description
`HttpResult`	{ ok, status, text, json, headers, error }. ok means a 2xx status; status 0 means no response arrived (no network, timeout, task stopped) and error says why; json holds the parsed body when the response is JSON and null otherwise; header names are lowercase. Failures do not throw — check ok.

Throws

Error	Raised when
`WDAError`INVALID_ARGUMENT	The address does not start with http(s), the wait is not a number or exceeds 600, or the headers are not an object.

Example

javascript

var r = httpGet('https://api.example.com/items?page=1');
if (r.ok) {
  logi(r.json.items.length);
} else {
  loge(r.status + ' ' + r.error);
}

httpPost#

Send a POST request. A string body is sent as-is ('a=1&b=2' goes out as a form, JSON text as JSON); an object is sent as JSON.

typescript

httpPost(url: string, body?: string | object, timeoutSec?: number, headers?: Record<string, string>): HttpResult;

Parameters

Name	Type	Required	Default	Description
`url`	`string`	Yes	—	The full address, starting with http:// or https://. Put query parameters in the address; non-ASCII text and spaces are encoded for you.
`body`	`string \| object`	No	—	The request body. A Content-Type header you set yourself is never overridden.
`timeoutSec`	`number`	No	`15`	The longest wait, in seconds.
`headers`	`Record<string, string>`	No	—	Request headers, for example { Authorization: 'Bearer xxx' }.

Returns

Type	Description
`HttpResult`	{ ok, status, text, json, headers, error }. ok means a 2xx status; status 0 means no response arrived (no network, timeout, task stopped) and error says why; json holds the parsed body when the response is JSON and null otherwise; header names are lowercase. Failures do not throw — check ok.

Throws

Error	Raised when
`WDAError`INVALID_ARGUMENT	The address does not start with http(s), the wait is not a number or exceeds 600, or the headers are not an object.

Notes

Requests go to whatever address the script names; the script's author is responsible for where that data goes.

Example

javascript

var r = httpPost('https://example.com/report', 'device=' + getDeviceId() + '&status=ok');
if (!r.ok) {
  loge(r.status + ' ' + r.error);
}