feat(mobile): device.unstable_raw exposes the test's agent-device session

Merged
OK
19d ago
+188-4

device is a closed method list. A host embedding e2e (T3 Code) or a test needing an agent-device command device doesn't wrap had no way to reach its own session: no device id, no session name, no client. The workaround was a second agent-device client guessing the session name e2e-<target>-<n>.

  • device.unstable_raw returns the session name, the device's agent-device id and name, the engine's device selection, and an agent-device client bound to the session.
  • Prefixed unstable_: no support promise, it may change or go away in any release.
  • Device id and name come from the boot result in init (packages/mobile/src/surface.ts), so they are exact even when the pool let the daemon pick a booted device.
  • client reads the worker's live client; after dispose it throws INVALID_STATE, like the rest of the surface.
  • Raw calls are deliberately outside e2e: not steps (no report or trace entry), not cached or replayed, args not redacted, no settle or transition wait. JSDoc, the reference entry, and the guide say so.
test('reads its own session', async ({ device }) => {
  const { client, session, deviceId, selection } = device.unstable_raw;
  const own = (await client.sessions.list()).find((entry) => entry.name === session);
  await client.apps.list(selection);
});
/** The agent-device session behind `device`; see `Device.unstable_raw`. */
export interface DeviceSession {
  readonly platform: MobilePlatform;
  readonly session: string;
  readonly deviceId: string;
  readonly deviceName: string;
  readonly selection: DeviceSelection;
  readonly client: AgentDeviceClient;
}

Verified

Ran it locally: yes

  • mobile benchmark, fresh iOS 26.5 iPhone 17 Pro simulator, scratch config pinning that UDID and session e2e-session-handle-verify (so it didn't collide with other runs on the shared sims).
  • New test tests/device-fixture.e2e.ts > "unstable_raw reaches the test session through agent-device": finds its own session in client.sessions.list() with matching device id and name, and reads inventory-header from a raw client.capture.snapshot.
$ e2e run tests/device-fixture.e2e.ts --config e2e.verify.config.ts --grep unstable_raw --retries 0
 ✓ mobile engine for target "ios-simulator" prepared 918ms
 ✓ |ios-simulator| tests/device-fixture.e2e.ts (1 test) 3.82s
   ✓ device fixture > unstable_raw reaches the test session through agent-device 3.82s
      Tests  1 passed (1)
  • Whole device-fixture.e2e.ts on the same simulator: 11 passed in 63.8s.
  • --trace page for the new test lists only the beforeEach steps (app.open, expect.toBeVisible, locator.tap); the raw client calls don't appear, as documented.
  • Android not run.