automated-e2e-testing

自動化 E2E テスト（automated-e2e-testing）

このスキルでは、Web アプリケーションの自動テストに関する一連のワークフローを扱います。手動テストケース（markmap + Schema）を Playwright spec に変換し、実行して検証し、Bug を発見してテストレポートを出力します。

主な原則：

1. テストを書く前に、まず業務を理解する — 機能に詳しくない場合は、まず自動化スクリプトでシステムを能動的に探索し、実際の動作を理解してからテストコードを書き始めます。
2. 疑問があれば質問し、自分で仮定しない — 作成中に不明な点があれば、必ずユーザーに質問して確認します。推測でコードを書くことは決してありません。
3. 自動化テストケースは手動テストケースと1対1で対応させ、各 test では1つの項目だけをテストします
4. 各 test を独立させます（データを自前で作成し、自前でクリーンアップします）
5. Page Object を必ず使用します — 正式なテストでロケーターを直接記述することは禁止です。すべてのページ操作を Page Object にカプセル化します。

プロジェクトの規約（スキャフォールディング、設定、シナリオコードのテンプレート、Page Object の規約）は references/playwright-conventions.md にまとめています。コードを書く際に読み込んでください。共通 Helper（ログイン、複数セッション、証拠収集）の参考実装は references/helpers_reference.md にあります。型の適用範囲に応じた3種類の実行スニペット（a11y スキャン／ビジュアルベースライン／複数ブラウザマトリックス）については、プロジェクト規約の第12～14節を参照してください。type_scope が該当する軸に分類された場合は、その段階で読み込んで使用します。

使用する場面

• テストケース（markmap / Schema）が与えられ、Playwright spec ファイルを生成して実行する必要がある場合
• 自動化コードを書く前に、小規模な業務理解のための探索が必要な場合（ページ構造の確認、セレクターの抽出）
• 自動化の実行中に Bug が見つかり、証拠を収集してテストレポートの項目に記録する必要がある場合
• 新しい Page Object または Helper 関数を書く必要がある場合

使用しない場面

• 要件全体のエンドツーエンドテスト（理解→戦略→テストケース→実行→レポートのパイプライン）→ qa スキルで統括します
• 手動テストケースの作成 → test-case-writing スキルを使用します
• 純粋な API インターフェーステスト（Web UI のフローなし）→ api-testing スキルを使用します
• システムの理解／リスクの発見を目的とする独立した探索的テストセッション（charter 主導で、探索メモを成果物とする場合）→ exploratory-testing スキルを使用します。このスキルのワークフローゼロで行うのは、「自動化を書くための事前確認」を目的とした小規模な探索のみです
• 確認済み Bug の根本原因の特定、影響分析、回帰テストの提案 → bug-analysis スキルを使用します。このスキルでは Bug の証拠（スクリーンショット／API／コンソール）の収集と、レポート項目の記録のみを行います
• コード変更後に回帰テストの範囲を判断する場合 → regression-testing スキルを使用します
• 単体テスト → Jest/Vitest を使用します。パフォーマンス負荷テスト → 専用ツール（k6、locust）を使用します。セキュリティテスト → セキュリティ監査の専用手順を使用します（test-strategy の handoff 規約を参照）

質問するタイミング（必ず遵守）

基本ルール：不確かな点は質問してください。推測するより、確認のために質問することを優先します。 形式と判断規則は ../core/clarify-pattern.md に統一されています（シナリオでは「実行確認」を使用）。

場面	質問する内容	自分で仮定しないこと
要素の特定に失敗した場合	「{ページ}で{要素}が見つかりません。実際のページ構造は想定と一致していますか？」	セレクターを安易に変更して推測しない
操作経路が不明確な場合	「テストケースには{操作X}とありますが、ページ上に直接の入口がありません」	操作手順を自分で組み立てない
期待される動作に曖昧さがある場合	「{結果A}を期待していますが、実際は{結果B}です。どちらを基準にすべきですか？」	どちらか一方を都合よく信じない
業務ルールが不明確な場合	「ルール{X}の具体的な境界はどこですか？」	一般的な既定値で代用しない
探索中に異常を発見した場合	「{異常な動作}を発見しました。これは想定どおりの動作ですか、それとも Bug ですか？」	Bug か仕様かを自分で判断しない
テストケースが繰り返しタイムアウトする／不安定な場合	「{ページ}には、ページがいつまでもアイドル状態にならない原因となる長時間接続やポーリングによるプッシュ（WebSocket/SSE/ハートビート送信）がありますか？」	常に networkidle 待機を使わず、待機の段階的なフォールバックに従う

