browserstack-node-sdk 1.65.6 → 1.66.0

package/src/detox-driver/cloudPlatformAction.js

@@ -0,0 +1,111 @@
+'use strict';
+
+// The BrowserStack cloud instrumentation bridge is driven by a `CloudPlatform`
+// action. We ship vanilla, unpatched Detox, so this is built on detox's exported
+// `Action` base and sent through the public `client.sendAction(action)` — no core
+// patch. Params are FLAT ({method, ...extra}, e.g. {method:'launchApp', launchArgs:{}}),
+// matching the bridge's expected shape.
+//
+// detox is the CUSTOMER's dependency, not the SDK's — resolve it from process.cwd()
+// (the SDK package has no detox installed), the same way the driver module is loaded.
+const fs = require('fs');
+const path = require('path');
+
+const detoxRoot = path.dirname(require.resolve('detox/package.json', {paths: [process.cwd()]}));
+const {Action} = require(path.join(detoxRoot, 'src/client/actions/actions'));
+
+// Current jest spec-file path, read from the worker's jest state. Detox opens one
+// cloud session per spec file, so this ties the session id to its spec — letting the
+// SDK correlate each session with the spec's verdict (from the jest reporter) and mark
+// it individually. Empty string when unavailable (falls back to the run-level verdict).
+function currentTestPath() {
+  try {
+    // Preferred: the spec path stashed by the spec-capture setupFilesAfterEnv module
+    // (jest's expect.getState().testPath is populated there but not in this driver's
+    // load context).
+    if (global.__BSTACK_DETOX_SPEC__) {
+      return global.__BSTACK_DETOX_SPEC__;
+    }
+    const state = global.expect && global.expect.getState && global.expect.getState();
+
+    return (state && state.testPath) || '';
+  } catch (err) {
+    return '';
+  }
+}
+
+// Last id seen on the socket, kept in memory for callers that need to address the LIVE
+// session (the a11y scan relay) rather than reconcile it after the run.
+let latestCloudSessionId = '';
+
+// The BrowserStack session id ("cloudSessionId") rides every CloudPlatform response.
+// Persist `<id>\t<specPath>` to the file the SDK's detox command points us at, so the
+// main process can mark each session (status + name) on the dashboard after the run.
+// Best-effort: this must never break the test run.
+function recordCloudSessionId(response) {
+  try {
+    const id = response && response.cloudSessionId;
+    if (!id) {
+      return;
+    }
+    latestCloudSessionId = id;
+    const file = process.env.BROWSERSTACK_DETOX_SESSION_IDS_FILE;
+    if (file) {
+      fs.appendFileSync(file, id + '\t' + currentTestPath() + '\n');
+    }
+  } catch (err) { /* best-effort session capture */ }
+}
+
+const getCloudSessionId = () => latestCloudSessionId;
+
+class CloudPlatformAction extends Action {
+  constructor(params) {
+    super('CloudPlatform', params);
+  }
+
+  get isAtomic() {
+    return true;
+  }
+
+  get timeout() {
+    return 90000;
+  }
+
+  async handle(response) {
+    this.expectResponseOfType(response, 'CloudPlatform');
+
+    return response;
+  }
+}
+
+// Carrier for the App Accessibility scan relay. Two deliberate departures from
+// CloudPlatformAction: a caller-supplied timeout (a scan must be written off long before
+// CloudPlatformAction's 90s), and NO response-type assertion — the whole point is to see
+// whatever the Hub answers with, including a shape nobody has documented, instead of
+// throwing an internal error that hides it.
+class ScanRelayAction extends CloudPlatformAction {
+  constructor(params, timeoutMs, type) {
+    super(params);
+    if (type) {
+      this.type = type;
+    }
+    this._timeoutMs = timeoutMs;
+  }
+
+  get timeout() {
+    return this._timeoutMs;
+  }
+
+  async handle(response) {
+    return response;
+  }
+}
+
+async function executeCloudPlatform(client, method, extra = {}) {
+  const response = await client.sendAction(new CloudPlatformAction(Object.assign({method}, extra)));
+  recordCloudSessionId(response);
+
+  return response;
+}
+
+module.exports = {CloudPlatformAction, ScanRelayAction, executeCloudPlatform, getCloudSessionId};

package/src/detox-driver/environment.js

