feat(browserstack): add @e2e-dev/browserstack device provider
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/leaseasagentDeviceLeases(), run on mobile's own agent-device. Both providers use it and peer@e2e-dev/mobile >=0.12.5. The device-cloud example indocs/mobile.mdxuses it too. - BrowserStack's
appcapability takes only an uploaded app (bs://,custom_id,shareable_id); a public URL fails session creation withBROWSERSTACK_INVALID_APP_URL, which agent-device surfaces asWebDriver create-session response missed sessionId. Anhttpsappis therefore uploaded once per run throughPOST /app-automate/upload(url=) and itsbs://id shared by every slot (packages/browserstack/src/provider.ts,uploadAppFromUrlinsrc/sessions.ts). - Release is strict:
daemon stopmust reportproviderReleases.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 underreleased, so a retry that finds no daemon still fails (assertSessionsEndedinpackages/mobile/src/lease/daemon.ts).@e2e-dev/testmunow gets the same strict release. - An
httpsapp URL never reaches logs or errors: the upload notice names only thebs://id, API errors redact the URL and its query before truncation, and a transport error keeps only a redacted cause. recordlinks BrowserStack's session video, found by build name (every build of that name, since projects can share one), then session name, withvideo_urlread again atstop.- 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 runwithdocs/examples/mobile/browserstack.config.tsandbrowserstack.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. -
findSessionagainst 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, andskills/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.