Skip to main content
AI/MLLeeJuOh

e2e-test

Run E2E browser tests from natural language JSON test files using agent-browser. Use when asked to run e2e tests, browser tests, UI tests, end-to-end tests, or test a web application.

Stars
45
Source
LeeJuOh/claude-code-zero
Updated
2026-05-25
Slug
LeeJuOh--claude-code-zero--e2e-test
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/LeeJuOh/claude-code-zero/HEAD/plugins/e2e-test-runner/skills/e2e-test/SKILL.md -o .claude/skills/e2e-test.md

Drops the SKILL.md into .claude/skills/e2e-test.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

E2E Test Runner

Run browser E2E tests defined in natural language JSON files. Each test case gets its own Claude Code session and browser instance for full isolation. Uses agent-browser for token-efficient interaction with built-in video recording.

Quick Start

# Run tests (dev server already running)
/e2e-test tests/login.test.json

# Auto-start dev server, take screenshots
/e2e-test tests/login.test.json --run "npm run dev" --port 3000 --screenshots

# Visual regression against baseline
/e2e-test tests/login.test.json --baseline ./e2e-results/1234567890

Workflow

  1. Parse $ARGUMENTS to extract the test file path and any flags
  2. Check that the runner dependencies are installed at ${CLAUDE_PLUGIN_DATA}/node_modules. If not, run:
    cd "${CLAUDE_PLUGIN_DATA}" && cp "${CLAUDE_PLUGIN_ROOT}/scripts/runner/package.json" . && npm install --production 2>&1
  3. Verify agent-browser is installed:
    command -v agent-browser >/dev/null 2>&1 || { echo "agent-browser not found. Install: npm install -g agent-browser && agent-browser install"; exit 1; }
  4. Run the test runner:
    "${CLAUDE_PLUGIN_DATA}/node_modules/.bin/tsx" "${CLAUDE_PLUGIN_ROOT}/scripts/runner/src/index.ts" --testsPath <path> --resultsPath ./e2e-results [additional flags from $ARGUMENTS]
  5. Read ./e2e-results/test-summary.md and present the results to the user
  6. If ./e2e-results/report.html exists, mention it for detailed interactive viewing
  7. If any tests failed, point out screenshot and video locations

Test File Format

For how to write test files, see references/test-schema.md.

CLI Options

Flag Description
--testsPath, -t Path to the JSON test file (required)
--resultsPath, -o Output directory for results (default: ./e2e-results/<timestamp>)
--verbose, -v Include all Claude Code messages in output
--screenshots, -s Take screenshots at every step (not just failures)
--maxTurns Max Claude Code interactions per test (default: 30)
--model, -m Override the Claude model
--run <command> Dev server start command (e.g. npm run dev)
--port <port> Dev server port (auto-detected from framework, fallback: 3000)
--url <url> Override the URL to open (instead of http://localhost:port)
--headed Show the browser window (default: headless)
--baseline <path> Baseline results directory for visual regression diff

Gotchas

  • agent-browser required: Install globally: npm install -g agent-browser && agent-browser install. Without it, the runner exits immediately.
  • First run installs runner dependencies (~30s). Subsequent runs skip this.
  • Each test case spawns a separate Claude Code session via the SDK, so Claude login is required.
  • Video recordings are saved as .webm files per test case. They play natively in browsers.
  • If --run is omitted and --url is not set, the runner auto-detects the framework from package.json and starts the appropriate dev server. Use --run to override.
  • The dev server is killed when tests complete. If the port is already in use, the existing server is used instead.
  • Test results are saved to ./e2e-results/ by default. Each run creates a timestamped subdirectory.
  • The interactive HTML report (report.html) includes embedded video playback and expandable test details.
  • For visual regression (--baseline), screenshots are compared pixel-by-pixel. Diff images are saved as diff-step-*.png.