Dev Webtest

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画面の動作確認として使用する。単独での使用も可能。

実行モード

並列実行オプション

• --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/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 に記録する

シナリオ固有セットアップの事前パース

「### シナリオN固有」セクションの内容をパースし、シナリオ名と curl コマンドの対応を記録する。実際の実行は各シナリオの直前に行う（Step 5-3 の Agent 委譲時にシナリオ固有セットアップも渡す）。

5. シナリオをグループ化し、グループ単位で並列実行する:

5-1. グループ化

シナリオの group フィールドに基づいてグループ分けする:

• group が同じシナリオは同一グループ（グループ内は depends 順に直列実行）
• group が未指定のシナリオはそれぞれ独立グループとして扱う（他と並列実行可能）
• depends が未指定のシナリオはグループ内の記述順に実行する

例: 4シナリオ（group: auth×2, group: products×1, group未指定×1）
  → グループ: [auth], [products], [シナリオ4]
  → maxParallel=2 の場合: [auth] と [products] を並列 → 完了後 [シナリオ4]

5-2. 並列実行制御

• maxParallel（デフォルト: 2）に基づき、同時実行するグループ数を制限する
• グループのキューを作成し、空きスロットができたら次のグループを開始する
• 具体的には: maxParallel 個のグループを Agent tool で 同時に起動（run_in_background: true）し、完了通知を受けたら次のグループの Agent を起動する
• maxParallel: 1 の場合は従来通りの完全直列実行となる

5-3. Agent 委譲（グループ単位）

1グループにつき1つの Agent を起動する。Agent にはグループ内の全シナリオを渡し、グループ内のシナリオは depends 順に直列実行 させる:

• Agent には以下を伝える:
  • 実行モード（CLI / MCP）とセッション情報
  • グループ内の全シナリオの手順・期待結果・視覚チェックポイント（テスト計画から該当部分を抽出）
  • 各シナリオのAPIシナリオ固有セットアップ（curl コマンド、存在する場合のみ）
  • ファイル共通セットアップで取得したトークン（${TOKEN} 等の値）
  • 各シナリオの結果の書き出し先: tmp/webtest/results/<plan-name>/<scenario-index>-<scenario-name>.md
  • エラー時の error.md 作成先: docs/dev/webtests/errors/
  • snapshot・screenshot の取り扱いルール（後述の「ルール・制約」を参照）
• Agent はグループ内の各シナリオについて以下を実行する: a-0. シナリオ固有セットアップがある場合、curl コマンドを Docker 内で実行する:

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

  • ${TOKEN} 等のプレースホルダはファイル共通セットアップで取得した値に展開する
  • 失敗した場合はエラーを記録し、シナリオを skipped として結果に記録する（次のシナリオに進む） a. シナリオの手順を実行（Step 2a 操作） b. Step 3 + Step 4: 視覚チェック + アクセシビリティチェック（同時実行可能 — どちらも読み取り専用のため。snapshot を取得した時点で Step 3 は screenshot を Read して判定、Step 4 は snapshot を分析。ただし Tab キーボードテストは Step 3 完了後に実行する） c. Step 5: レスポンシブテスト（viewport 変更を伴うため単独実行） d. Step 6: フォームバリデーションテスト（ページ状態を変更するため最後に実行） e. 問題検出時は error.md を作成 f. 結果を scenario 中間ファイルに書き出す（フォーマットは後述）
• Agent の返却値は「完了。passed/failed（N件中M件成功）。結果ファイルパス一覧」程度の短い文字列とする
• シナリオが failed でも中断せず、グループ内の次のシナリオを継続する

6. 全グループ完了後、APIクリーンアップを実行する（「## APIクリーンアップ」セクションが存在する場合）:

   テスト計画の「## APIクリーンアップ」セクション内の curl コマンドを上から順に Docker コンテナ内で実行する:

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

   • ${TOKEN} / ${ADMIN_TOKEN} 等のプレースホルダはセットアップ時に取得した値に展開する
   • 各コマンドの実行結果を確認するが、クリーンアップ失敗はエラーとして記録するのみでテスト結果には影響しない
   • クリーンアップ結果のサマリーを tmp/webtest/results/<plan-name>/api-cleanup.md に記録する

7. テスト計画ファイルの frontmatter status を更新する:

   • 全シナリオが passed → status: done
   • 1つでも failed がある → status: in_progress

8. Step 7 → Step 8 に進む

scenario 中間ファイルフォーマット

Agent が tmp/webtest/results/<plan-name>/<scenario-index>-<scenario-name>.md に書き出す:

---
scenario: "<シナリオ名>"
url: "<テスト対象URL>"
result: passed | failed | skipped
---
## APIセットアップ: <成功/失敗/なし>
- <セットアップの実行結果（1行。なしの場合は「シナリオ固有セットアップなし」）>

## シナリオ結果: <passed/failed/skipped>
- <結果の要約（1-2行）>

## 視覚チェック: <判定>
- <所見（1-2行）>

## アクセシビリティ: <判定>
- 画像alt: <判定> (N/M)
- フォームラベル: <判定> (N/M)
- Heading階層: <判定>
- キーボード: <判定> Tab到達率 N% (N/M)
- ARIA: <判定>
- ランドマーク: <判定>

## レスポンシブ: <判定>
- mobile: <判定> <所見>
- tablet: <判定> <所見>
- desktop: <判定> <所見>

## フォームバリデーション: <判定>
- <パターン>: <判定> | ...

## 検出エラー
- <error.md へのパス>（エラーがない場合は「なし」）

2b: モンキーテスト（monkey 指定時）

1. 指定URLにアクセスする
2. snapshot でページ構造を把握する
3. 以下のアクションをランダムに実行する（最大20アクション）:
   • リンクのクリック
   • ボタンのクリック
   • フォームへのランダム入力（正常値・異常値・空値・境界値）
   • ナビゲーション（戻る・進む）
4. 各アクション後に以下を確認する:
   • snapshot でページ状態を取得
   • console でJavaScriptエラーを確認
   • network でHTTPエラー(4xx/5xx)を確認
5. 問題検出時は screenshot を取得する
6. 問題検出時はエラーディレクトリを作成する:
   • docs/dev/webtests/errors/<YYYY-MM-DD>-<NNN>-<概要>/error.md を作成
   • tmp/webtest/errors/<YYYY-MM-DD>-<NNN>-<概要>/screenshot.png にスクリーンショットを保存
7. 同一ドメイン内のみ遷移する。外部リンクはスキップする

2c: クイックチェック（check 指定時）

1. 指定URLにアクセスする
2. screenshot + snapshot を取得する
3. Step 3（視覚チェック）と Step 4（アクセシビリティ）のみ実行する
4. 結果を直接ユーザーに報告する（レポートファイルは作成しない）