@@ -0,0 +1,253 @@
+'use strict';
+
+// Custom jest testEnvironment for BrowserStack Detox runs. Extends detox's
+// DetoxCircusEnvironment (so detox's own init / listeners / artifacts still run) and
+// stashes the current spec path on the Node-realm `global` that the CloudPlatform
+// driver reads. The driver loads in this same Node realm during detox.init — where
+// jest's sandbox `expect.getState().testPath` is NOT visible — so the environment
+// (also Node realm, and holding the spec path via `context.testPath`) is the correct
+// place to bridge it. Best-effort: never break detox's environment setup.
+//
+// TRA tap: this environment also observes jest-circus lifecycle events (tests +
+// hooks) and appends JSONL records to the per-slot capture file. Detox's own
+// constructor binds `this.handleTestEvent` (index.js:56) — with a subclass the bind
+// resolves to the override below, which delegates to detox's via super. Capture is
+// active only when the SDK main process exported the events file (TRA enabled).
+const path = require('path');
+
+const traCapture = require('./tra-capture');
+
+const detoxRoot = path.dirname(require.resolve('detox/package.json', {paths: [process.cwd()]}));
+const detoxEnvModule = require(path.join(detoxRoot, 'runners/jest/testEnvironment'));
+const DetoxCircusEnvironment = detoxEnvModule && detoxEnvModule.default ? detoxEnvModule.default : detoxEnvModule;
+
+class BrowserStackDetoxEnvironment extends DetoxCircusEnvironment {
+  constructor(config, context) {
+    super(config, context);
+    try {
+      const testPath = (context && context.testPath) || this.testPath;
+      if (testPath) {
+        global.__BSTACK_DETOX_SPEC__ = testPath;
+      }
+      this._bstackSpecPath = testPath || null;
+      this._bstackTests = new Map();
+      this._bstackHooks = new Map();
+      // jest re-runs a test in place under `retryTimes`, so the same identity
+      // fires test_start/test_done more than once. Remember the first attempt's
+      // uuid per identity so later attempts report as retries of it instead of
+      // landing as independent dashboard rows.
+      this._bstackFirstUuidByKey = new Map();
+    } catch (err) { /* best-effort spec capture */ }
+  }
+
+  async handleTestEvent(event, state) {
+    try {
+      if (traCapture.enabled() && event && event.name) {
+        this._bstackCaptureEvent(event, state, Date.now());
+        // A failure screenshot needs detox's async device API, so it cannot ride
+        // the synchronous capture switch. Awaited here, before detox's own
+        // handler tears the test down and the device becomes unusable.
+        if (event.name === 'test_done' && event.test && event.test.errors && event.test.errors.length) {
+          await this._bstackCaptureScreenshot(event.test);
+        }
+        // Cleared only after the failure capture above, so the driver's tee can still
+        // attribute that screenshot to this test.
+        if (event.name === 'test_done') {
+          global.__BSTACK_DETOX_TEST_UUID__ = null;
+        }
+      }
+    } catch (err) { /* best-effort: capture must never affect the run */ }
+    if (super.handleTestEvent) {
+      return super.handleTestEvent(event, state);
+    }
+  }
+
+  // Console output from the spec is only observable inside this worker, so tee it
+  // into the capture stream tagged with whichever test is running. Wrapping is
+  // guarded and always delegates to the original writer — a customer's console
+  // output must never be swallowed or duplicated.
+  _bstackPatchConsole() {
+    try {
+      if (this._bstackConsolePatched || !this.global || !this.global.console) {
+        return;
+      }
+      this._bstackConsolePatched = true;
+      const levels = {log: 'INFO', info: 'INFO', warn: 'WARN', error: 'ERROR', debug: 'DEBUG'};
+      Object.keys(levels).forEach((method) => {
+        const original = this.global.console[method];
+        if (typeof original !== 'function') {
+          return;
+        }
+        this.global.console[method] = (...args) => {
+          try {
+            const meta = this._bstackCurrentTestMeta;
+            if (meta && meta.uuid) {
+              traCapture.append({
+                kind: 'log',
+                testUuid: meta.uuid,
+                specPath: this._bstackSpecPath,
+                level: levels[method],
+                message: args.map((a) => (typeof a === 'string' ? a : traCapture.safeStringify(a))).join(' '),
+                timestamp: new Date().toISOString()
+              });
+            }
+          } catch (err) { /* never let capture break console */ }
+
+          return original.apply(this.global.console, args);
+        };
+      });
+    } catch (err) { /* best-effort */ }
+  }
+
+  // Screenshot on failure. `device.takeScreenshot` returns the path of the png the
+  // cloud driver wrote from the device's in-app Espresso capture; the image is read
+  // here and carried INLINE as base64, the shape the binary ultimately stores and
+  // the one puppeteer/playwright already ship in production. Carrying bytes rather
+  // than a path removes the binary's cross-process `readFileSync(filePath)` from the
+  // path — that read fails with only a `warn` and an emptied field, i.e. it loses
+  // screenshots silently. `filePath` still rides along as a fallback.
+  //
+  // Bounded by a timeout because a wedged device would otherwise hold the whole run
+  // hostage, and fully swallowed — a missing screenshot must never turn a suite red.
+  async _bstackCaptureScreenshot(test) {
+    try {
+      const device = this.global && this.global.device;
+      if (!device || typeof device.takeScreenshot !== 'function') {
+        return;
+      }
+      const meta = this._bstackTests.get(test) || {};
+      if (!meta.uuid) {
+        return;
+      }
+      const name = `failure-${meta.uuid}`;
+      const filePath = await Promise.race([
+        device.takeScreenshot(name),
+        new Promise((resolve) => setTimeout(() => resolve(null), 15000))
+      ]);
+      if (!filePath || typeof filePath !== 'string') {
+        this._bstackDebug(`screenshot: no path returned for ${name}`);
+
+        return;
+      }
+      // No record is written here on purpose: the driver tees every takeScreenshot into
+      // the TRA stream (bytes already in hand), so appending again would double-report.
+      this._bstackDebug(`screenshot: captured ${name} -> ${filePath}`);
+    } catch (err) {
+      this._bstackDebug(`screenshot: capture failed: ${err && err.message}`);
+    }
+  }
+
+  // The capture path was silently unobservable — a screenshot that never reached the
+  // dashboard left no trace of where it was dropped. Opt-in so it costs nothing.
+  _bstackDebug(message) {
+    try {
+      if (process.env.BROWSERSTACK_DETOX_SCREENSHOT_DEBUG === 'true') {
+        console.log(`[bstack-detox] ${message}`);
+      }
+    } catch (err) { /* best-effort */ }
+  }
+
+  _bstackCaptureEvent(event, state, now) {
+    switch (event.name) {
+      case 'setup': {
+        this._bstackPatchConsole();
+        break;
+      }
+      case 'test_start': {
+        if (event.test) {
+          const key = [this._bstackSpecPath, traCapture.scopesOf(event.test).join('>'), String(event.test.name || '')].join('|');
+          const firstUuid = this._bstackFirstUuidByKey.get(key);
+          const uuid = traCapture.mintUuid();
+          if (!firstUuid) {
+            this._bstackFirstUuidByKey.set(key, uuid);
+          }
+          this._bstackTests.set(event.test, {uuid, startedAt: now, retryOf: firstUuid || null});
+          this._bstackCurrentTestMeta = this._bstackTests.get(event.test);
+          // Published for the cloud driver (same Node realm, the way __BSTACK_DETOX_SPEC__
+          // already is): it tees EVERY device.takeScreenshot() — including the customer's
+          // own calls from a test body — and needs the owning test to attribute it to.
+          global.__BSTACK_DETOX_TEST_UUID__ = uuid;
+        }
+        break;
+      }
+      case 'test_done': {
+        const test = event.test;
+        if (!test) {
+          break;
+        }
+        const meta = this._bstackTests.get(test) || {};
+        const failed = Boolean(test.errors && test.errors.length);
+        traCapture.append({
+          kind: 'test',
+          uuid: meta.uuid || traCapture.mintUuid(),
+          specPath: this._bstackSpecPath,
+          name: String(test.name || ''),
+          scopes: traCapture.scopesOf(test),
+          status: failed ? 'failed' : 'passed',
+          startedAt: meta.startedAt || null,
+          endedAt: now,
+          durationMs: meta.startedAt ? now - meta.startedAt : null,
+          failure: traCapture.serializeErrors(test.errors),
+          ...(meta.retryOf ? {retryOf: meta.retryOf} : {})
+        });
+        this._bstackCurrentTestMeta = null;
+        break;
+      }
+      case 'test_skip':
+      case 'test_todo': {
+        const test = event.test;
+        if (!test) {
+          break;
+        }
+        traCapture.append({
+          kind: 'test',
+          uuid: traCapture.mintUuid(),
+          specPath: this._bstackSpecPath,
+          name: String(test.name || ''),
+          scopes: traCapture.scopesOf(test),
+          status: 'skipped',
+          startedAt: now,
+          endedAt: now,
+          durationMs: 0
+        });
+        break;
+      }
+      case 'hook_start': {
+        if (event.hook) {
+          this._bstackHooks.set(event.hook, {uuid: traCapture.mintUuid(), startedAt: now});
+        }
+        break;
+      }
+      case 'hook_success':
+      case 'hook_failure': {
+        const hook = event.hook;
+        if (!hook) {
+          break;
+        }
+        const meta = this._bstackHooks.get(hook) || {};
+        const currentTest = state && state.currentlyRunningTest;
+        const testMeta = currentTest ? this._bstackTests.get(currentTest) : null;
+        traCapture.append({
+          kind: 'hook',
+          uuid: meta.uuid || traCapture.mintUuid(),
+          specPath: this._bstackSpecPath,
+          hookType: String(hook.type || ''),
+          testUuid: (testMeta && testMeta.uuid) || null,
+          testName: currentTest ? String(currentTest.name || '') : null,
+          scopes: traCapture.scopesOf(hook),
+          status: event.name === 'hook_failure' ? 'failed' : 'passed',
+          startedAt: meta.startedAt || null,
+          endedAt: now,
+          durationMs: meta.startedAt ? now - meta.startedAt : null,
+          failure: event.error ? traCapture.serializeErrors([event.error]) : undefined
+        });
+        break;
+      }
+      default:
+        break;
+    }
+  }
+}
+
+module.exports = BrowserStackDetoxEnvironment;
+module.exports.default = BrowserStackDetoxEnvironment;

