browserstack-node-sdk 1.65.6 → 1.66.0

package/src/detox-driver/a11y.js

@@ -0,0 +1,574 @@
+'use strict';
+
+// App Accessibility scan hook — runs inside the detox jest process (Node realm), NOT the
+// SDK. Same realm rules as tra-capture/session-reporter: node builtins only, and every
+// path is best-effort. A11y is instrumentation; a scan that cannot be armed, routed or
+// answered must leave the customer's test result byte-identical to a run without it.
+//
+// The arming data (scan script, build uuid, tokens, command list) is resolved in the SDK
+// main process and handed over as a JSON file named by BROWSERSTACK_DETOX_A11Y_CONFIG —
+// the detox child inherits the parent env wholesale. A file rather than an env value
+// because the scan script is an opaque server-supplied string of unbounded length.
+//
+// The scan itself is NOT ours to compose: the server ships a `scan` script carrying a
+// printf-style `%s`, and every App-A11y SDK substitutes a JSON args object into it and
+// hands the result to the framework's execute primitive (java `String.format`, csharp
+// `.Replace("%s", …)`, ruby `format_string`). Detox has no execute primitive and no
+// WebDriver session, so the substituted string is relayed over the one device-side
+// channel that exists — the detox WS bridge, whose `CloudPlatform` action the Hub
+// already intercepts. Which frame shape the Hub routes is discovered at runtime by the
+// candidate ladder below, because it is not documented anywhere we can read.
+const fs = require('fs');
+const https = require('https');
+
+const LOG_PREFIX = '[BrowserStack App A11y]';
+
+// Deliberately shorter than CloudPlatformAction's 90s: an unrouted frame must not hold a
+// test for a minute and a half, and a scan the far side never answers has to be written
+// off while the run is still cheap to save.
+const SCAN_TIMEOUT_MS = 30000;
+
+const loggedOnce = new Set();
+let config = null;
+let disabled = '';
+let routedCandidate = null;
+let laddersWalked = false;
+let scansAttempted = 0;
+let scansRouted = 0;
+// The WS client is reachable only through the runtime driver — the expect/matcher surfaces
+// are handed an invocationManager, not a client. The driver registers it on construction,
+// which always precedes any element action.
+let registeredClient = null;
+
+const registerClient = (client) => {
+  registeredClient = client || registeredClient;
+};
+
+const log = (message) => {
+  try {
+    console.log(`${LOG_PREFIX} ${message}`);
+  } catch (err) { /* a log must never break a run */ }
+};
+
+const logOnce = (key, message) => {
+  if (loggedOnce.has(key)) {
+    return;
+  }
+  loggedOnce.add(key);
+  log(message);
+};
+
+const brief = (value, limit = 600) => {
+  try {
+    const text = typeof value === 'string' ? value : JSON.stringify(value);
+    if (text === undefined) {
+      return String(value);
+    }
+
+    return text.length > limit ? `${text.slice(0, limit)}…(${text.length} chars)` : text;
+  } catch (err) {
+    return String(value);
+  }
+};
+
+// Command entries arrive in the shape App Accessibility serves them:
+// {library, method, module, name, class}. `class` and the trailing segment of `module`
+// both name the surface; either is accepted because only one of them is guaranteed by
+// the served payload. `name` is what the scan reports as its `method` — the served set
+// carries BOTH bare and disambiguated names for the same method on different surfaces
+// (`tap` on NativeElement vs `deviceTap` on RuntimeDevice), which is exactly why the
+// match key is (surface, method) and never the name alone.
+const normaliseCommands = (raw) => {
+  const commands = [];
+  if (!Array.isArray(raw)) {
+    return commands;
+  }
+  raw.forEach((entry) => {
+    if (!entry || !entry.method) {
+      return;
+    }
+    const moduleTail = String(entry.module || '').split('/').pop();
+    const surface = String(entry.class || moduleTail || '');
+    if (!surface) {
+      return;
+    }
+    commands.push({
+      surface: surface.toLowerCase(),
+      method: String(entry.method),
+      name: String(entry.name || entry.method),
+      source: entry.bstackLocal === true ? 'sdk-local' : 'served'
+    });
+  });
+
+  return commands;
+};
+
+const loadConfig = () => {
+  if (config !== null) {
+    return config;
+  }
+  config = false;
+  try {
+    const file = process.env.BROWSERSTACK_DETOX_A11Y_CONFIG;
+    if (!file || !fs.existsSync(file)) {
+      return config;
+    }
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!raw || !raw.scanScript) {
+      log('armed but the build carried no scan script — no scans for this run.');
+
+      return config;
+    }
+    const commands = normaliseCommands(raw.commands);
+    if (!commands.length) {
+      log('armed but the build carried no commands to wrap — no scans for this run.');
+
+      return config;
+    }
+    config = {
+      scanScript: String(raw.scanScript),
+      thBuildUuid: String(raw.thBuildUuid || ''),
+      thJwtToken: String(raw.thJwtToken || ''),
+      authHeader: String(raw.authHeader || ''),
+      centralAuthHeader: String(raw.centralAuthHeader || ''),
+      commands,
+      hub: raw.hub && raw.hub.user && raw.hub.key ? raw.hub : null,
+      probe: raw.probe === true
+    };
+    const bySource = commands.reduce((acc, cmd) => {
+      acc[cmd.source] = (acc[cmd.source] || 0) + 1;
+
+      return acc;
+    }, {});
+    log(`armed — ${commands.length} command(s) to wrap (`
+      + `${Object.keys(bySource).map((k) => `${k}: ${bySource[k]}`).join(', ')}`
+      + `), build ${config.thBuildUuid || '<unknown>'}`
+      + `, hub relay ${config.hub ? config.hub.host : 'unavailable (no credentials)'}`
+      + `${config.probe ? ', transport probe ON' : ''}.`);
+  } catch (err) {
+    log(`could not read the arming data (${err && err.message}) — no scans for this run.`);
+    config = false;
+  }
+
+  return config;
+};
+
+const enabled = () => Boolean(loadConfig()) && !disabled;
+
+// Which command name (if any) a call on `surface` maps to. Returns null for anything not
+// in the list — matchers, expectations and every unmapped method stay untouched.
+const commandNameFor = (surface, method) => {
+  const cfg = loadConfig();
+  if (!cfg) {
+    return null;
+  }
+  const key = String(surface || '').toLowerCase();
+  const hit = cfg.commands.find((cmd) => cmd.surface === key && cmd.method === method);
+
+  return hit ? hit : null;
+};
+
+// The scan args, exactly the set the reference SDKs put on the wire for the app branch
+// (javaagent AccessibilityModule.getParamsForScanForCli). `method` is the matched command
+// name; the backend does not validate it against a closed set, so the observed values
+// differ across SDKs (a test-method name from TestNG, command names from WDIO).
+const scanArgs = (cfg, testUuid, commandName) => {
+  const args = {
+    thTestRunUuid: testUuid,
+    thBuildUuid: cfg.thBuildUuid,
+    thJwtToken: cfg.thJwtToken,
+    authHeader: cfg.authHeader,
+    method: commandName,
+    scanTimestamp: String(Date.now())
+  };
+  // The reference SDKs send the CENTRAL SDK JWT here — verified byte-identical to
+  // `thJwtToken` in a working TestNG scan (both the 840-char `iss: www.browserstack.com`
+  // token; `authHeader` is the separate build-scoped a11y token). Omitting it is why a scan
+  // could be accepted (`scan_pending: true`) and still never produce a snapshot: the far
+  // side has the build token but not the central one.
+  const central = cfg.centralAuthHeader || cfg.thJwtToken;
+  if (central) {
+    args.centralAuthHeader = central;
+  }
+
+  return args;
+};
+
+// Candidate frame shapes for relaying the scan, most-likely first. Every one rides the
+// `CloudPlatform` action the Hub already intercepts for launchApp/terminateApp, so an
+// unrecognised shape is answered (or refused) by the Hub rather than forwarded to the
+// stock upstream detox-server, which would reject an unknown action type. The
+// executor-string variants carry the substituted script verbatim; the argument variants
+// carry the parsed action + arguments, which is the shape app-automate's own spec names
+// for a `device.browserstackExecutor({action, arguments})` helper.
+// The Hub dispatches on `method` and answers an unknown one with a well-formed
+// `{success:false, message:'method <x> not supported'}` — cheaply, in well under a second,
+// with no effect on the socket. That makes a name sweep both safe and conclusive, so the
+// probe list is deliberately broad: the entry name is app-automate's to choose and is not
+// documented anywhere readable from here.
+// The scan's other possible carrier, and the only one that needs nothing from the Hub: the
+// `cloudSessionId` the bridge returns on every CloudPlatform response is a real Hub session
+// key — a request against a FINISHED one is answered `{"status":13,"value":{"message":
+// "Session not started or terminated"}}`, i.e. looked up and found absent, not refused as
+// unroutable. If the record is live for the duration of the session, the standard WebDriver
+// execute endpoint reaches the same `jsExecutor` → `appAllyHandler.appAllyScan` path every
+// Appium SDK uses, with the executor string verbatim and no new Hub route.
+//
+// Never rejects; the outcome is the status line and the body, because a refusal's SHAPE is
+// what distinguishes "no such session" from "no such command" from "not allowed here".
+const httpPost = (hub, pathname, body, timeoutMs) => new Promise((resolve) => {
+  let settled = false;
+  const done = (outcome) => {
+    if (!settled) {
+      settled = true;
+      resolve(outcome);
+    }
+  };
+  try {
+    const request = https.request({
+      host: hub.host,
+      port: 443,
+      method: 'POST',
+      path: pathname,
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+        Authorization: `Basic ${Buffer.from(`${hub.user}:${hub.key}`).toString('base64')}`
+      },
+      timeout: timeoutMs
+    }, (response) => {
+      let raw = '';
+      response.setEncoding('utf8');
+      response.on('data', (chunk) => {
+        raw += chunk;
+      });
+      response.on('end', () => done({status: response.statusCode, body: raw}));
+    });
+    request.on('timeout', () => {
+      request.destroy(new Error(`no answer within ${timeoutMs}ms`));
+    });
+    request.on('error', (err) => done({error: (err && err.message) || String(err)}));
+    request.end(body);
+  } catch (err) {
+    done({error: (err && err.message) || String(err)});
+  }
+});
+
+const httpScan = async (cfg, candidate, script, timeoutMs) => {
+  if (!cfg.hub) {
+    return {routed: false, fatal: false, detail: 'no hub credentials in the arming data'};
+  }
+  const sessionId = require('./cloudPlatformAction').getCloudSessionId();
+  if (!sessionId) {
+    return {routed: false, fatal: false, detail: 'no cloud session id seen on the bridge yet'};
+  }
+
+  const result = await httpPost(
+    cfg.hub, `/wd/hub/session/${sessionId}${candidate.suffix}`, JSON.stringify({script, args: []}), timeoutMs
+  );
+  if (result.error) {
+    return {routed: false, fatal: false, detail: `transport error: ${result.error}`};
+  }
+
+  let parsed = null;
+  try {
+    parsed = JSON.parse(result.body);
+  } catch (err) { /* a non-JSON body is reported verbatim below */ }
+  const value = parsed && parsed.value;
+  // W3C reports failure as `value.error`; the JSONWire dialect this Hub also speaks reports
+  // it as a non-zero top-level `status`. A refusal is never a route.
+  const errored = result.status !== 200
+    || (value && typeof value === 'object' && value.error)
+    || (parsed && parsed.status);
+
+  return {
+    routed: !errored,
+    fatal: false,
+    detail: `HTTP ${result.status} session=${sessionId} body=${brief(result.body)}`
+  };
+};
+
+const CANDIDATES = [
+  // First because it is the only shape that could make this SDK-only, and because an HTTP
+  // call is off the WS socket entirely — it cannot disturb an in-flight detox action.
+  {id: 'http:wd-execute-sync', kind: 'http', suffix: '/execute/sync'},
+  {id: 'http:wd-execute', kind: 'http', suffix: '/execute'},
+
+  {id: 'cloudPlatform:appAllyScan', params: (script, args) => ({method: 'appAllyScan', arguments: args})},
+  {id: 'cloudPlatform:browserstackExecutor+action', params: (script, args) => ({method: 'browserstackExecutor', action: 'appAllyScan', arguments: args})},
+  {id: 'cloudPlatform:browserstackExecutor+script', params: (script) => ({method: 'browserstackExecutor', script})},
+  {id: 'cloudPlatform:executeScript', params: (script) => ({method: 'executeScript', script})},
+  {id: 'cloudPlatform:accessibilityScan', params: (script, args) => ({method: 'accessibilityScan', arguments: args})},
+
+  {id: 'cloudPlatform:appAllyScan+script', probeOnly: true, params: (script) => ({method: 'appAllyScan', script})},
+  {id: 'cloudPlatform:appAccessibilityScan', probeOnly: true, params: (script, args) => ({method: 'appAccessibilityScan', arguments: args})},
+  {id: 'cloudPlatform:performScan', probeOnly: true, params: (script, args) => ({method: 'performScan', arguments: args})},
+  {id: 'cloudPlatform:jsExecutor', probeOnly: true, params: (script) => ({method: 'jsExecutor', script})},
+  {id: 'cloudPlatform:customExecutor', probeOnly: true, params: (script) => ({method: 'customExecutor', script})},
+  {id: 'cloudPlatform:execute', probeOnly: true, params: (script) => ({method: 'execute', script})},
+  {id: 'cloudPlatform:sendRequestToPlatform', probeOnly: true, params: (script) => ({method: 'sendRequestToPlatform', script})},
+  {id: 'cloudPlatform:accessibility_info', probeOnly: true, params: (script, args) => ({method: 'accessibility_info', arguments: args})},
+
+  // Deliberately last: a frame whose ACTION TYPE the Hub does not intercept is relayed
+  // generically to the stock upstream detox-server, and an unknown type there answers with
+  // a frame detox's own _onMessage cannot place — which rejects every pending request and
+  // takes the run down. Worth measuring once under the probe flag; never on a customer run.
+  {id: 'action:browserstackExecutor', probeOnly: true, actionType: 'browserstackExecutor', params: (script, args) => ({action: 'appAllyScan', arguments: args})}
+];
+
+// A response frame the Hub never answered leaves its entry in the WS client's in-flight
+// map (detox's InflightRequest.reject does not remove it), and the NEXT send then sees two
+// atomic requests in flight and rejects BOTH — which would fail the customer's next
+// command. Clearing our own entry the way detox's own resetInFlightPromises does, and
+// recording it as aborted so a late answer is logged rather than thrown as an unexpected
+// message, is what keeps a dead scan from taking the run with it.
+const releaseInflight = (client, messageId) => {
+  try {
+    const ws = client && client._asyncWebSocket;
+    if (!ws || messageId === undefined || messageId === null) {
+      return;
+    }
+    if (ws.inFlightPromises && Object.prototype.hasOwnProperty.call(ws.inFlightPromises, messageId)) {
+      delete ws.inFlightPromises[messageId];
+    }
+    if (ws._abortedMessageIds && typeof ws._abortedMessageIds.add === 'function') {
+      ws._abortedMessageIds.add(+messageId);
+    }
+  } catch (err) { /* best-effort */ }
+};
+
+// Outcome shape: {routed:boolean, fatal:boolean, detail:string}. `fatal` means the socket
+// is no longer safe to send scans on, so the ladder stops and scanning is disabled for the
+// rest of the session — one bad frame, never a cascade.
+const attempt = async (client, actions, candidate, script, args) => {
+  if (candidate.kind === 'http') {
+    return httpScan(loadConfig(), candidate, script, SCAN_TIMEOUT_MS);
+  }
+  // Construction is INSIDE the try on purpose: `candidate.params()` and the Action constructor
+  // are the caller's own code running inside a real device action's promise chain, so a throw
+  // here would fail the customer's command — the exact outcome this file exists to prevent.
+  let action;
+  try {
+    action = new actions.ScanRelayAction(
+      candidate.params(script, args), SCAN_TIMEOUT_MS, candidate.actionType
+    );
+    const response = await client.sendAction(action);
+    const type = response && response.type;
+    const envelopeAccepted = type === 'CloudPlatform' || type === 'browserstackExecutor';
+    // The Hub answers an unmapped method with a well-formed frame of the RIGHT type and
+    // `success: false` ("method <x> not supported"). Reading the type alone would score
+    // that as a working transport and stop the search at the first refusal.
+    const inner = (response && response.response) || {};
+    const refused = inner.success === false;
+
+    if (envelopeAccepted && !refused) {
+      return {routed: true, fatal: false, detail: `type=${type} response=${brief(response)}`};
+    }
+    if (envelopeAccepted) {
+      return {routed: false, fatal: false, detail: `Hub refused: ${inner.message || brief(response)}`};
+    }
+
+    return {routed: false, fatal: false, detail: `unexpected response type=${type} response=${brief(response)}`};
+  } catch (err) {
+    const message = String((err && err.message) || err);
+    const timedOut = message.includes('has not received a response within');
+    // `action` is undefined if construction itself threw — there is no in-flight entry to
+    // release in that case, and dereferencing it here would turn a handled failure into an
+    // unhandled one.
+    if (timedOut && action) {
+      releaseInflight(client, action.messageId);
+    }
+
+    return {routed: false, fatal: timedOut, detail: `${timedOut ? 'timeout' : 'error'}: ${brief(message)}`};
+  }
+};
+
+// Fire one scan for a completed command. Awaited by the caller on purpose: detox rejects
+// every in-flight atomic action the moment a second one is sent, so a fire-and-forget scan
+// would fail the customer's next command. Never throws.
+const scan = async (client, commandName, testUuid) => {
+  const cfg = loadConfig();
+  if (!cfg || disabled || !client) {
+    return;
+  }
+
+  // A scan with no test to attach to is an orphan the dashboard cannot place. Hook-scope
+  // uuids are not published, so a beforeAll/beforeEach action is suppressed rather than
+  // reported against an empty uuid.
+  if (!testUuid) {
+    logOnce('no-uuid', `no scan for "${commandName}" and any other command outside a test body`
+      + ' — a scan can only be attributed to a running test.');
+
+    return;
+  }
+
+  let args;
+  let script;
+  try {
+    // Built once: the script-carrying and argument-carrying relay shapes must describe the
+    // same scan, and a second scanArgs() call would give them different scanTimestamps.
+    args = scanArgs(cfg, testUuid, commandName);
+    // Function replacement: `$&`-style sequences inside a JWT would otherwise be read as
+    // replacement patterns.
+    const json = JSON.stringify(args);
+    script = cfg.scanScript.includes('%s') ? cfg.scanScript.replace('%s', () => json) : cfg.scanScript;
+  } catch (err) {
+    log(`could not build the scan payload for "${commandName}" (${err && err.message}); skipping.`);
+
+    return;
+  }
+
+  const actions = require('./cloudPlatformAction');
+  scansAttempted++;
+
+  // Once a candidate has routed, only that one is used. The full ladder is walked exactly
+  // once — a detox cloud session allocates rarely enough that one-shape-per-run would cost
+  // days, so the first scan of a probe run measures every shape and later scans use the
+  // winner. Outside probe mode the ladder stops at the first shape that answers.
+  const sweeping = cfg.probe && !laddersWalked;
+  const ladder = (routedCandidate && !sweeping)
+    ? [routedCandidate]
+    : CANDIDATES.filter((candidate) => sweeping || !candidate.probeOnly);
+  let routed = false;
+
+  for (const candidate of ladder) {
+    const outcome = await attempt(client, actions, candidate, script, args);
+    const line = `scan for "${commandName}" via ${candidate.id} → ${outcome.routed ? 'ROUTED' : 'no route'} — ${outcome.detail}`;
+    if (outcome.routed || sweeping) {
+      log(line);
+    } else {
+      logOnce(`nr:${candidate.id}`, line);
+    }
+
+    if (outcome.routed) {
+      routed = true;
+      if (!routedCandidate) {
+        routedCandidate = candidate;
+        log(`transport resolved: ${candidate.id}`);
+      }
+      if (!sweeping) {
+        break;
+      }
+    }
+
+    if (outcome.fatal) {
+      disabled = `transport timed out on ${candidate.id}`;
+      log(`scans DISABLED for the rest of this session (${disabled}). The test run is unaffected.`);
+      break;
+    }
+  }
+
+  if (sweeping) {
+    laddersWalked = true;
+  }
+
+  if (routed) {
+    scansRouted++;
+
+    return;
+  }
+
+  // A refused method is a static property of the Hub's route table, not a transient
+  // failure — retrying it on every subsequent command would add a round trip per command
+  // and change nothing. Stop after one exhausted pass, and say plainly that this run
+  // produced NO scans (as distinct from scans that were attempted and failed), because
+  // that distinction is the whole difference for whoever picks up the support ticket.
+  if (!disabled) {
+    disabled = 'the Hub has no route for a detox App Accessibility scan';
+    log(`NO SCANS for this run: ${ladder.length} relay shape(s) tried and every one was refused`
+      + ` by the Hub (${ladder.map((c) => c.id).join(', ')}). The App Accessibility build was created`
+      + ' and armed correctly; the scan relay is not routed. Test results are unaffected.');
+  }
+};
+
+// Recursive, path-accumulating proxy over one of detox's element objects. Applied ONLY
+// when a11y is armed, so the disabled path returns detox's own objects untouched.
+//
+// Two source hazards it exists to absorb: `NativeElement.atIndex()` and
+// `NativeWaitForElement`'s `get not` both `return this` — the raw target — so a chained
+// call would escape the wrapper unless a result identical to the target is re-wrapped.
+// Methods are applied to the TARGET, not the proxy, so detox's own internal `this.…`
+// calls never re-enter the hook and no action is counted twice.
+const wrap = (target, surface) => {
+  if (!target || (typeof target !== 'object' && typeof target !== 'function')) {
+    return target;
+  }
+
+  const proxy = new Proxy(target, {
+    get(obj, prop) {
+      const value = obj[prop];
+      if (typeof value !== 'function') {
+        return value;
+      }
+
+      const command = commandNameFor(surface, String(prop));
+
+      return function wrapped(...args) {
+        const result = value.apply(obj, args);
+
+        // Synchronous chaining helper (atIndex, WebViewElement.element): re-wrap so the
+        // chain stays instrumented all the way to the leaf action.
+        if (!(result && typeof result.then === 'function')) {
+          return result === obj ? proxy : wrapChainResult(result);
+        }
+
+        return result.then(async (resolved) => {
+          if (command) {
+            // Post-settle by construction: a native invocation resolves only after
+            // Espresso's idling resources are idle, so the screen the scan captures is the
+            // one the command produced. Web-view actions are detox's own documented
+            // exception — it adds a hardcoded 500ms and guarantees nothing.
+            await scan(registeredClient, command.name, currentTestUuid());
+          }
+
+          return resolved === obj ? proxy : wrapChainResult(resolved);
+        });
+      };
+    }
+  });
+
+  return proxy;
+};
+
+// A method that returns a *different* element object (WebViewElement.element() →
+// WebElement) has to hand back a proxy over the new surface, or the leaf action is never
+// seen. Anything that is not one of the wrapped surfaces is returned untouched.
+const WRAPPED_SURFACES = ['NativeElement', 'WebElement', 'WebViewElement'];
+
+const wrapChainResult = (result) => {
+  try {
+    if (!result || typeof result !== 'object') {
+      return result;
+    }
+    const name = result.constructor && result.constructor.name;
+    if (WRAPPED_SURFACES.includes(name)) {
+      return wrap(result, name);
+    }
+  } catch (err) { /* best-effort */ }
+
+  return result;
+};
+
+// The owning test's uuid, published per `it()` on the Node-realm global by the SDK's jest
+// environment (the same channel __BSTACK_DETOX_SPEC__ uses) and cleared at test_done —
+// so its absence is precisely the "outside a test body" case R50 requires be suppressed.
+const currentTestUuid = () => {
+  try {
+    return global.__BSTACK_DETOX_TEST_UUID__ || '';
+  } catch (err) {
+    return '';
+  }
+};
+
+const summary = () => ({scansAttempted, scansRouted, disabled, transport: routedCandidate && routedCandidate.id});
+
+module.exports = {
+  enabled,
+  commandNameFor,
+  scan,
+  wrap,
+  registerClient,
+  currentTestUuid,
+  summary,
+  SCAN_TIMEOUT_MS
+};

package/src/detox-driver/allocationDriver.js

@@ -0,0 +1,26 @@
+'use strict';
+
+// Vanilla Detox's external-module contract (devices/allocation/factories/external.js)
+// requires a `DeviceAllocationDriverClass`. BrowserStack cloud sessions don't allocate
+// a local device — the real "allocation" happens server-side when the runtime driver's
+// launchApp opens the cloud WebSocket session — so this driver is a no-op shell that
+// satisfies the AllocationDriverBase interface (init/allocate/postAllocate/free).
+class CloudAllocationDriver {
+  async init() {}
+
+  // Cookie shape must match detox's AndroidDeviceCookie ({id, adbName}) since
+  // RuntimeDevice/DeviceAllocator key off cookie.id — nulls are fine, there is no
+  // local adb device to name.
+  async allocate(_deviceConfig) {
+    return {id: null, adbName: null};
+  }
+
+  async postAllocate(deviceCookie) {
+    return deviceCookie;
+  }
+
+  // No real device to release.
+  async free(_cookie, _options) {}
+}
+
+module.exports = CloudAllocationDriver;