feat(cli): e2e run --step holds each step until a key
e2e run had no way to stop between steps. --headed shows the app, but the test runs straight through. Playwright users reach for page.pause() or --debug and find nothing.
e2e run --step runs the first step, then holds each later top-level step until a key is pressed. The keys follow --watch.
| Key | Does |
|---|---|
| Enter | runs the held step |
n | runs the rest of this test, holds at the next test |
a | runs the rest of the run without stopping |
h | shows or hides every key |
q, Esc | stops the run like Ctrl-C (exit 130) |
❯ web tests/coffee.e2e.ts 0/2
└── orders two drinks paused
✓ app.open "/" 50ms
▶ step 2 locator.click "getByRole("radio", name: "Latte")" tests/coffee.e2e.ts:7
press enter to run this step, press h to show help, press q to quit
How it works
sequenceDiagram
participant W as worker (StepRecorder)
participant S as scheduler
participant G as StepGate (CLI)
W->>W: AttemptHolds stops the test clock
W->>S: step-hold
S->>G: beforeStep(step, { signal, show })
G-->>S: resolves on Enter / n / a
S->>W: step-release
W->>W: clock runs again with the time it had left
-
RunOptions.beforeStep(packages/e2e/src/run/step-hold.ts) is an internal seam. It is not public API, so there are no.d.tsor wire schema changes. A worker holds each top-level step over IPC (step-hold,step-release,step-cancel). -
Held time counts toward no timeout.
AttemptHoldsstops the test clock and rearms the deadline with what was left. The scheduler pushesmaxDurationback by the held time. -
Setup tests, retries, teardown steps, and steps inside an
expect.pollread run without stopping. -
Steps held together in one
Promise.allshare one prompt and run on one Enter. AwaitForResponseplaced beside the click that triggers it (the pattern indocs/browser.mdx) would otherwise run alone and time out while the click waits for its key. -
The prompt is drawn in the list reporter's live window under its test. Without a live window, it is one plain line.
-
--stepis refused, with exit 2:- in CI;
- without a TTY;
- with
--watch; - with
--workersabove 1; - with the json reporter.
It forces one worker.
-
Docs:
docs/debugging.mdxgets a "Step through a test" section.- The CLI reference, the errors reference, the Playwright migration rows (
page.pause(),--debug), and the skill references are updated. - Patch changeset.
Issue
Closes #1251
Verified
Ran it locally: yes
- Surface: the packed
e2ebuild in a scratch project. It has a one-page app and two test files. Each run was driven in tmux on LBox withe2e run --step. - Coffee test, keys: Enter runs one step and moves to the next prompt.
hshows the full key list andhagain hides it.nfinishes the test and holds at step 1 of the next test.aruns to the end. Result: 2 passed, exit 0. Promise.alltest, 7 s pause: both steps show in one prompt. I waited 7 s before pressing Enter, longer than the 5 swaitForURLgets. The test passed with exit 0.
└── waits for the page a navigation opens paused
✓ app.open "/" 50ms
▶ step 2 browser.waitForURL "/\/menu$/" tests/together.e2e.ts:6
▶ step 3 app.open "/menu" tests/together.e2e.ts:6
press enter to run these 2 steps, press h to show help, press q to quit
...
✓ web tests/together.e2e.ts (1 test) 8.61s
- Integration tests:
tests/integration/step-hold.test.tschecks against real workers that:- a hold stops the test clock and the time limit;
- a test that hangs after a release still times out on the time it had left;
- an interrupt ends a held step as
interrupted; - setup tests, teardown, retries, and poll reads are never held.
- Unit tests:
tests/unit/cli-step.test.tschecks the keys, the 150 ms guard, and the sharedPromise.allprompt. - Headed run on macOS: Krzysztof ran an earlier build of the same demo with
--step --headedon a Mac. That was before thePromise.allgrouping change.
Reviewed with sol-loop: 1 round with gpt-6.1-sol. Sol verdict: approved. That approval was before the Promise.all grouping, which a later fresh-context review asked for.
Written by Claude Opus 5.5 in Claude Code (T3 Code).