シナリオテスト設計・実行・コード化スキル

• 対象サイト URL
• テストケース一覧（TC-ID ・手順・期待結果を含む）
• テストケースの優先度

QA Management から受け取る情報の対応表:

STEP 0: ヒアリング

AskUserQuestion を使い、以下の情報を収集する。 既にユーザーが提示している情報はスキップしてよい。

STEP 1: テストケース設計

収集した情報をもとに、テストシナリオを設計する。

1-1. シナリオ洗い出し

以下の観点でテストケースを網羅的に洗い出す：

• 正常系（Happy Path）: メインの操作フローが期待通り動作するか
• 異常系（Error Path）: バリデーションエラー、404、権限不足などの処理
• 境界値: 入力値の最大・最小、空欄送信、特殊文字
• UI/UX 確認: レスポンシブ対応、ボタンの活性/非活性、ローディング表示
• ナビゲーション: ページ遷移、ブラウザバック、リンク切れ

1-2. シナリオ一覧の提示

以下のフォーマットでユーザーに提示し、フィードバックを求める：

## テストシナリオ一覧

### シナリオ 1: [シナリオ名]
- **目的**: [テストの目的]
- **前提条件**: [必要な状態・データ]
- **手順**:
  1. [操作 1]
  2. [操作 2]
  3. ...
- **期待結果**: [期待される動作・表示]
- **優先度**: 高 / 中 / 低

### シナリオ 2: [シナリオ名]
...

AskUserQuestion でユーザーの承認・修正フィードバックを得る。 シナリオに変更があれば反映し、再度提示する。

STEP 2: 手動検証（Playwright CLI）

承認されたシナリオを Playwright CLI で実際に操作し、動作を確認する。

2-1. ブラウザセッション開始

playwright-cli open [対象URL]

2-2. シナリオの手動実行

各シナリオの手順に沿って Playwright CLI コマンドを実行する：

# ページ構造の確認
playwright-cli snapshot

# 要素の操作
playwright-cli click [ref]
playwright-cli fill [ref] "[入力値]"
playwright-cli press Enter

# 結果の確認
playwright-cli snapshot
playwright-cli screenshot --filename=reports/screenshots/[scenario-name].png

2-3. 検証結果の記録

各シナリオについて以下を記録する：

• 実行結果: Pass / Fail / Skip
• 実行時に使用した Playwright コード（CLI が自動生成するコード）
• 発見した問題点や注意事項
• スクリーンショット（必要な場合、reports/screenshots/ に保存）

検証結果をユーザーに報告し、問題がなければ STEP 3 へ進む。

STEP 3: シナリオ Fix（ユーザー承認）

AskUserQuestion を使い、以下を確認する：

• 手動検証の結果に問題はないか
• シナリオの追加・修正・削除はあるか
• テストコード化に進んでよいか

ユーザーが承認したら STEP 4 へ進む。 修正がある場合は STEP 1 または STEP 2 に戻る。

STEP 4: テストコード生成

4-1. ファイル作成

テストファイルは tests/ ディレクトリに作成する。

• ファイル名: tests/[feature-name].spec.ts
• 命名規則: ケバブケースで機能名を表す（例: login-flow.spec.ts, cart-checkout.spec.ts）

4-2. コード構造

既存テスト（tests/*.spec.ts）のスタイルに合わせて記述する：

import { expect, type Page, test } from "@playwright/test";

// ---------------------------------------------------------------------------
// 定数・ヘルパー
// ---------------------------------------------------------------------------
const BASE_URL = "https://example.com";

// 外部サイトへのリクエストで load が遅延するページがあるため余裕を持たせる
test.use({ navigationTimeout: 60_000 });

/**
 * domcontentloaded で遷移する（load 待ちによるタイムアウトを回避）
 */
async function navigateTo(page: Page, url: string) {
  return page.goto(url, { waitUntil: "domcontentloaded" });
}

// =========================================================================
// テストスイート
// =========================================================================
test.describe("[機能名]", () => {
  test("[シナリオ名]", async ({ page }) => {
    // 1. ページ遷移
    await navigateTo(page, `${BASE_URL}/path`);

    // 2. 操作（Playwright CLI で生成されたコードを活用）
    await page.getByRole("button", { name: "Submit" }).click();

    // 3. アサーション
    await expect(page.getByText("Success")).toBeVisible();
  });
});