ワークフローゼロ：業務理解（事前に必須。自動化のための小規模な事前確認）

実施が必要な場合：対象の機能モジュールをテストしたことがない／不慣れなページルートがある／新しい Page Object を作成する必要がある／テストケースを受け取ったものの、システムの画面構成が分からない場合

このワークフローは小規模な事前確認のための探索（ページ構造の把握、セレクターの抽出、Page Object の作成）であり、その成果はワークフロー一で使用します。システムの理解／リスクの発見を目的とする本格的な探索セッション（charter 主導で、探索メモを成果物とする場合）は exploratory-testing スキルを使用します。

手順

1. ページ構造を探索する：ログイン → 対象ページに移動 → スクリーンショットを撮る → 操作可能な要素をすべて列挙する
2. 主要なフローを体験する：テストケースの手順に沿ってフロー全体を実行し、各手順でスクリーンショットを撮り、API 呼び出しを記録する
3. 発見した内容を記録する：ページ間の移動経路、主要な要素のセレクター、API インターフェース、隠れた動作、Page Object の作成または更新

探索コードのテンプレートは references/playwright-conventions.md 第4節（explore-*.spec.ts）を参照してください。

完了基準

• 対象となる各ページのスクリーンショットがある
• ページ間の移動経路を理解している
• 主要な要素のセレクターを確認している
• 実際の API リクエストを記録している
• 隠れた動作（非表示フィールド、既定値、前提条件）を発見している
• 対応する Page Object を作成または更新している

---

ワークフロー一：手動テストケース → 自動化コード

前提条件：ワークフローゼロ（業務理解）を完了し、対象の機能を十分に理解していること。

テストケースの入力と自動化範囲の判定

入力は test-case-writing が作成した markmap テストケースファイルです（测试用例.schema.yaml が含まれる場合は、あわせて使用します）。

• Schema の execution_model: ui かつ automation.supported != no のテストケース → このワークフローで変換します
• execution_model: dev-collab（UI を使わない協調テストケース）→ api-testing に引き継ぐか、手動で協調して実行します。無理に UI 自動化を作成しません
• automation_plan が存在する場合は（test-strategy が作成）、ユーザーの実行戦略に従って判断します。戦略が未確定の場合は、どのテストケースを自動化するかユーザーに確認します

手順

1. テストケースを解析する：markmap Markdown からシナリオと期待結果を抽出します。test 名にはテストケースの TC 番号をそのまま使用します（例：TC-01-03: {テストケース名}）。手動テストケースに番号がない場合は、変換前に番号を補います
2. Page Object を選択／新規作成する：tests/pages/ の下に該当する Page Object があるか確認し、既存のものを優先して再利用します
3. spec を作成する：すべてのページ操作を Page Object にカプセル化します。各 test の作成を終える前に、アサーションの3つの確認事項を確認します。① 前提条件に「一致してはならない／除外されるべき」データはありますか？「含まれない」ことのアサーションを網羅していますか？② テスト対象の手順の実行方法はテストケースの仕様と一致していますか（不安定さを避けるために実行経路を変更してはなりません）？③ 失敗した場合、「機能の不具合」と「環境の未読み込み」を区別できますか？——判断基準と反例はプロジェクト規約の第15節を参照してください
4. 実行して検証する：npx playwright test tests/{ファイル名}.spec.ts を実行します。ベースラインで1件も成功しない状態では納品できません——初回実行で成功が0件の場合、フローの理解に誤りがあるとみなします（セレクター／ダイアログ構造／待機の想定が実際のページと一致していない状態です）。ワークフローゼロに戻って対象を再確認し、修正して再実行し、1件以上成功してから次の手順に進みます。ベースラインで成功が0件の spec を納品することは禁止です

スキャフォールディング、シナリオコードのテンプレート（CRUD／フォーム送信／状態遷移／複数ユーザーの並行処理）、Page Object の規約、spec の命名については、この段階で references/playwright-conventions.md を読み込みます（第1、5～7節）。