package/src/detox-driver/expect.js

@@ -0,0 +1,44 @@
+'use strict';
+
+// Reuse vanilla detox's Android matchers (element/expect/waitFor/web). The built-in
+// Android matchers factory remaps its deps before construction
+// (`{invocationManager, device, emitter}`), but the external matchers factory
+// (matchers/factories/index.js: External.createMatchers) passes
+// `{invocationManager, runtimeDevice, eventEmitter}` straight through unmapped — so
+// this adapter does the same remap AndroidExpect expects.
+//
+// detox is resolved from process.cwd() (the customer's install), not the SDK package.
+const path = require('path');
+
+const detoxRoot = path.dirname(require.resolve('detox/package.json', {paths: [process.cwd()]}));
+const AndroidExpect = require(path.join(detoxRoot, 'src/android/AndroidExpect'));
+
+const a11y = require('./a11y');
+
+class CloudExpect extends AndroidExpect {
+  constructor({invocationManager, runtimeDevice, eventEmitter}) {
+    super({invocationManager, device: runtimeDevice, emitter: eventEmitter});
+  }
+
+  // App Accessibility wraps mapped element and web-view actions so a scan can fire on
+  // their completion. This is the SDK-owned seam for it: AndroidExpect binds
+  // element/web/waitFor/expect in its constructor, so a subclass override is what those
+  // bindings resolve to — no Detox internal is patched, and `waitFor`/`expect` are left
+  // alone because no matcher or expectation is a scannable command.
+  //
+  // The wrapper is installed ONLY when a11y is armed. With it disabled these overrides
+  // return exactly what AndroidExpect returns, so the non-a11y path is unchanged.
+  element(matcher) {
+    const element = super.element(matcher);
+
+    return a11y.enabled() ? a11y.wrap(element, 'NativeElement') : element;
+  }
+
+  web(matcher) {
+    const webView = super.web(matcher);
+
+    return a11y.enabled() ? a11y.wrap(webView, 'WebViewElement') : webView;
+  }
+}
+
+module.exports = CloudExpect;