4-3. TC-ID トレーサビリティ

QA Management から TC-ID 付きのテストケースを受け取った場合、テストコードと QA 成果物の紐付けを維持する。

テスト名への TC-ID 埋め込みルール:

// QA Management の TC-E001 に対応するテスト
test("TC-E001: カートに商品を追加して購入完了まで遷移する", async ({ page }) => {
  // ...
});

// QA Management の TC-E002 に対応するテスト
test("TC-E002: 在庫切れ商品でエラーメッセージが表示される", async ({ page }) => {
  // ...
});

• TC-ID は test() の第一引数の先頭に TC-XXXX: プレフィックスとして付与する
• QA Management のテストケース一覧・不具合一覧・テスト結果レポートで同じ TC-ID を参照可能にする
• ユーザーが直接本スキルを呼び出した場合（QA Management 経由でない場合）は TC-ID プレフィックスは不要

4-4. コーディング規約

• ロケーター: getByRole(), getByText(), getByLabel() 等のセマンティックロケーターを優先。CSS セレクターは最終手段
• 待機: waitForURL(), waitForSelector() を使い、固定の waitForTimeout() は避ける
• アサーション: expect の Playwright 組み込みアサーション（toBeVisible(), toHaveURL(), toHaveText() 等）を使用
• ヘルパー関数: 複数シナリオで共通する操作（ログイン、ナビゲーション等）はヘルパーに切り出す
• テストの独立性: 各テストは他のテストに依存しない。テストごとに状態をリセットする
• 日本語の使用: test.describe() や test() のラベルは日本語で記述してよい（既存テストの慣例に準拠）
• 守秘情報の取り扱い: パスワードなどの守秘情報は .env もしくは .env.project ファイルで管理し、テストコードには含めない。

STEP 5: 品質チェック

5-1. lint チェックと自動修正

bun lint:fix

lint エラーが残る場合は手動で修正する。

5-2. テスト実行

bun e2e

テストが失敗する場合：

1. エラーメッセージを分析
2. ロケーター・タイミング・アサーションの問題を特定
3. コードを修正
4. 再実行

全テストが Pass するまで繰り返す。

5-3. リファクタリング

テストが Pass した後、以下の観点でリファクタリングを検討する：

• 重複コードのヘルパー関数化
• マジックナンバーの定数化
• テストデータの構造化（配列・オブジェクトで管理）
• 不要な waitForTimeout() の除去
• コメントの追加（テスト意図が不明瞭な箇所）

リファクタリング後、再度 lint と テスト実行を行い Pass を確認する。

STEP 6: セットアップ完了

テストが安定稼働することを確認したら、ユーザーに以下を案内する：

実行コマンド

# 全 E2E テスト実行
bun e2e

# 特定のテストファイルのみ実行
bunx playwright test tests/[file-name].spec.ts

# UI モードで実行（デバッグ用）
bun e2e:ui

# ヘッドフルモード（ブラウザ表示あり）
bun e2e:headed

# デバッグモード
bun e2e:debug

作成物一覧

最後に、作成・変更したファイルの一覧を表示する：

[作成] tests/[file-name].spec.ts  — [テストの概要]
[変更] playwright.config.ts        — [変更があった場合のみ]

判断基準・注意事項

playwright-cli スキルとの棲み分け

判定ルール:

• 「テストを作りたい」「テストケースを洗い出したい」「E2E テストを自動化したい」→ scenario-test
• 「このページのスクリーンショットを撮って」「フォームに入力して」「ページの情報を取得して」→ playwright-cli
• 本スキル内の STEP 2（手動検証）では playwright-cli スキルのコマンドを内部的に使用する

既存テストとの一貫性

• tests/ ディレクトリの既存ファイル（tam-i18n.spec.ts 等）のスタイルを踏襲する
• playwright.config.ts の設定（testDir, projects 等）に準拠する
• navigateTo() ヘルパー等、共通パターンがあれば再利用する

テスト対象の制約

• 外部サービス（決済、メール送信等）を伴うシナリオは、モックやテスト環境の利用を検討する
• 認証が必要なシナリオでは、storageState の活用を提案する（参考: playwright-cli/references/storage-state.md）
• CI 環境での実行を考慮し、ヘッドレスで安定動作するテストを目指す