---

ワークフロー二：Bug の探索と記録

業務ロジックを理解したうえで、ページの機能を体系的に検証し、Bug や不整合を発見します。

複数の失敗が発生した場合の事前振り分け：1回の実行で失敗が3件以上の場合、まず ../core/triage.md を読み込んで4分類（A 真の欠陥／B アセットの問題／C 環境／D 不安定）を行います。このワークフローで証拠収集とレポート項目への記録を行うのは、A 分類のみです。3件未満の場合は、従来どおり個別のフローを維持します。

headless パイプラインのシナリオ（PR スモークテスト／夜間の全件実行／リリースのゲート）：チェックポイントの降格による未解決項目の扱い、成果物の保存規約、終了コードの意味については ../core/pipeline-integration.md に従います（この段階で読み込みます）。このフローに戻ってきた後の複数失敗も、上記の振り分けフローの対象となります。

担当範囲：このワークフローでは発見＋証拠収集＋レポート項目への記録を行います。Bug が確認された後の根本原因の特定、影響分析、回帰テストの提案は bug-analysis スキルに引き継ぎます（対応するレポート項目の拡張フィールド5つのうち、根本原因分析などは TODO のままにします）。

Bug 发现策略

策略	检查方式	典型 Bug
UI 预期不一致	对比测试用例与实际截图	默认值不对、文案错误
表单校验缺失	提交非法数据	必填不校验、范围不限制
网络异常	监听 API 响应	500 错误、超时
数据不一致	操作后 reload 验证	提交成功但数据丢失
状态流转错误	多步操作验证状态	状态未更新、卡死
控制台错误	setupConsoleLogging(page) 持续监听	组件崩溃、静默失败

Bug 证据收集（发现 Bug 时必须执行）

Bug 发现 → 截图操作前 → 操作触发异常 → 截图操作后 → 收集 API/控制台日志 → 写入报告

证据收集代码（setupBugTracking / tracker.collect）见 references/playwright-conventions.md 第 8 节；通用 Helper 落地时加载 references/helpers_reference.md。

截图命名统一小写 bug-{序号}-* 前缀：手动截图记录过程两态（bug-001-01-操作前.png、bug-001-02-异常.png）；tracker.collect() 自动补一张整页汇总截图（bug-001-汇总.png）并 attach 到 HTML 报告。Bug 报告标题中的 BUG-{序号} 仅为显示格式。

Bug 报告格式

记录在 {项目名}/测试报告_{来源}_{日期}.md，条目字段与 ../core/report-template.md §3（测试报告唯一来源模板，此时加载）保持一致，保证条目可直接拼装进 qa 收尾的最终报告；本 skill 的发现方式含「业务熟悉探索」。执行分报告还需包含 §2 执行统计（P0/P1/P2 × 用例数/通过/失败/阻塞/未执行表，同样按 report-template）；条目中根因分析等五个扩展字段留 TODO，由 bug-analysis 填写。按 report-template「机读摘要」约定，分报告末节追加机读摘要片段（占位符替换后），供 qa 收尾与后续回归编排机读解析。

---

Explore 文件生命周期管理

业务熟悉探索文件（explore-xxx.spec.ts）是临时产物，遵循以下生命周期：

创建 explore-xxx.spec.ts → 提取知识到 Page Object → 删除 explore 文件 + 截图

规则

1. 知识提取后立即删除：将发现的选择器、API 路径、页面结构写入 Page Object 或 helpers 后，删除 explore 文件
2. 截图清理：探索产生的 debug-*.png 截图是临时调试产物，确认不需要后删除
3. 不积累：tests/ 目录下不应存在已完成的 explore 文件。如果存在，说明知识提取步骤被跳过了
4. Bug 报告截图保留：bug-{序号}-*.png 截图属于 Bug 报告的一部分，不删除

---

关键技巧速查表

下表方法名（createDualSession / tracker.collect / setupBugTracking / isServerCrash 等）为本 skill 脚手架内置 helper 的示例（定义在 references/），不是 Playwright 通用 API——换项目时按 references/helpers_reference.md 适配实际脚手架，勿假定这些函数存在。

