feat(e2e): record one span of the screen with app.startRecording and app.stopRecording

Merged
OK
19d ago
+735-31

Video was only a per-attempt mode (off / on / retain-on-failure), so a test could not record a single transition. This adds a span recording on the universal app fixture, next to app.screenshot(), on every engine that records video (web, hosted browsers, mobile, hosted devices).

test('the sheet slides up', { video: 'off' }, async ({ app, screen }) => {
  await app.open();
  await app.startRecording({ name: 'sheet' });
  await screen.getByRole('button', 'Open sheet').tap();
  await expect(screen.getByText('Sheet title')).toBeVisible();
  const [video] = await app.stopRecording();
  if ('path' in video) console.log(video.path); // .e2e/results/.../attempt-1/recordings/001-sheet.mp4
});
  • Runs in the runner core on the existing engine contract, EngineArtifacts.startVideo / stopVideo. No new engine methods. The contract JSDoc now says an attempt may start and stop more than once, never overlapping. Web, kernel-style provider video, and mobile already handled that, and their unit tests now cover it.
  • packages/e2e/src/run/recordings.ts tracks who holds the engine's one recorder per session: the attempt's video or a span. It moves each stopped segment from video/ to recordings/NNN-<name>[-partN].<ext> before anything can overwrite it, registers each file or link as a video artifact, and links it from the app.stopRecording step.
  • Return type: Promise<readonly [RecordedVideo, ...RecordedVideo[]]>, where RecordedVideo is { path, startedAt } (absolute path) or { url, mediaType, startedAt } (hosted). Every segment is returned, because on the web a page replaced mid-span (app.restart(), app.clearState()) legitimately gives one file per page. Throwing on that case would break a normal test. The non-empty tuple means const [video] = await app.stopRecording() needs no undefined check. A stop whose engine wrote nothing fails with ENGINE_FAILURE.
  • Conflicts throw, nothing is stopped behind the test's back:
    • while the test's video records: UNSUPPORTED_CAPABILITY, and the message says to set video: 'off' on the test
    • on an engine without video: UNSUPPORTED_CAPABILITY
    • another span running, or a stop with none: INVALID_ARGUMENT
  • A span still running when the attempt ends is stopped within the cleanup budget and kept as an attempt artifact. A serial member's span ends with the member, not the group.
  • The attempt's video mode is unchanged. It only marks the recorder as held now, and a span never collects the attempt's segments.
  • Trace: a step's video m:ss offset now uses only a recording that covers the step. A recording stopped by a step ends at that step, so steps before or after a span get no offset. packages/e2e/src/report/failure-text.ts.
  • Removed device.startRecording / device.stopRecording from @e2e-dev/mobile. They were never released, and mobile's source is back to main.
  • Docs: reference/app.mdx (new entries and types), mobile.mdx "Record a transition" (now uses app, keeps the closeApp gotcha), reference/engine.mdx Videos, reference/errors.mdx, Maestro mapping, skill writing-tests and debugging (plus plugin copy). reference/screen.mdx says boundingBox() is in points on a device.

Why spans refuse instead of nesting inside the attempt video: on mobile, a device-scope recording started before the app has a session creates its own session, and stopping it ends that session. The attempt video starts before app.open(), so pausing it mid-test would kill the test's app session (agent-device CLI: record stop returned recordOnlySession: true, then snapshot got SESSION_NOT_FOUND).

Verified

Ran it locally: yes

Scratch test files (not committed) with the built CLI, --trace on.

Web: web-benchmark, local Chromium, Async States scenario (served on a scratch port, since 4280 was held by another checkout).

PROBE videos [{"path":".../attempt-1/recordings/001-toast.webm","startedAt":"2026-10-27T22:15:37.340Z"}]
PROBE restart videos ["recordings/001-restart.webm","recordings/001-restart-part2.webm"]
PROBE refusal UNSUPPORTED_CAPABILITY app.startRecording cannot record while the test's video records, since the engine has one recorder; set video: 'off' on the test: test('...', { video: 'off' }, ...)
 ✓ records the toast coming and going 5.07s
 ✓ one video per page across a restart 376ms
 ✓ refuses while the video records 150ms
  • 001-toast.webm: vp9, 1280x720, 114 frames, decodes cleanly. Scene changes at 0.08 s (toast appears after the tap) and 2.56 s (toast gone). That matches the steps: tap at +0.00 s, toBeHidden ended at +2.56 s. The file runs 4.56 s against a 2.9 s span because Playwright's screencast pads at least 1 s of the last frame when it stops. The attempt video does the same.
  • video: 'on' test: refused, and the attempt's video/video.webm is still written and linked in Evidence.

web: before the tap, the toast, after it left

iOS: fresh iOS 26.5 simulator (xcrun simctl create, deleted afterwards; no other booted sim touched), mobile benchmark Release build, Modal Flow, own session name.

PROBE ms from tap to stop 3786
PROBE videos [{"path":".../attempt-1/recordings/001-modal_opens.mp4","startedAt":"2026-10-27T22:15:00.674Z"}]
PROBE refusal UNSUPPORTED_CAPABILITY app.startRecording cannot record while the test's video records, since the engine has one recorder; set video: 'off' on the test: test('...', { video: 'off' }, ...)
 ✓ records the modal opening 8.89s
 ✓ refuses while the video records 8.49s
  • 001-modal_opens.mp4: h264, 1206x2622, 30 fps, 88 frames, 2.93 s, decodes cleanly. The span from the recorder's confirmed start to the stop call was 2.49 s. The device keeps recording until the stop lands (the stop step took 1.3 s to finalize).
  • video: 'on' test: refused, and the attempt's video/video.mp4 is still written (5.37 s).

ios: before tap, scrim fading in, sheet open

Trace page (iOS):

5. ✓ `app.startRecording` `modal opens` (572ms) — `tests-verify/recording.e2e.ts:5`
6. ✓ `locator.tap` `getByTestId("open-modal-button")` (934ms, video 0:00) — `tests-verify/recording.e2e.ts:7`
7. ✓ `expect.toBeVisible` `getByTestId("continue-button")` (57ms, video 0:00) — `tests-verify/recording.e2e.ts:8`
8. ✓ `app.stopRecording` (1.3s, video 0:02) — `tests-verify/recording.e2e.ts:10`
9. ✓ `locator.tap` `getByTestId("continue-button")` (428ms) — `tests-verify/recording.e2e.ts:13`

## Evidence

- [video](attempt-1/recordings/001-modal_opens.mp4) `.e2e/results/recording-records-the-modal-opening-.../attempt-1/recordings/001-modal_opens.mp4`

Not run: Android emulator, hosted browser and device providers. They go through the same startVideo / stopVideo path, and the link case is covered by unit tests.

Upload from /tmp: gh pr edit 1381 --title "feat(e2e): record one span of the screen with app.startRecording and app.stopRecording" --body-file body.md --attach ./web-strip.png --attach ./ios-strip.png --attach /tmp/rec-verify/web/001-toast.webm --attach /tmp/rec-verify/ios/001-modal_opens.mp4