feat(cli): e2e run --step holds each step until a key

Merged
KR
13d ago
+1632-123

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.

KeyDoes
Enterruns the held step
nruns the rest of this test, holds at the next test
aruns the rest of the run without stopping
hshows or hides every key
q, Escstops 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.ts or wire schema changes. A worker holds each top-level step over IPC (step-hold, step-release, step-cancel).

  • Held time counts toward no timeout. AttemptHolds stops the test clock and rearms the deadline with what was left. The scheduler pushes maxDuration back by the held time.

  • Setup tests, retries, teardown steps, and steps inside an expect.poll read run without stopping.

  • Steps held together in one Promise.all share one prompt and run on one Enter. A waitForResponse placed beside the click that triggers it (the pattern in docs/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.

  • --step is refused, with exit 2:

    • in CI;
    • without a TTY;
    • with --watch;
    • with --workers above 1;
    • with the json reporter.

    It forces one worker.

  • Docs:

    • docs/debugging.mdx gets 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 e2e build in a scratch project. It has a one-page app and two test files. Each run was driven in tmux on LBox with e2e run --step.
  • Coffee test, keys: Enter runs one step and moves to the next prompt. h shows the full key list and h again hides it. n finishes the test and holds at step 1 of the next test. a runs to the end. Result: 2 passed, exit 0.
  • Promise.all test, 7 s pause: both steps show in one prompt. I waited 7 s before pressing Enter, longer than the 5 s waitForURL gets. 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.ts checks 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.ts checks the keys, the 150 ms guard, and the shared Promise.all prompt.
  • Headed run on macOS: Krzysztof ran an earlier build of the same demo with --step --headed on a Mac. That was before the Promise.all grouping 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).