Pev e2e verify

pev-e2e-verify

verifier agent の sub-skill。 npm test (unit) では検証できない UI / E2E AC を Playwright で確認する。

token 効率のため Playwright CLI ベース (npx playwright test)。 Playwright MCP は使わない (~75% コンテキスト節約、 公式推奨)。 test 生成 / 修復は Playwright が出荷する 3 agent (planner/generator/healer、 .claude/agents/ 配下の Markdown agent definitions) に委譲する。

When to Use

起動すべき場面:

• AC に UI / E2E 系の keyword が含まれる時 (verifier が auto-dispatch):
  • click / navigate / page / screen / button / form / dialog / modal / redirect / appears / visible / hidden / accessible / ARIA
• ユーザーが明示的に --e2e フラグを付けて /pev / /pev-verify を起動した時
• /pev-verify --e2e 直接呼び出し時

起動すべきでない場面:

• API endpoint の HTTP response 確認 → 通常の verifier (curl / supertest)
• 純粋な library / function の unit test → vitest 等
• AC が完全に backend 系 (DB migration / cron job / etc.)

dispatch logic は default auto-detect + explicit --e2e / --no-e2e override 可 (v1.4 設計)。

Prerequisites

• @playwright/test が プロジェクトに install済 (package.json の devDependencies)
• npx playwright install --with-deps chromium 実行済 (browser binary)
• playwright.config.ts 存在 (testDir / webServer / baseURL の設定)
• tests-e2e/seed.spec.ts 存在 (Playwright agents の前提)
• .claude/agents/playwright-test-{planner,generator,healer}.md 存在 (npx playwright init-agents --loop=claude で生成)
• .mcp.json に playwright-test MCP server 設定 (init-agents が同時に書く)

未 install の場合は pev-bootstrap-playwright skill を起動 (上記5項目を 1 コマンドで bootstrap)。

Architecture

[verifier agent]
  │ AC keyword 検知 or --e2e フラグ
  ▼
[pev-e2e-verify skill]
  │
  ├─ Step 1: preflight (playwright install 確認、 seed.spec.ts 確認、 agents 初期化済か確認)
  │   └─ 未setup → pev-bootstrap-playwright を促す
  │
  ├─ Step 2: existing test 実行
  │   └─ npx playwright test --reporter=json,html
  │       (.pev-artifacts/e2e/ に保存)
  │
  ├─ Step 3: AC に対応する test が無い → Playwright agents に委譲
  │   ├─ Planner agent → specs/<ac-slug>.md
  │   └─ Generator agent → tests-e2e/<ac-slug>.spec.ts
  │   └─ npx playwright test を再実行
  │
  ├─ Step 4: 失敗 → Healer agent (option)
  │   ├─ 失敗 step を replay
  │   ├─ patch 提案
  │   └─ 再 test
  │
  └─ Step 5: .pev-artifacts/e2e/ に結果保存 + sync_state.json 更新

Step 詳細

Step 1: Preflight (v1.3 規約準拠)

# 必須項目 5 つ
[ -f node_modules/@playwright/test/package.json ] || echo "playwright not installed"
npx playwright --version > /dev/null 2>&1 || echo "playwright CLI not available"
[ -f playwright.config.ts ] || [ -f playwright.config.js ] || echo "playwright config missing"
[ -f tests-e2e/seed.spec.ts ] || echo "seed test missing (required for Playwright agents)"
[ -d .claude/agents ] && ls .claude/agents/playwright-test-{planner,generator,healer}.md > /dev/null 2>&1 || echo "playwright agents not initialized"
[ -f .mcp.json ] && grep -q "playwright-test" .mcp.json || echo "playwright-test MCP server not configured"

不在の項目があれば warning + pev-bootstrap-playwright skill を起動するか提案。 linear-project-workflow の Preflight と同じ規約 (Read=warning continue / Write=hard fail) を踏襲。

Step 2: Existing test 実行

mkdir -p .pev-artifacts/e2e

# JSON reporter で agent-parseable + HTML reporter で人間レビュー用
npx playwright test \
  --reporter=json,html \
  --output=.pev-artifacts/e2e/test-results/ \
  2>&1 | tee .pev-artifacts/e2e/stdout.log

# json output は別 path に rename (playwright default は test-results.json)
mv test-results.json .pev-artifacts/e2e/results.json 2>/dev/null || true

reporter 選択基準:

• json: agent が parse して PASS/FAIL を判定
• html: 人間レビュー用、 失敗時の screenshot/trace 込み
• line / list: token 節約 (stdout が長くなるなら未使用)

artifacts 構造:

.pev-artifacts/e2e/
├── results.json              # machine-readable verdict
├── playwright-report/        # HTML reporter output
├── test-results/             # screenshot, trace, video
├── stdout.log                # raw stdout
└── sync_state.json           # pev-e2e-verify 動作の trace

Step 3: AC に対応する test が無い → Playwright agents 委譲

verifier が AC を見て「これは E2E test として書ける」と判断、 かつ既存 test に対応するものがない場合:

