Documentation

e2e-onboarding-playwright

docs/e2e-onboarding-playwright.md

Playwright MCP Onboarding Smoke Test

This doc captures how to run the onboarding smoke test via Codex/Claude + Playwright MCP so everyone follows the same workflow.

Prerequisites

  • Node 22+ with pnpm installed.
  • Codex CLI (Claude Code) latest build.
  • Repo cloned locally with .env.local populated for staging/test.
  • Playwright dependencies installed (pnpm install already pulls @playwright/test).

Install Playwright MCP for Codex

Pinned server: @executeautomation/playwright-mcp-server@1.0.6. Config lives in both .cursor/mcp.json and ~/.claude.json so Cursor, Codex, and Claude Code stay in sync (env vars lock browsers + artifacts inside the repo sandbox).

claude mcp add playwright -s user -- npx -y @executeautomation/playwright-mcp-server@1.0.6
claude mcp list  # should report “playwright … ✓ Connected”

Every time you touch the config, capture the CLI output in logs/mcp/<date>-playwright-setup.log for auditability.

Restart Codex, then run /mcp inside the CLI to verify the playwright server shows as healthy.

Sandbox & env expectations

  • Default env vars (defined in .cursor/mcp.json + .claude.json)
{
  "PLAYWRIGHT_BROWSERS_PATH": "/Users/tiago/Documents/Projects/petunia/node_modules/.cache/ms-playwright",
  "PLAYWRIGHT_ARTIFACTS_DIR": "/Users/tiago/Documents/Projects/petunia/tests/artifacts/onboarding"
}
  • For Docker isolation, mount only /Users/tiago/Documents/Projects/petunia read/write and pass any secrets at runtime via --env-file. Block outbound traffic except to the staging host under test.

Repo scaffolding

  • Specs live in e2e/ (created by this doc).
  • Artifacts (screenshots, traces) go into tests/artifacts/onboarding/.
  • playwright.config.ts defines defaults (base URL, retries, output dir).
  • npm scripts:
    • pnpm playwright:test
    • pnpm playwright:onboarding
    • pnpm playwright:onboarding:headed

Running the MCP workflow

  1. In Codex, open this repo and ensure /mcp lists playwright.
  2. Prompt Codex: “Use the Playwright MCP tools to generate an onboarding smoke test. Launch Chromium headful, navigate to staging, perform signup/login, go through onboarding, capture screenshots + trace into tests/artifacts/onboarding, and save the spec as e2e/onboarding.spec.ts. Add a parallel returning-user variant.”
  3. Codex will invoke the MCP server, which spins up Playwright, runs the flow, and writes:
    • e2e/onboarding.spec.ts
    • tests/artifacts/onboarding/step-*.png
    • tests/artifacts/onboarding/trace.zip
  4. After the MCP run finishes, run the spec locally to ensure it passes:
pnpm playwright:onboarding:headed

CI follow-up

Add a GitHub Actions workflow (future work) that runs pnpm playwright:onboarding headless on every PR, uploads tests/artifacts/onboarding on failures, and surfaces trace links.

Notes

  • Keep MCP server pinned; update intentionally.
  • Use test-only credentials when automating signup.
  • If staging URL changes, set PLAYWRIGHT_BASE_URL env or edit playwright.config.ts.
  • Large binary artifacts can be git-ignored; archive them elsewhere if needed.