For engineering

A check on the PR for the flows customers are taught.

Walkthroughs are YAML next to the code and run like tests. A failure is filed with the video, an intended change is one approval, and you never maintain a help center.

In the repo, reviewed like code

A walkthrough names the feature it covers and the source files it anchors to. Record it on your laptop against localhost with npx stagewright record, or have your coding agent write it through the MCP server.

.walkthroughs/invite-teammate.yaml

id: invite-teammate
title: Invite a teammate
features: [settings/members]
anchors: [src/invites/**]
steps:
  - id: open
    narration: Teammates live under Settings, in Members.
    actions:
      - goto: /settings/members
    expect:
      - visible: 'role=heading[name="Members"]'

  - id: open-invite
    narration: Click Invite to add someone by email.
    actions:
      - click: 'role=button[name="Invite"]'
      - fill: { target: 'internal:label="Email"i', value: "{{vars.email}}" }

  - id: send-invite
    narration: Pick a role, then send the invite. They get an email right away.
    actions:
      - select: { target: 'internal:label="Role"i', value: Member }
      - click: 'role=button[name="Send invite"]'
    expect:
      - text: { target: "role=status", contains: "Invite sent" }

A walkthrough is a YAML file next to the code. Narration, actions and checks in one place, reviewed in pull requests.

A verdict people trust

Every failure is recorded twice before it's judged, so the check fails only on a regression or a walkthrough your change broke. Flaky runs are reported, never blocking. Only walkthroughs your changed files can affect are recorded.

The GitHub App, or stagewright ci in GitHub Actions, GitLab, Azure DevOps and Bitbucket.
Exit code 1 is the only one that should block a merge.

Verdict	Meaning	Check
= Unchanged	Passed; every step matches the approved frames	success
Δ UI changed / + New	Passed; steps look different, or it's the first run	action required: approve
! Update the walkthrough	Failed twice the same way, and the PR touched the walkthrough's anchors	failure
▲ Regression	Failed twice the same way, and the PR didn't touch its anchors. Filed as an issue	failure
~ Flaky	Failed once, then passed or failed elsewhere on the automatic second run. Never files an issue	neutral
– Skipped	The change can't affect it; its approved recording stays the baseline	no run

Every failed recording runs a second time before it's judged. Only a regression or a broken walkthrough fails the check.

Found, filed, fixed, proven

A regression lands in Linear, Jira or GitHub Issues with the clip of the failing step, the failing selector, the second run's result and a trace, assigned to the PR's author. Hand it to a coding agent with /stagewright:fix. When the fix PR says Fixes ACM-231, the walkthrough is replayed and the verdict goes back on the PR and the issue.

ACM-231

Invite a teammate: Send invite button not found

Status: Done
Assignee: Lee Park · PR author
Label: walkthrough-regression
Found on: PR #412 · 8c1e7d2

0:58 · step 4 send-invite

Steps to reproduce

Open /settings/members
Click Invite, enter an email
Pick a role, click Send invite

Failing check

click role=button[name="Send invite"] · 0 elements after 10 s

Second run failed at the same step. Trace, frame and recording attached.

Fix it with a coding agent

/stagewright:fix ACM-231

Stagewright filed this from run 2188 on PR #412
Lee Park delegated the fix to a coding agent
Fix proven on PR #418 at 3f9a2c1: the walkthrough passed step 4

A regression, filed with its video. The fix PR is replayed and the result is posted back. Sample project, example data.

Try it on your own product

Record a first walkthrough on your machine with no account. PR checks, approvals and publishing are in private beta: join the waitlist and we'll set you up by hand.

npx stagewright init

Join the waitlist Developer docs