场景	方法	备注
受控组件输入框（Ant Design 等）	fill() 优先，不生效再 keyboard.type()	fill 会派发 input 事件，多数受控组件可用；keyboard.type 逐键最稳但慢
确认弹窗按钮	在 role=dialog 作用域内定位（如 page.getByRole('dialog').getByRole('button', { name: '确定' })）	防止与页面同名按钮歧义命中；弹窗外「确定/删除」同名按钮是常见误击源
隐藏必填字段	page.evaluate() 直接设值	阻止表单提交的常见原因
网络请求验证	page.on('request') 监听	必须在操作之前设置
数据持久化验证	page.reload() + 断言	确认数据真正保存
多用户会话	createDualSession(browser, roleA, roleB)	两个角色并发
登录态复用	createSession(browser, role)	缓存 storageState 免重复 UI 登录（工程约定第 10 节）
等待策略	① auto-wait + expect 断言 → ② waitForResponse → ③ networkidle（仅传统 SSR/MPA）	自上而下优先（工程约定第 9 节）；固定 waitForTimeout 仅临时调试；长轮询/心跳页对 networkidle 永不空闲
并行执行	默认串行，独立性达标后开 workers	前提：自建数据 + 自清理 + 唯一命名逐项核对（工程约定第 11 节）
flaky 定性	首次失败原样重跑通过 → 判 flaky	重跑只用于定性；定位根因前标 test.fixme（工程约定第 11 节）
截图调试	page.screenshot({ fullPage: true })	每个关键步骤都截图
服务端崩溃检测	isServerCrash(bodyText)	检测 500/502 错误
唯一命名	${前缀}-${Date.now()}	避免测试间名称冲突
Bug 证据收集	tracker.collect(testInfo, id, desc)	一键收集截图+API+控制台
Bug 探索前置	setupBugTracking(page)	注册 API 和控制台监听

Common Mistakes

错误	后果	正确做法
受控组件值不生效仍反复 fill()	测试卡死或断言失败	fill 失效时改用 keyboard.type()（见速查表）
网络监听放在 click 之后	捕捉不到请求	先注册 listener，再执行操作
不清理测试数据	后续测试受影响	afterEach 中删除创建的资源
用固定 timeout 等待	时序不稳定	按等待降级阶梯换用：① auto-wait+expect 断言 → ② waitForResponse → ③ networkidle（工程约定第 9 节）
不验证持久化	数据可能只存在内存	reload 后重新断言
正式测试不使用 Page Object	代码重复，难以维护	所有页面交互封装在 Page Object 中
explore 文件不删除	上下文污染，AI 每次读大量废代码	知识提取后立即删除
遇到疑问自行假设	产出不可靠的测试	不确定就向用户提问
Bug 只截图不记录 API/控制台	开发无法定位根因	用 setupBugTracking() + tracker.collect()
硬编码环境地址/账号	无法跨环境运行、泄露敏感信息	统一放 constants.ts / .env，代码只引用常量
失败重跑变绿就当没事	flaky 混入主干，CI 随机红	按 flaky 定性流程处理：先定性再修根因，禁止调大重试硬压（工程约定第 11 节）
对长轮询/推送页强套 networkidle	超时假失败	按等待降级阶梯换 waitForResponse/断言自动轮询（工程约定第 9 节）
每个 context 都走一遍登录页	执行时长翻倍、缓存认证态形同虚设	用 createSession() 复用 storageState，失效自动回退 UI 登录（工程约定第 10 节）
所有用例永久串行不敢并行	全量执行时长线性膨胀	独立性核对通过后渐进开启 workers（工程约定第 11 节）
手动用例信息不足仍硬造定位器与操作路径	幻觉自动化：断言全绿但没测到真实行为	先过 ../core/executability.md 转换闸门 + 工作流零踩点核实页面结构

---

与其他 skill 配合

• 上游：test-case-writing 产出手动用例（markmap + Schema）→ 本 skill 把 execution_model: ui 且可自动化的用例变成可执行代码；端到端流水线由 qa 编排
• 旁路：无文档 / 系统陌生的完整探索会话用 exploratory-testing，其探索笔记可作为本 skill 踩点的输入
• 下游：Bug 确认后的根因 / 影响 / 回归分析 → bug-analysis；执行报告与 Bug 条目按 ../core/report-template.md 对齐，供 qa 收尾汇总
• 平级：纯 API 用例的自动化 → api-testing