@stagewright-ai/playwright

Turn your existing Playwright tests into narrated product walkthroughs with Stagewright. A fixture records them, and a reporter uploads them.

npm install -D @stagewright-ai/playwright

Fixture

// 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("[email protected]");
    await page.getByRole("button", { name: "Invite" }).click();
  });
});

Normal runs are unchanged: walkthrough.step is test.step. With STAGEWRIGHT=1 the fixture draws a cursor, records video, paces actions so they're watchable, and writes a timeline and a screenshot per step under the test's output folder. The test timeout is multiplied by 3.

Reporter

// playwright.config.ts
import { defineConfig } from "@playwright/test";
import type { StagewrightOptions } from "@stagewright-ai/playwright";

export default defineConfig<StagewrightOptions>({
  use: { baseURL: "http://localhost:3000", stagewright: { actionDelayMs: 600 } },
  reporter: [["list"], ["@stagewright-ai/playwright/reporter", { product: "my-app" }]],
});

STAGEWRIGHT=1 STAGEWRIGHT_API_KEY=ak_... npx playwright test --grep @walkthrough

The reporter does nothing unless STAGEWRIGHT=1. It uploads every recorded test as a run, and syncs tests tagged @walkthrough as walkthroughs. Options: apiUrl, apiKey (defaults to STAGEWRIGHT_API_URL / STAGEWRIGHT_API_KEY, then the stagewright login credentials), product (defaults to STAGEWRIGHT_PRODUCT), enabled.

Pacing options (under use.stagewright): actionDelayMs (400), settleMs (700), typingDelayMs (45), typeFills (true), maxTypedLength (60), glide (true), glideTimeoutMs (2000), timeoutMultiplier (3).

Needs @playwright/test 1.50 or newer and Node.js 22.18 or newer.

License

MIT