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.

نظرة عامة

·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;

المعاملات

الاسم	النوع	مطلوب	القيمة الافتراضية	الوصف
`message`	`any`	نعم	—	What to log. Objects are serialised to JSON; anything else is converted to a string.

ملاحظات

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.

مثال

javascript

logd(client.windowSize());

انظر أيضًا logi、loge

logi#

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

typescript

logi(message: any): void;

المعاملات

الاسم	النوع	مطلوب	القيمة الافتراضية	الوصف
`message`	`any`	نعم	—	What to log. Objects are serialised to JSON; anything else is converted to a string.

مثال

javascript

logi('step 1 done');

انظر أيضًا logd、loge

loge#

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

typescript

loge(message: any): void;

المعاملات

الاسم	النوع	مطلوب	القيمة الافتراضية	الوصف
`message`	`any`	نعم	—	What to log. Objects are serialised to JSON; anything else is converted to a string.

مثال

javascript

loge('the login button never appeared');

انظر أيضًا logi

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;

المعاملات

الاسم	النوع	مطلوب	القيمة الافتراضية	الوصف
`on`	`boolean`	نعم	—	true to log, false to stay quiet.

القيمة المُعادة

النوع	الوصف
`boolean`	The previous setting.

ملاحظات

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

مثال

javascript

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

انظر أيضًا clickElement、clickImage、clickText

sleep#

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

typescript

sleep(seconds: number): void;

المعاملات

الاسم	النوع	مطلوب	القيمة الافتراضية	الوصف
`seconds`	`number`	نعم	—	How many seconds to wait; fractions are allowed.

مثال

javascript

sleep(1.5);

انظر أيضًا randomFloat、shouldStop

getNowTimestamp#

The current Unix timestamp in seconds (an integer).

typescript

getNowTimestamp(): number;

القيمة المُعادة

النوع	الوصف
`number`	The number of seconds since 1970-01-01 00:00:00 UTC.

ملاحظات

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().

مثال

javascript

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

انظر أيضًا getNowTime、sleep

getNowTime#

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

typescript

getNowTime(): string;

القيمة المُعادة

النوع	الوصف
`string`	"YYYY-MM-DD HH:MM:SS", with month, day, hour, minute and second zero-padded to two digits.

ملاحظات

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

مثال

javascript

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

انظر أيضًا getNowTimestamp

randomInt#

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

typescript

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

المعاملات

الاسم	النوع	مطلوب	القيمة الافتراضية	الوصف
`min`	`number`	نعم	—	The lower bound (inclusive).
`max`	`number`	نعم	—	The upper bound (inclusive).

القيمة المُعادة

النوع	الوصف
`number`	An integer in [min, max]. Swapped bounds are handled.

مثال

javascript

var n = randomInt(1, 6);

انظر أيضًا randomFloat、randomChoice

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;

المعاملات

الاسم	النوع	مطلوب	القيمة الافتراضية	الوصف
`min`	`number`	نعم	—	The lower bound (inclusive).
`max`	`number`	نعم	—	The upper bound (inclusive).
`digits`	`number`	لا	`1`	How many decimal places to keep; an integer from 0 to 10.

القيمة المُعادة

النوع	الوصف
`number`	A decimal in [min, max] with digits decimal places. Swapped bounds are handled.

الاستثناءات

الاستثناء	متى يحدث
`WDAError`INVALID_ARGUMENT	digits is not an integer from 0 to 10.

ملاحظات

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.

مثال

javascript

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

انظر أيضًا randomInt、randomChoice、sleep

randomChoice#

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

typescript

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

المعاملات

الاسم	النوع	مطلوب	القيمة الافتراضية	الوصف
`list`	`T[]`	نعم	—	The candidates.

القيمة المُعادة

النوع	الوصف
`T \| null`	The chosen item, or null for an empty array.

الاستثناءات

الاستثناء	متى يحدث
`WDAError`INVALID_ARGUMENT	The argument is not an array — for example, the candidates were passed as separate arguments.

مثال

javascript

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

انظر أيضًا randomInt、randomFloat

base64Encode#

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

typescript

base64Encode(text: string): string;

المعاملات

الاسم	النوع	مطلوب	القيمة الافتراضية	الوصف
`text`	`string`	نعم	—	The text.

القيمة المُعادة

النوع	الوصف
`string`	The Base64 string.

مثال

javascript

var b64 = base64Encode('hello');

انظر أيضًا base64Decode

base64Decode#

Decode Base64 back to text (UTF-8).

typescript

base64Decode(base64: string): string;

المعاملات

الاسم	النوع	مطلوب	القيمة الافتراضية	الوصف
`base64`	`string`	نعم	—	The Base64 string.

القيمة المُعادة

النوع	الوصف
`string`	The decoded text.

مثال

javascript

var text = base64Decode('aGVsbG8=');

انظر أيضًا base64Encode

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;
};

المعاملات

الاسم	النوع	مطلوب	القيمة الافتراضية	الوصف
`url`	`string`	نعم	—	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`	لا	`15`	The longest wait, in seconds.
`headers`	`Record<string, string>`	لا	—	Request headers, for example { Authorization: 'Bearer xxx' }.

القيمة المُعادة

النوع	الوصف
`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.

الاستثناءات

الاستثناء	متى يحدث
`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.

مثال

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

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;

المعاملات

الاسم	النوع	مطلوب	القيمة الافتراضية	الوصف
`url`	`string`	نعم	—	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`	لا	—	The request body. A Content-Type header you set yourself is never overridden.
`timeoutSec`	`number`	لا	`15`	The longest wait, in seconds.
`headers`	`Record<string, string>`	لا	—	Request headers, for example { Authorization: 'Bearer xxx' }.

القيمة المُعادة

النوع	الوصف
`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.

الاستثناءات

الاستثناء	متى يحدث
`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.

ملاحظات

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

مثال

javascript

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

انظر أيضًا httpGet