Référence de l'API de script

Script minimal exécutable

A script must return true to count as a success; returning false or nothing is recorded as a failure. The runtime library is prepended to every script, so client, clickElement, logi, sleep and the rest are available directly.

function main() {
  // Open Settings and go into General
  client.session('com.apple.Preferences');
  sleep(2);

  if (!clickElement('label', 'General', 5)) {
    loge('General not found');
    return false;
  }

  logi('opened General');
  return true;
}

main();

Conventions générales

Arguments go in order

Every function takes its arguments in order — no {} options objects. The common ones come first and trailing ones can be left out; write null to keep the default for one in the middle, as in findImage('a.png', 0, null, 0.85). Passing an old-style {} throws INVALID_ARGUMENT, and the message contains the corrected line.

Locators say how to look

The first two arguments of the element functions are how to look and what to look for: clickElement('label', 'Log in'). There are exactly 7 strategies, named like the selectors: label (exact text), labelContains (text contains), accessibilityId (the element's name — the most stable), xpath, predicate, classChain and className.

Time is always in seconds

Every duration is in seconds and may be fractional. Lookup and read functions look once by default; tap functions wait up to 10 seconds. Values above 600 are rejected as milliseconds passed by mistake. The only exceptions are setTimeout and setInterval, which keep JavaScript's millisecond convention.

Coordinates and areas

Coordinates are points, not pixels: the x and y you get back can go straight into client.click, and the same script works on 2x and 3x screens. When x and y both fall between 0 and 1 they are screen ratios. Areas are written [x, y, w, h]: all four between 0 and 1 means screen ratios (portable across resolutions), otherwise points.

Several checks on one frame

Colour, image and text lookups take their own screenshot every time and release it afterwards. To check several things on the same frame, call keepScreen() first and releaseScreen() when done — or use withScreen(function () { … }), which releases the frame for you.

Stopping is cooperative

Pressing Stop in the console only sets a flag; it never interrupts the script by force. Long loops must check shouldStop() and exit when it returns true; sleep and the waits inside lookup functions return immediately after a stop.

Branch on error codes

Every error carries a stable code field. Branch on the code rather than the message text, which is written for people and changes between versions. Lookup functions return null or false on a miss instead of throwing; exceptions are reserved for real errors such as wrong arguments or device and WDA failures.