/dev-webtest

name: dev-webtest
description: This skill should be used when the user asks to "dev-webtest", "Webテスト", "画面の動作確認", "E2Eテスト", "web test", "visual check", "モンキーテスト", "アクセシビリティチェック", "レスポンシブテスト", "フォームテスト". Playwright CLIを使ってWebアプリの動作確認・視覚テスト・アクセシビリティ・レスポンシブ・フォームバリデーションを実行し、問題を検出・記録する。
argument-hint: '<plan-name> [--parallel N] | monkey <url> | check <url> | retest'

Dev Webtest

Playwright CLI (`@playwright/cli`) を使ったWebアプリケーションの動作確認・視覚テスト・記録スキル。計画テスト、モンキーテスト、視覚チェック、アクセシビリティ、レスポンシブ、フォームバリデーションの6種類のテストを実行し、検出した問題をエラーディレクトリに記録する。修正は dev-debug 等の別スキルに委譲する。

前提知識

dev-*スキルフロー内の位置

dev-context → dev-plan → dev-impl → dev-verify
                                         ↓
                                    [dev-webtest]
                                         ↓
                                    dev-debug (問題修正)

dev-verify でユニットテスト/ビルド/Lintが通った後にWeb画面の動作確認として使用する。単独での使用も可能。

実行モード

| モード | 引数 | 用途 | |-------|------|------| | 計画テスト | `<plan-name> [--parallel N]` | Markdownテスト計画に沿って自動テスト | | モンキーテスト | `monkey <url>` | ランダム操作でエラー・崩れを検出 | | クイックチェック | `check <url>` | 単一ページの視覚・アクセシビリティ確認 | | プラン選択 | (引数なし) | 利用可能なプラン一覧から選択して実行 | | 再テスト | `retest` | 未解決エラーの再現手順を再実行し、修正済みなら fixed に更新 |

並列実行オプション

| オプション | デフォルト | 説明 | |-----------|-----------|------| | `--parallel N` | 2 | シナリオグループの最大並列実行数（1〜5） |

• `--parallel 1` で従来通りの完全直列実行
• シナリオの `group` フィールドに基づいてグループ化し、異なるグループを並列実行する
• 同一グループ内のシナリオは `depends` 順に直列実行する

ツール構成

• **メイン**: Playwright CLI — Bash経由でコマンド実行。スナップショット(YAML)とスクリーンショット(PNG)はディスク保存
• **代替**: Playwright MCP (`@playwright/mcp`) — CLI が利用できない場合のフォールバック。MCP プロトコル経由でブラウザ操作（詳細は `references/mcp-workflow.md`）
• **補助**: Chrome DevTools MCP — パフォーマンストレース、Lighthouse監査、ネットワーク分析（利用可能時のみ）

ワークフロー

Step 1: 環境準備

Step 1 開始
    |
[1-0] docs/dev/webtests/env-knowledge.md を Read（存在する場合）
    |    → 過去のトラブルシュートを把握し、同じ問題発生時に即座に適用する
    |
[1-1] docker compose ps
    |
    +-- Playwright コンテナ Running --> [1-5] CLI動作確認・モード判定
    |
    +-- 未起動 / docker compose 自体が使えない
         |
[1-2] docker-compose.yaml の存在 + playwright サービスの定義を確認
         |
         +-- yaml あり & playwright サービス定義済み → AskUserQuestion (A0, C, D)
         +-- yaml あり & playwright サービス未定義 → AskUserQuestion (A1, C, D)
         +-- yaml なし → AskUserQuestion (B, C, D)

**1-0. 過去の環境セットアップ知見を読み込む**

`docs/dev/webtests/env-knowledge.md` が存在する場合、Read して内容を把握する。過去のトラブルシュートを参考に、同じ問題が起きた場合は記録済みの解決策を即座に適用する。

**1-1. Docker Compose の状態を確認する**

docker compose ps

Playwright コンテナが Running なら **1-5** へ進む。未起動またはコマンド自体が使えない場合は **1-2** へ。

**1-2. docker-compose.yaml の存在と playwright サービスの定義を確認する**

確認結果に応じて AskUserQuestion で環境セットアップ方法を選択してもらう。各状況で **Recommended 付きの選択肢1つ + C + D の3択** になる。

| 選択肢 | 表示条件 | 処理 | |--------|----------|------| | A0) Playwright コンテナを起動する (Recommended) | yaml あり & playwright 定義済み | `docker compose up -d playwright` → `npm install -g @playwright/cli@latest` → **1-5** へ | | A1) 既存の docker-compose.yaml に Playwright サービスを追加する (Recommended) | yaml あり & playwright 未定義 | `docker-setup.md` を参照して yaml 編集 → `docker compose up -d playwright` → `npm install -g @playwright/cli@latest` → **1-5** へ | | B) 新しい docker-compose.yaml を作成する (Recommended) | yaml なし | `docker-setup.md` を参照して yaml 新規作成 → `docker compose up -d playwright` → `npm install -g @playwright/cli@latest` → **1-5** へ | | C) 手動でセットアップする | 常に表示 | `docker-setup.md` を案内 → ユーザーに完了確認 → **1-5** へ | | D) Docker を使わずローカル MCP で実行する | 常に表示 | `docker-setup.md` の「ローカル MCP セットアップ」を参照して `.mcp.json` に playwright 設定追加 → `mkdir -p tmp/webtest/screenshots` → `.gitignore` 追記 → **MCP モード確定** → Step 2 へ |

