| name | playwright-scenario-test |
| description | pytest-playwright 上の Web シナリオ E2E テスト実施フレームワーク。HTSM / ISTQB / FEW HICCUPPS に基づき page role 別の checklist + 必須技法マッピングを内蔵し、accessibility (axe-core) / Core Web Vitals 自動計測 + Playwright trace / HAR / 動画 / Markdown レポート + Google Drive 共有を pytest fixture / hook として提供する。v0.5.0 で利用者プロジェクトに all-in-one ディレクトリを埋め込む Skill 非依存構成へ移行。 |
| when_to_use | E2E テスト計画立案 / 不具合エビデンス収集 / 動画レポート / Google Drive 共有が必要なとき。LP / 一覧 / 詳細 / 編集 / 申込フォーム / 検索 / ダッシュボード / 認証 / カート / チェックアウト / モーダル / ウィザード / 設定 / エラーページ など page role 別の理論ベースチェックを行う。Triggers: 'E2E テスト', 'シナリオテスト', '動画エビデンス', 'Playwright', 'pytest-playwright', 'リリース前確認', '回帰テスト', 'a11y テスト', 'accessibility テスト', 'Core Web Vitals', 'Web Vitals', 'page role', 'pwk_role', 'pwk_evidence' |
| allowed-tools | ["Read","Bash(uv *)","Bash(pytest *)","Bash(playwright *)","Bash(python *)"] |
Playwright シナリオテスト Skill (v0.5.0)
Web アプリの E2E シナリオを 理論ベース で計画し、pytest-playwright 上で実行、動画 + Markdown レポート + accessibility / web vitals を自動収集する一式の Skill。
v0.5.0 の方針: 本 Skill は「テストを書き始めるためのスキャフォルダ」であり、scripts/init_project.sh で利用者プロジェクトに all-in-one ディレクトリ を埋め込んだ後は、Skill ディレクトリの存在に依存せず単独で動作する (CI / 別マシン / Skill 非導入のメンバー環境でも完結)。
用語集
ドメイン略語と正式名・意味の対応表。
| 略語 / 用語 | 正式名 / 意味 |
|---|
| accessibility (旧 a11y) | Web アクセシビリティ。WCAG 準拠を axe-core で機械検査 |
| web vitals (旧 CWV) | Google が定義する「ユーザ体感パフォーマンス指標」群 |
| LCP | Largest Contentful Paint — 最大コンテンツ描画時間 (体感ロード速度) |
| CLS | Cumulative Layout Shift — 累積レイアウトずれ量 (視覚的安定性) |
| TTFB | Time To First Byte — 初バイト到達時間 (サーバ応答速さ) |
| longest_task | Long Tasks API で観測した最長タスクのミリ秒値 (応答性代理指標) |
| HAR | HTTP Archive — ネットワーク通信ログのファイル形式 |
| trace | Playwright Trace — DOM スナップショット + 操作ログ + 動画の zip |
| overlay (旧 HUD) | テスト中に画面に重ねる赤丸カーソル + 字幕表示 |
| body_check | サーバが HTML 本文に出力した PHP/SSR エラー文字列の検出 |
| page role | LP / 一覧 / 詳細 / フォーム 等のページ種別。a11y / web vitals 自動実行の判定材料 |
| pwk | playwright_kit の略。fixture (pwk_*) / CLI option (--pwk-*) / env (PWK_*) の prefix |
提供物
playwright-scenario-test/ ← Skill 自体 (この Skill ディレクトリ)
├── SKILL.md ← このファイル
├── pyproject.toml ← Skill 開発用 (pytest entry-point 含む)
├── playwright_kit/ ← Python パッケージ本体 (旧 scenario_test)
│ ├── pytest_plugin.py ← pytest11 entry-point (addoption / markers / hooks)
│ ├── pytest_report.py ← report.md 生成
│ ├── fixtures/ ← pytest fixtures
│ │ ├── auth.py — pwk_config / pwk_role_<id>
│ │ ├── evidence.py — pwk_evidence (HAR / trace / console / pageerror)
│ │ ├── accessibility.py — page_role marker autouse で axe-core
│ │ ├── web_vitals.py — page_role marker autouse で Core Web Vitals
│ │ └── body_check.py — page.on("response") で本文エラー文字列を検出
│ ├── accessibility.py / web_vitals.py — axe-core / Web Vitals ランナー (純関数)
│ ├── overlay.py ← 赤丸カーソル + 字幕 (旧 HUD) JS
│ ├── video.py ← webm → mp4 変換
│ └── config.py ← scenario.config.yaml ローダ
├── docs/ ← テスト方法論 (HTSM / ISTQB / FEW HICCUPPS)
├── scripts/
│ ├── init_project.sh ← all-in-one 初期化 (rsync ベース)
│ ├── init_project.bat ← 同 Windows 版 (xcopy ベース)
│ ├── classify_page_role.py / run_a11y_scan.py / check_cwv.py / record_scenario.py
│ └── upload_evidence.py / gdrive_upload_dir.py / build_gdoc_with_drive_links.py
└── templates/ ← 利用者プロジェクト用雛形
├── pyproject.toml.runtime — runtime 用 pyproject (dev 用 deps を排除)
├── runtime-gitignore — .venv / __pycache__ / reports/
├── runtime-README.md — Skill 無し環境向けの最低限の使い方
├── run.sh / run.bat — ワンコマンドランチャ
├── scenario.config.yaml — base_url / roles / accessibility / web_vitals 設定
├── conftest.py.template — 利用者の conftest.py 雛形
└── test_*.py.template — auth / list / form / dashboard 雛形
init 後の利用者プロジェクト側 (Skill 非依存):
your-app/
└── scenario-test/ ← all-in-one ランタイム (--runtime-dir で名前変更可)
├── playwright_kit/ ← Python パッケージ本体
├── scripts/ ← 補助 CLI
├── tests/ ← 利用者の pytest テスト
│ ├── conftest.py
│ └── test_*.py
├── reports/ ← 実行結果 (.gitignore 推奨)
├── scenario.config.yaml ← 利用者の設定
├── run.sh / run.bat ← ワンコマンドランチャ
├── pyproject.toml ← runtime 用 (testpaths=["tests"])
├── uv.lock ← 再現性のため commit 推奨
└── README.md ← runtime-README.md コピー
クイックスタート
cd .claude/plugins/ndf/skills/playwright-scenario-test
./scripts/init_project.sh /path/to/your-app
./scripts/init_project.sh /path/to/your-app --runtime-dir e2e
scripts\init_project.bat C:\path\to\your-app
$EDITOR /path/to/your-app/scenario-test/scenario.config.yaml
$EDITOR /path/to/your-app/scenario-test/tests/test_admin.py
cd /path/to/your-app
./scenario-test/run.sh
./scenario-test/run.sh -k test_admin
./scenario-test/run.sh --pwk-overlay
./scenario-test/run.sh --pwk-drive-folder=<ID>
→ 以降このディレクトリ (Skill) は不要。your-app/scenario-test/ 単体で完結する。
複数ランタイム共存
./scripts/init_project.sh your-app --runtime-dir e2e-prod
./scripts/init_project.sh your-app --runtime-dir e2e-staging
利用者は通常の pytest テストを書く
import pytest
from playwright.sync_api import Page, expect
@pytest.mark.page_role("dashboard")
@pytest.mark.role("admin")
def test_admin_kpi_view(page: Page, pwk_role_admin):
page.goto("/admin/dashboard")
expect(page.get_by_role("heading", name="売上サマリ")).to_be_visible()
page.get_by_role("link", name="ユーザ管理").click()
expect(page).to_have_url(lambda u: "/admin/users" in u)
提供 fixture / marker:
| 提供 | 種別 | 役割 |
|---|
pwk_config | session fixture | scenario.config.yaml をロード (Config dataclass) |
pwk_role_<id> | function fixture (動的) | 該当 role で login 済の storage_state を context に注入 |
pwk_evidence | function fixture | HAR / trace / console.error / pageerror / body_check の集中管理 |
pwk_accessibility_scan() | helper | 任意のタイミングで axe-core を 1 回実行 |
pwk_web_vitals_measure() | helper | 任意のタイミングで Web Vitals を 1 回計測 |
pwk_body_check_scan() | helper | 任意のタイミングで現在の page 本文を 1 回 body_check |
@pytest.mark.page_role("form") | marker | accessibility / web_vitals autouse の判定 (auto_roles 設定に従う) |
@pytest.mark.role("admin") | marker | report.md 集計用 (login 自体は pwk_role_<id> fixture) |
@pytest.mark.phase(1) | marker | report.md フェーズ集計 |
@pytest.mark.priority("high") | marker | report.md ソート |
@pytest.mark.no_body_check | marker | body_check autouse をこの test では skip |
body_check (PHP / SSR エラー検出, v0.4.0+)
PHP / SSR が HTML 本文に直接出力した Fatal error / Warning: / STRICT: 等の
エラー文字列は console.error / pageerror では拾えない。body_check は
page.on("response") で全 HTML レスポンスを監視し、文字列パターンとの substring
一致で violation を記録する。default で enabled + PHP 系パターン内蔵 なので、
config を書かなくても PHP プロジェクトでまず動く。
パターンを上書きしたい場合のみ scenario.config.yaml で明示する:
body_check:
enabled: true
fatal_patterns: ["Fatal error", "Uncaught", "Parse error"]
warning_patterns: ["STRICT:", "Warning:", "Notice:", "Deprecated:"]
warning_head_chars: 300
not_found_patterns: ["File not found"]
fail_on_match: true
- 違反は
case_dir/body_check.jsonl に 1 violation = 1 行で出力 (jq/grep
で集計しやすいよう flat structure にしている)
report.md のサマリ表に body_check カラムが、件数 > 0 の場合は詳細セクション
(URL / pattern / snippet) が出力される- 機能ごと無効化したい場合は
body_check.enabled: false を明示
- 個別カテゴリのみ無効化したい場合は
fatal_patterns: [] のように明示空指定
- 個別 test で skip したい場合は
@pytest.mark.no_body_check を付与
- 非 PHP プロジェクトでは default の
Notice: / Warning: 等が誤検出になる
場合あり。その場合は warning_patterns: [] で warning カテゴリだけ無効化するか
enabled: false で機能ごと off にする
CLI options
ランチャ経由 (./run.sh / run.bat) でも、uv run pytest を直接呼んでも、同じ option がそのまま効く。
| option | 役割 |
|---|
--pwk-config <path> | scenario.config.yaml のパス。env PWK_CONFIG / CWD の同名ファイルでも可 |
--pwk-out-dir <path> | 成果物出力先 (default: reports/<run-id>/) |
--pwk-no-evidence | HAR / trace / video の収集を OFF |
--pwk-har-mode {minimal,full,none} | HAR 録画モード (default: minimal、Issue #62) |
--pwk-overlay | overlay (赤丸カーソル + 字幕、旧名 HUD) を全 page に inject |
--pwk-drive-folder <id> | session 終了時に report.md と evidence を Drive アップロード |
pytest 標準と組み合わせて使える:
./scenario-test/run.sh -m "page_role"
./scenario-test/run.sh -n 4
./scenario-test/run.sh --pwk-drive-folder=<FOLDER_ID>
./scenario-test/run.sh --html=reports/index.html --self-contained-html
標準ワークフロー (理論ベース計画)
[A] 対象 URL を渡される
│
[B] page role を判定 scripts/classify_page_role.py --url <URL>
▼
[C] 該当 checklist を開く docs/checklists/checklist-{role}.md
│ 全項目を「適用」or「不適用 (理由付き)」で判定
▼
[D] 必須技法を確定 docs/03-test-techniques.md § 11
▼
[E] pytest テストを書く templates/test_<role>.py.template を起点に
│ `playwright codegen` で操作 → そのまま test 関数に貼る or 整形
▼
[F] 実行 ./scenario-test/run.sh
│ trace.zip / video / HAR / console / accessibility / web_vitals を自動収集
▼
[G] レポート確認 scenario-test/reports/<run-id>/report.md
│ --pwk-drive-folder 指定で Drive にアップロード + viewer URL 化
▼
[H] 不具合発見 → bug report docs/05-bug-report.md
FEW HICCUPPS の oracle 軸を必ず付与
単発 CLI ツール (補助)
| Script | 用途 |
|---|
scripts/classify_page_role.py --url <URL> | a11y tree + URL pattern + role 集計から page role 推定 |
scripts/record_scenario.py <URL> | Playwright codegen を起動し操作を Python コードで取得 |
scripts/run_a11y_scan.py --url <URL> | axe-core 単発スキャン |
scripts/check_cwv.py --url <URL> | Web Vitals (LCP/CLS/TTFB) 単発計測 |
scripts/upload_evidence.py <file> --kind trace --public | Drive アップロード + Playwright Trace Viewer URL 生成 |
docs/ 配下 (理論ベース知識)
| ファイル | 内容 |
|---|
docs/01-methodology.md | 総論: HTSM / FEW HICCUPPS / ISO 29119-3 の位置付け |
docs/02-page-roles.md | page role 分類 (lp/list/item/edit/form/search/...) |
docs/03-test-techniques.md | テスト技法 (EP / BVA / Decision Table / Pairwise) と role 必須マッピング |
docs/04-playwright-mapping.md | Playwright API → role / 観点 マッピング |
docs/05-bug-report.md | bug report 仕様 (ISO 29119-3 + FEW HICCUPPS) |
docs/06-pytest-playwright.md | pytest-playwright fixture / CLI option / playwright_kit 拡張との対応関係 |
docs/checklists/checklist-<role>.md | role 別チェックリスト (lp/list/item/edit/form/search/dashboard/auth/cart-checkout/modal-wizard/common) |
テスト雛形 (templates/)
利用者は role に応じて test_<role>.py.template をコピーして編集する (init 時に
4 ファイルが配置済)。各テンプレートには:
- 該当
page_role marker
- 該当
pwk_role_<id> fixture
expect() ベースの web-first assertion- 正常系 + 1 件以上の異常系
が含まれる。
開発者向け: Skill 単体で動かす旧運用
Skill 自身の改修・テスト時のみ、Skill ディレクトリで直接 pytest を回す:
cd .claude/plugins/ndf/skills/playwright-scenario-test
uv sync
uv run pytest -q
利用者環境向け (init_project.sh 経由) と Skill 開発用は 別の uv プロジェクト
として分離される (利用者側は templates/pyproject.toml.runtime を用い、開発側は
リポジトリルートの pyproject.toml を用いる)。
制約 / 注意
- 依存:
pytest>=8.0, pytest-playwright>=0.5, pytest-xdist>=3.0, playwright>=1.50
- 認証情報は YAML に直書きしない:
scenario.config.yaml の fields.Password 等は ${ENV_VAR} で参照し、実値は環境変数 (.env / direnv / shell export) で管理してください。リポジトリに認証情報をコミットしないこと
- トレース / HAR / 動画は機微情報を含む:
- HAR には URL のクエリ文字列・Cookie・Authorization ヘッダ等が記録されます
- trace.zip には localStorage / 操作履歴 / DOM スナップショットが含まれます
--pwk-drive-folder=<id> は private folder を指定し、共有相手を限定してくださいupload_evidence.py --public を付けない限り Drive にも非公開でアップ (既定)
- CI: GitHub Actions では
cd scenario-test && uv run pytest -n auto でそのまま回せる
- Skill 更新時の追従: 開発中につきコピー済ランタイムは再
init_project.sh で
上書き運用 (scenario.config.yaml / tests/conftest.py / tests/test_*.py は
既存があれば skip するため利用者編集物は保護される)
関連ドキュメント
docs/README.md — 知識マップtemplates/scenario.config.yaml — 設定例templates/runtime-README.md — init 後の your-app/scenario-test/README.md 元
