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.