package/src/detox-driver/index.js

@@ -0,0 +1,12 @@
+'use strict';
+
+// Vanilla Detox external device module contract (detox/src/environmentFactory.js:
+// _getExternalModuleFactories). device.type must be a require-able path to this
+// directory; these three exports are validated by
+// devices/allocation/factories/external.js, devices/runtime/factories/external.js and
+// matchers/factories/index.js's External classes.
+module.exports = {
+  DeviceAllocationDriverClass: require('./allocationDriver'),
+  RuntimeDriverClass: require('./runtimeDriver'),
+  ExpectClass: require('./expect')
+};

package/src/detox-driver/login-timeout-preload.js

@@ -0,0 +1,25 @@
+'use strict';
+
+// Login-timeout fix, loaded via NODE_OPTIONS=--require BEFORE detox loads (the SDK's
+// `detox` command injects it, mirroring the nightwatch spawn preload). Vanilla detox
+// times out the Login WS action at 1000ms; BrowserStack cloud device allocation takes
+// longer, so the timeout must be raised before detox is required — an in-driver patch
+// loads too late (Login fires before the device driver module is required).
+//
+// Guarded: a failure here must never break the customer's run (the default 1000ms
+// window would apply and Detox would surface its own timeout, not an SDK crash).
+try {
+  const path = require('path');
+  const detoxRoot = path.dirname(require.resolve('detox/package.json', {paths: [process.cwd()]}));
+  const actions = require(path.join(detoxRoot, 'src/client/actions/actions'));
+  const ms = Number(process.env.BSTACK_DETOX_LOGIN_TIMEOUT_MS || 240000);
+  Object.defineProperty(actions.Login.prototype, 'timeout', {
+    configurable: true,
+    get() {
+      return ms;
+    }
+  });
+} catch (err) {
+  // eslint-disable-next-line no-console
+  console.error('[browserstack-detox] login-timeout preload failed: ' + (err && err.message));
+}