1. Planner agent invoke (.github/ 配下のMarkdown agent を Claude Code が読む)
   - input: AC 文字列 (例: "ログインボタンを押すと dashboard に遷移する")
   - output: specs/<ac-slug>.md (Markdown test plan)
2. Generator agent invoke
   - input: specs/<ac-slug>.md + tests-e2e/seed.spec.ts (ref)
   - output: tests-e2e/<ac-slug>.spec.ts (executable Playwright test)
3. Step 2 を再実行 (新規生成 test を含めて npx playwright test)

これらの agent は Playwright が用意した Markdown agent definitions で、 pev-harness 側で再実装しない。 単に .claude/agents/playwright-test-{planner,generator,healer}.md 配下にあれば Claude Code が認識する。

重要: 各 agent definition の tools: field には mcp__playwright-test__* (browser_click / browser_navigate / planner_save_plan / generator_write_test 等) が大量に listed されている。 これは Playwright が独自に提供する playwright-test MCP server (一般 playwright MCP とは別物、 test 生成専用) によって動く。 .mcp.json が config を保持する。

つまり pev-harness の verifier は:

• ✅ npx playwright test で test 実行 (CLI、 token 効率)
• ✅ test 生成 / 修復は Playwright agents に委譲 (これらは内部で専用 MCP を使う、 公式の効率的設計)

の二段構え。 pev-harness 側で MCP の用意は不要 (Playwright init-agents が自動 setup)。

Step 4: Healer agent (option、 default ON)

test が失敗した場合:

1. results.json の failure 詳細を読む
2. Healer agent invoke (.github/healer.md)
   - input: 失敗した test 名 + failure context
   - output: locator 更新 / wait 調整 などの patch
3. patch を tests-e2e/ に適用
4. 再 test (npx playwright test --grep <failed test>)
5. 再 fail → Healer 再起動 (max 2 round)
6. それでも失敗 → "Healer unable to fix" を verify.json に記録、 verifier 親 agent が判断

Healer は test side の問題 (locator drift など) を fix する。 アプリ側のバグは Healer は fix しない (planner agent に戻して retry)。

Step 5: artifacts への記録

.pev-artifacts/e2e/sync_state.json:
{
  "ran_at": "2026-05-11T...",
  "preflight": {
    "playwright_installed": true,
    "config_present": true,
    "seed_test_present": true,
    "agents_initialized": true
  },
  "test_result": {
    "total": 5,
    "passed": 4,
    "failed": 1,
    "skipped": 0
  },
  "generated_tests": [
    {"spec": "specs/login-redirect.md", "test": "tests-e2e/login-redirect.spec.ts", "via": "Planner+Generator"}
  ],
  "healer_runs": [
    {"failed_test": "...", "rounds": 1, "outcome": "fixed | unfixable"}
  ],
  "verdict": "PASS | FAIL"
}

verifier 親 agent が sync_state.json.verdict を読んで verify.json に統合する。

Examples

Example 1: AC が UI 系 (auto-dispatch)

AC: "/healthz エンドポイントに加えて、 / ページに 'Status: ok' バッジが表示される"

verifier の動作:
1. AC parse → "ページ" "表示" の keyword 検知
2. pev-e2e-verify skill auto-dispatch
3. Step 1 preflight: 全 OK
4. Step 2: 既存 test 実行 → "ステータスバッジ表示" 系 test なし
5. Step 3: Planner → specs/status-badge.md 生成
   Generator → tests-e2e/status-badge.spec.ts 生成
   再 test → PASS
6. Step 5: .pev-artifacts/e2e/ に保存

Example 2: 明示的 --e2e フラグ

/pev-harness:pev https://linear.app/.../issue/TES-99 --e2e

verifier 親 agent が --e2e=true を渡し、 pev-e2e-verify が必ず invoke される (AC keyword に関わらず)。

Example 3: --no-e2e で disable

/pev-harness:pev https://linear.app/.../issue/TES-100 --no-e2e

verifier が AC keyword を検知しても skip。 unit test のみで verdict 判定。

MCP error handling

Playwright CLI は MCP ではないが、 dependent な MCP tool (browser 操作系) を使う場合は linear-project-workflow の MCP error handling 表を参照 (single source of truth)。

Token 効率の根拠

アプローチ	Token/session
Playwright MCP	~114K
Playwright CLI (このskill)	~27K
節約	87K (~75% コンテキスト残る)

公式推奨: "If your tasks involve coding, testing, and you're using a coding agent — use CLI" (Playwright Docs)。

Limitations

• Playwright agents が .github/ 配下に init されていることが前提 (pev-bootstrap-playwright が自動 setup)
• dev server は webServer config が起動する想定 (手動起動不要)
• Healer は test side の修正のみ (アプリ側 bug は planner に戻す)
• token 制御: stdout が長すぎる場合は --quiet / --reporter=json のみに切替

Related

• pev-bootstrap-playwright — 新規プロジェクトの Playwright setup を自動化
• agents/verifier.md — dispatch logic (AC keyword + --e2e フラグ)
• commands/pev-verify --e2e.md — explicit invocation
• Playwright 公式: https://playwright.dev/docs/test-agents
• 設計判断: 2026-05-11 dog food session 後の v1.4 design (CLI 採用、 token 効率最重視)