feat(e2e): record one span of the screen with app.startRecording and app.stopRecording
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.tstracks who holds the engine's one recorder per session: the attempt'svideoor a span. It moves each stopped segment fromvideo/torecordings/NNN-<name>[-partN].<ext>before anything can overwrite it, registers each file or link as a video artifact, and links it from theapp.stopRecordingstep.- Return type:
Promise<readonly [RecordedVideo, ...RecordedVideo[]]>, whereRecordedVideois{ 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 meansconst [video] = await app.stopRecording()needs noundefinedcheck. A stop whose engine wrote nothing fails withENGINE_FAILURE. - Conflicts throw, nothing is stopped behind the test's back:
- while the test's
videorecords:UNSUPPORTED_CAPABILITY, and the message says to setvideo: 'off'on the test - on an engine without video:
UNSUPPORTED_CAPABILITY - another span running, or a stop with none:
INVALID_ARGUMENT
- while the test's
- 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
videomode 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:ssoffset 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.stopRecordingfrom@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 usesapp, keeps thecloseAppgotcha),reference/engine.mdxVideos,reference/errors.mdx, Maestro mapping, skillwriting-testsanddebugging(plus plugin copy).reference/screen.mdxsaysboundingBox()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,toBeHiddenended 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'svideo/video.webmis still written and linked in Evidence.

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'svideo/video.mp4is still written (5.37 s).

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