**Developers** # Walkthroughs live in your repo and run in your CI. YAML next to the code, recorded on your laptop against localhost, checked on every pull request in GitHub, GitLab, Azure DevOps or Bitbucket, and written by your coding agent if you'd rather not. npx stagewright init[stagewright on npm](https://www.npmjs.com/package/stagewright) ## Quickstart, no account `init` writes a sample walkthrough, `stagewright.config.ts` and the JSON Schema for your editor.`doctor` checks Node, Chromium and ffmpeg. `record` records the sample against Playwright's demo app and renders `.stagewright/out//final.mp4`, with a trace, screenshots and a timeline. ``` npx stagewright init npx stagewright doctor --install npx stagewright record .walkthroughs/example.yaml ``` Node.js 22.18 or newer. Narration uses a local OpenAI-compatible speech server if one answers, otherwise captions only. Behind a login? `stagewright auth` opens a browser, you sign in however your app does (SSO, MFA, magic links), and the session is saved locally. \[Illustration\] A walkthrough file, .walkthroughs/invite-teammate.yaml: an id, the feature it covers, the source files it anchors to, and steps that each have narration, actions and an expect check. ## Run it where your code runs | Mode | Command | Needs | | --- | --- | --- | | Offline | stagewright record | No account. Chromium and ffmpeg on the machine. | | Local | stagewright run \[files\] | An API key. The browser runs here, so localhost and VPN-only apps work. Results, diffs, approvals and publishing as in the cloud. | | Cloud | stagewright run --cloud | An API key, and an app reachable from the internet. | | Your runner | runner: on an environment | A container you host. Opens no ports; polls Stagewright over outbound HTTPS. | ## Every pull request, in any CI `stagewright ci` syncs the walkthroughs, records the ones the change affects, and posts the same sticky comment and status on whichever host the pipeline runs for. Without an API key it still records and reports pass, regression or flaky, without frames or baselines, and `--out ` keeps the rendered videos as files for a CI artifact. | Host | How | What you get | | --- | --- | --- | | GitHub | The GitHub App, or stagewright ci in Actions | Walkthroughs check run, sticky comment, Stagewright Preview deployment | | GitLab (and self-managed) | stagewright ci | One merge request note, Walkthroughs commit status | | Azure DevOps (Services and Server) | stagewright ci | One PR thread, stagewright/walkthroughs status a branch policy can require | | Bitbucket Cloud | stagewright ci | One PR comment, Walkthroughs build status | ### GitHub Actions ``` # .github/workflows/stagewright.yml on: pull_request permissions: contents: read pull-requests: write checks: write deployments: write jobs: walkthroughs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: { fetch-depth: 0 } - run: npx playwright install --with-deps chromium && sudo apt-get install -y ffmpeg # PREVIEW_URL: this PR's preview deployment, from your host's earlier step - run: npx stagewright ci --base-url "$PREVIEW_URL" env: STAGEWRIGHT_API_KEY: ${{ secrets.STAGEWRIGHT_API_KEY }} GITHUB_TOKEN: ${{ github.token }} ``` ### GitLab CI ``` walkthroughs: stage: test image: mcr.microsoft.com/playwright:v1.63.0-noble rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event" variables: GIT_DEPTH: "0" script: - npx --yes stagewright@latest ci --base-url "$REVIEW_APP_URL" ``` `stagewright ci --template gitlab` (or `azure-devops`, `bitbucket`) prints a pipeline file filled in from your config. ### Exit codes
0Clean, or only results that don't block: changed, new, flaky
1A regression, or a walkthrough this change broke, that failed the same way on the second run. The only code that should block a merge
2Usage or configuration error
4A run couldn't complete (infrastructure, or the app didn't start). The check is neutral
### Claims on the PR Put `Fixes ENG-42`, or a list under a `## Claims` heading, in the PR description. Each claim is checked by replaying a walkthrough on the PR: proven, not proven or untested, decided by the replay alone, never by a model. With`claims: { block: true }` a disproved claim fails the check. ## Your coding agent can do all of this The CLI runs an MCP server, so Claude Code, Codex, Cursor and other agents can validate, record and fix walkthroughs on your machine, read a failing run with its failure screenshot and the selectors on screen, and draft walkthroughs for features with none. The Stagewright plugin adds skills, commands and a hook that checks Stagewright files as the agent writes them. ``` # Claude Code /plugin marketplace add stagewright-ai/plugins /plugin install stagewright@stagewright # Codex codex plugin marketplace add stagewright-ai/plugins # Any MCP client claude mcp add stagewright -- npx stagewright mcp claude mcp add --transport http stagewright https://api.stagewright.ai/mcp ``` The plugin's `/stagewright:init` works before anyone signs in: it scans the repo for product tours, docs navigation, recording plans and course outlines, imports them as walkthroughs and courses, and writes the config. The remote MCP server records on Stagewright's cloud runner, so it needs a public URL. \[Illustration\] Copy prompt “Give your coding agent Stagewright”. Hand this prompt to your coding agent to add the Stagewright skills and MCP server to this repo, so every teammate's agent can write and fix walkthroughs. Get the full text with: npx stagewright@latest prompt agent-setup ## Start from your Playwright tests Keep your tests where they are. `stagewright import playwright tests/todo.spec.ts` converts a test into a walkthrough (locators, actions and expectations), with narration left for a person to write. Or use the fixture: with`STAGEWRIGHT=1`, tests tagged `@walkthrough` are recorded with a paced cursor and screenshots per step, and the reporter uploads them as runs. Without it, your tests run unchanged. ``` STAGEWRIGHT=1 npx playwright test --grep @walkthrough ``` Step by step, from your first tagged test to a check on every pull request:[Record product walkthrough videos from your Playwright tests](https://stagewright.ai/guides/playwright-walkthrough-videos). Why walkthroughs belong in the repo: [docs as code, for product walkthroughs](https://stagewright.ai/docs-as-code). ``` // tests/team.spec.ts import { test, expect } from "@stagewright-ai/playwright"; test("invite a teammate @walkthrough", async ({ page, walkthrough }) => { await walkthrough.step("Open the team settings", async () => { await page.goto("/settings/team"); await expect(page.getByRole("heading", { name: "Team" })).toBeVisible(); }); await walkthrough.step("Send an invite", async () => { await page.getByLabel("Email").fill("jo@example.com"); await page.getByRole("button", { name: "Invite" }).click(); }); }); ``` ## Settings as code Everything a project is set up with, except secrets and connections, can live in `stagewright.config` (TypeScript, JSON or YAML): environments, personas, sign-in, glossary, narration tone, CI selection, locales, issue tracking, help-center mapping and the coverage map's features. A section the file defines is read-only in the dashboard and changes through pull requests. Secrets are listed by name; their values stay write-only in the dashboard or your CI. ``` stagewright config check stagewright config export --format yaml ``` Webhooks follow Standard Webhooks signing. The API returns RFC 9457 problem details and accepts idempotency keys. Full reference docs are still being written; until then, `npx stagewright --help` and the MCP tool`get_walkthrough_schema` are the reference. ``` # stagewright.config.yaml product: acme-crm baseUrl: http://localhost:3000 environments: staging: kind: staging baseUrl: https://staging.acme.internal secrets: [admin_username, admin_password] # names only runner: acme-vpn # a runner you host ci: affected: true # PRs record only what the change can touch alwaysRun: [src/lib/auth/**] i18n: locales: [en-US, de-DE, { locale: ja-JP, timezone: Asia/Tokyo }] issues: tracker: linear assign: pr_author closeOnProven: true ``` ## Record your first walkthrough 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](https://app.stagewright.ai/?waitlist)[Developer docs](https://stagewright.ai/developers)