feat(browserstack): add @e2e-dev/browserstack device provider

Merged
MA
17d ago
+2282-471

Refs #1404

What and why

  • New @e2e-dev/browserstack: browserstack({ device, osVersion, app }) leases BrowserStack App Automate real Android and iOS devices for @e2e-dev/mobile, one isolated agent-device daemon per worker slot, the same shape as @e2e-dev/testmu.
  • agent-device ships BrowserStack in core (leaseProvider: 'browserstack'), so there is no plugin to install.
  • The lease plumbing testmu and browserstack shared (daemon per slot, heartbeat, daemon stop, acquire/release) now lives in @e2e-dev/mobile/lease as agentDeviceLeases(), run on mobile's own agent-device. Both providers use it and peer @e2e-dev/mobile >=0.12.5. The device-cloud example in docs/mobile.mdx uses it too.
  • BrowserStack's app capability takes only an uploaded app (bs://, custom_id, shareable_id); a public URL fails session creation with BROWSERSTACK_INVALID_APP_URL, which agent-device surfaces as WebDriver create-session response missed sessionId. An https app is therefore uploaded once per run through POST /app-automate/upload (url=) and its bs:// id shared by every slot (packages/browserstack/src/provider.ts, uploadAppFromUrl in src/sessions.ts).
  • Release is strict: daemon stop must report providerReleases.status: 'completed' with nothing pending. A forced stop or a lost shutdown report (status: 'unknown', pending: null) fails the release and keeps the lease and its state for diagnosis instead of treating a possibly billed session as ended, and a granted lease needs its id listed under released, so a retry that finds no daemon still fails (assertSessionsEnded in packages/mobile/src/lease/daemon.ts). @e2e-dev/testmu now gets the same strict release.
  • An https app URL never reaches logs or errors: the upload notice names only the bs:// id, API errors redact the URL and its query before truncation, and a transport error keeps only a redacted cause.
  • record links BrowserStack's session video, found by build name (every build of that name, since projects can share one), then session name, with video_url read again at stop.
  • Options mirror the agent-device BrowserStack flags: orientation, geoLocation, timezone, language, locale, appiumVersion, networkProfile / customNetwork (mutually exclusive), and iOS-only noResignApp.
mobile({
  platform: 'android',
  device: browserstack({ device: 'Google Pixel 7', osVersion: '13.0', app: apk, appiumVersion: '3.2.0' }),
})

Verified

Ran it locally: yes

  • Docs example, live on BrowserStack App Automate: e2e run with docs/examples/mobile/browserstack.config.ts and browserstack.e2e.ts (WikipediaSample.apk by URL, Google Pixel 7 / Android 13.0):

    ℹ browserstack (1 of 1): uploaded the app URL as bs://…
    ℹ browserstack (1 of 1): lease …: Google Pixel 7, android 13.0; session e2e-…-pixel-7-1 reserved
     ✓ mobile engine for target "pixel-7" prepared 19.98s
     ✓ |pixel-7| tests/home.e2e.ts (1 test) 2.23s
    ℹ browserstack: released 1 device(s)
    
  • A production app (bs:// id, Google Pixel 9 / Android 16.0): open, assert a banner, tap, assert it is gone; passed in 10.4 s, device released.

  • findSession against the live API found that session by build and name and returned its video URL.

  • The WikipediaSample shows an old-target-SDK dialog on Android 16, so the example pins Android 13.0.

Maintainer takeover (squashed and rebased on main): the shared lease helper, strict release for testmu, and fixes from review (a throwing log no longer leaks a granted lease, the service env can't override AGENT_DEVICE_*, signed URL out of error causes, same-named builds across projects). pnpm check passes; unit tests: mobile 476, testmu 87, browserstack 53. No live BrowserStack or TestMu run after the refactor.

Checklist

  • Changeset added (pnpm changeset) for any change to a published package, or the change is testbed, docs, or CI only.
  • Breaking change: n/a.
  • Docs updated in the same PR: docs/integrations/browserstack.mdx, docs/integrations/testmu.mdx, index card, mobile.mdx, reference/environment.mdx, and skills/e2e/references/setup.md.
  • Contract change: n/a.
  • Engine contract change: n/a.

Logos: Devicon 2.16.0 (MIT) browserstack-plain.svg for the sidebar and browserstack-original.svg for the card; Simple Icons has no BrowserStack mark. Happy to swap in BrowserStack's official files.