※ A0/A1/B は排他（状況に応じて1つだけ表示）。

**1-5. CLI 動作確認・モード判定**（A0/A1/B/C 選択時のみ）

docker compose exec playwright playwright-cli --version

• 成功 → **CLI モード**（本ドキュメントの手順に従う）
• 失敗 → **MCP モード**（Docker MCP）へフォールバック（`references/mcp-workflow.md` の手順に従う）

**1-6. 環境セットアップ知見を記録する**

Step 1 完了時に `docs/dev/webtests/env-knowledge.md` に今回の知見を追記する。

• ファイルが存在しない場合は新規作成する（下記フォーマットに従う）
• **成功手順**: 今回実行した環境構築の手順を簡潔に記録する（選択した方式、実行コマンド、確定モード）
• **トラブルシュート**: Step 1 中にエラーが発生し解決した場合、症状・原因・解決策を記録する
• 既に同じ内容が記録済みの場合は追記しない（重複防止）
• 問題なくスムーズに完了した場合、トラブルシュートの追記は不要

**env-knowledge.md フォーマット**:

# Webtest 環境セットアップ知見

## 成功手順

### <YYYY-MM-DD> <モード名>モード確立
- <実行した手順の要約>
- 所要ステップ: <通過したステップ>

## トラブルシュート

### <YYYY-MM-DD> <問題の概要>
- 症状: <エラーメッセージや観察された挙動>
- 原因: <特定された原因>
- 解決: <実行した解決策>

Step 2: 引数解析とプラン解決

引数に応じてテストモードを切り替える。

**引数解析フロー:**

引数あり?
  +-- "retest"       → 2d へ
  +-- "monkey <url>" → 2b へ
  +-- "check <url>"  → 2c へ
  +-- その他の文字列 → plan-name として解釈 → プラン解決へ
  +-- 引数なし → プラン一覧表示へ

--parallel N が含まれる場合:
  → N を抽出し maxParallel に設定（デフォルト: 2、範囲: 1〜5）
  → --parallel 部分を引数から除去して上記フローを継続

**プラン解決:**

1. `docs/dev/webtests/plans/` ディレクトリを Glob で走査し、利用可能な `.md` ファイルを一覧取得する 2. 引数が plan-name の場合:

• `docs/dev/webtests/plans/<plan-name>.md` が存在する → 2a へ進む
• 存在しない → 利用可能なプラン一覧を表示し、AskUserQuestion で「実行するプランを選択してください」と提示する（複数選択可）。選択されたプランを 2a で順番に実行する

3. 引数なしの場合:

• プランが1件以上ある → AskUserQuestion でプラン一覧を表示し選択させる（複数選択可）。選択されたプランを 2a で順番に実行する
• プランが0件 → 「`docs/dev/webtests/plans/` にテスト計画がありません。`dev-webtest-plan` でテスト計画を生成するか、`monkey <url>` または `check <url>` で直接テストしてください」と案内する

4. 複数プランが選択された場合、各プランを順番に 2a で実行する。最後に Step 8 で全プランの統合レポートを出力する

2a: 計画テスト（plan-name 解決済み）

1. `docs/dev/webtests/plans/<plan-name>.md` を読み込む 2. テスト計画のフォーマットは `references/test-plan-template.md` を参照 3. テスト計画ファイルの frontmatter を更新する:

• `status` → `in_progress`
• `last-run` → 当日の日付（`YYYY-MM-DD`）

4. `mkdir -p tmp/webtest/results/<plan-name>` で中間結果ディレクトリを作成する 4-1. **APIデータセットアップの実行**（「## APIデータセットアップ」セクションが存在する場合）:

ファイル共通セットアップの実行

テスト計画の「### ファイル共通」セクション内の curl コマンドを上から順に Docker コンテナ内で実行する:

docker compose exec playwright bash -c '<curl コマンド>'

• トークン取得コマンドがある場合は、レスポンスからトークンを抽出して後続コマンドの `${TOKEN}` 等に展開する
• 各コマンドの実行結果（HTTP ステータスコード）を確認する
• 失敗した場合はエラーを記録し、ユーザーに警告を表示する（テスト自体は継続する）
• セットアップ結果のサマリーを `tmp/webtest/results/<plan-name>/api-setup.md` に記録する