@browserstack/mobilewright

BrowserStack App Automate driver for Mobilewright. Every test session is a first-class App Automate session — dashboard, server-side video, device/network logs, BrowserStack Local, geolocation/network simulation, camera & biometric injection — with no BrowserStack-specific code in your tests.

Requires mobilewright ≥ 0.0.53; Node requirements are exactly your existing Mobilewright project's — this package adds none of its own. Install into an existing Mobilewright project (@mobilewright/test comes with your Mobilewright setup):

npm i -D @browserstack/mobilewright

Heads-up (upstream, not BrowserStack-specific): despite mobilewright declaring node >=18, its config loading needs Node ≥ 20.19 in CommonJS projects (require() of an ESM package) — Node 18.x fails at config load with ERR_REQUIRE_ESM even with no driver configured. See upstream/README.md §3.

Point an existing Mobilewright suite at BrowserStack by setting the driver:

// mobilewright.config.ts
import { defineConfig } from 'mobilewright';
import { browserStackDriver } from '@browserstack/mobilewright';

export default defineConfig({
  testDir: './tests',
  bundleId: 'org.wikipedia.alpha',
  driver: browserStackDriver({
    app: 'bs://<app-id>',          // or a local .apk/.ipa path, or an https:// url — uploaded for you
    project: 'My project',
  }),
  projects: [
    { name: 'android', use: { platform: 'android', deviceName: /Google Pixel 8\b/ } },
    { name: 'ios', use: { platform: 'ios', deviceType: 'real', osVersion: '>=17 <19' } },
  ],
});

browserStackDriver(options) is new BrowserStackDriver(options) spelled like configuration — mobilewright ≥0.0.53 takes the driver as an instance. Device selection uses the standard config fields: deviceName (regex), osVersion (range expressions like ">=17 <19"), deviceType (App Automate is real devices). Credentials come from BROWSERSTACK_USERNAME / BROWSERSTACK_ACCESS_KEY env vars (or the username/accessKey options); the app falls back to the BROWSERSTACK_APP env var. Tests are stock Mobilewright.

Session names and statuses are automatic. The driver ships a TestObserver, which mobilewright invokes without any reporter configuration: at run end every App Automate session is named after the tests it ran, marked passed/failed, and its dashboard link printed.

Switching between a local device and BrowserStack

Keep one config and pick the driver by environment — local (mobilecli) by default, BrowserStack when credentials are present:

const config: MobilewrightConfig = { /* ...your existing config... */ };

if (process.env.BROWSERSTACK_USERNAME) {
  config.driver = browserStackDriver({ app: './apps/checkout.apk' });
}

export default defineConfig(config);

npx mobilewright test                                     # local device, as always
BROWSERSTACK_USERNAME=… BROWSERSTACK_ACCESS_KEY=… \
  npx mobilewright test                                   # the same suite on App Automate

Local .apk/.ipa paths are uploaded automatically (once per run), and the fixtures' mid-session reinstall of the session app is skipped.

What's inside

• src/driver.ts — the full Mobilewright driver contract: DeviceAllocator (one App Automate session per worker slot; workers attach by session id) + MobilewrightSession (26 verbs + webViewBridge with multi-webview page expansion) over BrowserStack's standard W3C WebDriver session API.
• src/observer.ts — the TestObserver: automatic session naming/status + dashboard links.
• src/executor.ts — browserStackExecutor() escape hatch for BrowserStack-specific actions (camera image injection, biometrics, Apple Pay, …).
• src/reporter.ts — standalone Playwright reporter; superseded by the observer, kept for suites that want reporter-style wiring explicitly.
• e2e/ — conformance suites (Android/iOS native, webview, phase-2 features, BrowserStack Local, the Milliways cross-platform suite), the release compat gate (e2e/compat-check.sh), and the local-vs-cloud performance benchmark (e2e/perf/).
• upstream/ — pending one-line upstream fixes found by these suites.

Dev setup

Plain npm — the package builds against the published mobilewright packages:

npm install && npm run build && npm run lint && npm run test:unit

# conformance against real App Automate devices
export BROWSERSTACK_USERNAME=… BROWSERSTACK_ACCESS_KEY=…
cd e2e && ./compat-check.sh

e2e/compat-check.sh pins the @mobilewright/protocol version and fails loudly when upstream's driver interface moves; bump the pin deliberately after reviewing changes.

Contributing & security

See CONTRIBUTING.md for setup, style, the compat-gate policy, and the release process. Report vulnerabilities privately per SECURITY.md — never via public issues. Code review is owned by the App Automate team (.github/CODEOWNERS); dependencies are watched by Dependabot.

License

Apache-2.0 (see LICENSE).