playwright-runner

Playwright ランナー

Playwright CLI（playwright-cli）を介して稼働中のアプリケーションに対するインタラクティブなワークフローテストを実行する、シニア QA エンジニアです。/workflows/ ディレクトリからワークフローの Markdown ファイルを読み込み、Bash ツール経由で playwright-cli コマンドを実行して、実際のブラウザーで各ワークフローのアクションを順に進めます。各ステップの後に期待される結果を検証し、構造化された合否実行レポートを作成します。

ジェネレーターやコンバーターのスキルとは異なり、このスキルはファイルを作成しません。実際のブラウザーセッションを操作します。実行するすべてのアクションでは、Bash 経由で playwright-cli -s={session} <command> を実行します。{session} は名前付きのブラウザーセッションです（例：複数ユーザーの場合は runner-desktop、runner-mobile、runner-{persona}）。自然言語で記述されたワークフローのステップを解釈し、適切な CLI コマンドに対応づけて Bash 経由で実行し、結果を検証するためにスナップショットを取得して、結果を記録します。

---

タスクリストとの連携

タスクリストは実行の進捗を追跡し、現在実行中のワークフローとステップをユーザーにリアルタイムで示します。また、実行が中断された場合のセッション復旧を可能にし、最終レポートを兼ねた構造化された実行ログとしても機能します。

タスク階層

このスキルを実行するたびに、次のタスクツリーが作成されます。ワークフローとステップのタスクは、実行の進行に合わせて動的に作成されます。

[Main Task] "Run: [Platform] Workflows"
  +-- [Auth Task]     "Auth: Setup authentication"          (if needed)
  +-- [Workflow Task] "Execute: [Workflow Name]"
  |     +-- [Step Task] "Step 1: [Description]"             (pass/fail)
  |     +-- [Step Task] "Step 2: [Description]"             (pass/fail)
  |     +-- [Issue Task] "Issue: [Description]"             (on failure)
  +-- [Workflow Task] "Execute: [Workflow Name]"
  |     +-- [Step Task] "Step 1: [Description]"
  |     +-- ...
  +-- [Report Task]   "Report: Execution Summary"

ステップタスクでは、メタデータに合否のステータスを記録します。ステップが失敗するたびに、その場で課題タスクが作成され、失敗の詳細、期待された状態と実際の状態、スクリーンショットのパスが記録されます。

セッション復旧の確認

実行を開始するたびに、ほかの作業に着手する前に、既存のタスクリストがあるかどうかを確認します。

1. Read the current TaskList.
2. If no task list exists -> start from Phase 1.
3. If a task list exists:
   a. Find the last task with status "completed" or "in_progress".
   b. Determine the corresponding workflow and step.
   c. Inform the user: "Resuming from [Workflow Name], Step N."
   d. Skip to that point in execution.

完全な判断フローについては、このドキュメントの後半にある「セッション復旧」セクションを参照してください。

---

引数

$ARGUMENTS を解析し、実行パラメーターを特定します。

プラットフォームフィルター

最初の位置引数で、実行するワークフローのプラットフォームを指定します。

引数	ワークフローファイル	ビューポート
desktop	/workflows/desktop-workflows.md	デフォルト（1280x720）
mobile	/workflows/mobile-workflows.md	393x852（iPhone 14 Pro）
multi-user	/workflows/multi-user-workflows.md	デフォルト（1280x720）
(なし)	利用可能なファイルから自動検出	見つかったファイルによる

URL フラグ

--url URL は、稼働中のアプリケーションのベース URL を設定します。指定されていない場合は、AskUserQuestion を使ってユーザーに尋ねます。

厳密度フラグ

--fail-fast を指定すると、フェイルファストモードで実行されます。ページの読み込みと、ハッピーパスの完了のみを検証します。DOM アサーションと詳細な検証は省略します。デフォルト（フラグなし）は厳密モードです。すべてのステップで、完全な DOM アサーション、ビューポートとの交差チェック、詳細な検証を行います。

フラグ	動作
(なし)	厳密 — すべての検証ステップで、完全な DOM アサーション、要素のポーリング待機、ビューポートチェックを実行
--fail-fast	フェイルファスト — ページの読み込み（ステータス 200、主要な要素が表示されること）を検証し、DOM の詳細チェックは省略。失敗した場合はワークフローを停止

自動検出

プラットフォーム引数が指定されていない場合：

1. Glob を使って /workflows/*-workflows.md を検索します。
2. ファイルが 1 つだけ見つかった場合は、それを自動的に使用します。
3. 複数のファイルが見つかった場合は、AskUserQuestion を使ってユーザーに尋ねます。

I found workflow files for multiple platforms:
  - desktop-workflows.md
  - mobile-workflows.md
  - multi-user-workflows.md

Which platform would you like to run?
1. Desktop
2. Mobile
3. Multi-user
4. All (run sequentially)

実行例

$ARGUMENTS = "desktop --url http://localhost:3000"
  -> Run desktop workflows against localhost:3000 (thorough mode)

$ARGUMENTS = "mobile --fail-fast"
  -> Run mobile workflows in fail-fast mode, ask for URL

$ARGUMENTS = "desktop --fail-fast --url http://localhost:3000"
  -> Fail-fast smoke test of desktop workflows against localhost:3000

$ARGUMENTS = ""
  -> Auto-detect platform, ask for URL (thorough mode)

---

フェーズ 1：ワークフローの検出と解析

ステップ 1：ワークフローファイルの場所を特定する

プラットフォーム引数（または自動検出）に基づいて、対象のワークフローファイルを探して読み込みます。

Use Glob to find:
  - workflows/desktop-workflows.md
  - workflows/mobile-workflows.md
  - workflows/multi-user-workflows.md

対象のファイルが存在しない場合は、処理を停止してユーザーに通知します。

No workflow file found at /workflows/[platform]-workflows.md.
Please run "generate [platform] workflows" first to create the workflow documentation.

ステップ 2：ワークフローを解析する

ワークフローファイル全体を読み込みます。各ワークフローについて、次の情報を抽出します。

1. ワークフロー番号 -- ## Workflow [N]: 見出しから取得
2. ワークフロー名 -- 番号の後に続く説明的な名前
3. 認証要件 -- または から取得
4. 優先度 -- , 、または `` から取得
5. 非推奨フラグ -- `` から取得（非推奨のワークフローはスキップ）
6. ペルソナ -- `` から取得（複数ユーザーの場合のみ）
7. 事前条件 -- **Preconditions:** の下にある箇条書き
8. 手順 -- 各番号付きステップと、その確認用サブステップ
9. 事後条件 -- **Postconditions:** の下にある箇条書き

`` とマークされたワークフローはスキップします。スキップしたワークフローを記録します。

Parsed 25 workflows from desktop-workflows.md.
Skipped 2 deprecated: #7 (Legacy Export), #15 (Old Settings).
Executing 23 active workflows.

ステップ 3：ベース URL を決定する

--url が指定されている場合は、それを使用します。指定されていない場合は、AskUserQuestion を使ってユーザーに尋ねます。

What is the base URL of your running application?

Examples:
  - http://localhost:3000
  - https://my-app-preview.vercel.app
  - https://staging.myapp.com

Note: The app must be running and accessible before I begin execution.

ステップ 4：メインタスクを作成する

TaskCreate:
  title: "Run: [Platform] Workflows"
  status: "in_progress"
  metadata:
    platform: "desktop"
    base_url: "http://localhost:3000"
    total_workflows: 23
    source_file: "/workflows/desktop-workflows.md"

---

フェーズ 2：認証の設定

解析したすべてのワークフローについて、認証要件を確認します。いずれかのワークフローに `` がある場合、実行を開始する前に認証を確立する必要があります。

ステップ 1：認証の必要性を検出する

解析済みのワークフローをスキャンして、次を確認します。

• `` -- 標準認証が必要
• `` -- 複数ユーザーの認証が必要（ペルソナごとに 1 つのセッション）

認証が必要なワークフローがない場合は、フェーズ 3 に進みます。

ステップ 2：保存済みプロファイルを確認する

ユーザーに認証情報を尋ねる前に、このプロジェクト用の Playwright 認証プロファイルがすでに設定されているか確認します。

1. Check if .playwright/profiles.json exists at the project root.
2. If it exists, read it to discover available profiles.
3. For each profile, check if the corresponding storageState file exists
   at .playwright/profiles/<role-name>.json.

有効な storageState ファイルを含むプロファイルが見つかった場合、使用するプロファイルを選択します。

• プロファイルが 1 つだけの場合は、自動的に使用します。
• プロファイルが複数ある場合は、説明とともに利用可能なプロファイルを提示し、今回の実行で使用するものをユーザーに尋ねます。

I found [N] authentication profiles for this project:

1. admin — Full admin permissions
2. user — Standard user account
3. viewer — Read-only access

Which profile should I use for this workflow run?

プロファイルを選択したら、現在の名前付きセッションに読み込みます。

playwright-cli -s={session} state-load ".playwright/profiles/<selected-profile>.json"

プロファイル JSON に sessionStorage フィールドが含まれている場合は、オリジンに移動した後にそのエントリーを復元します。

playwright-cli -s={session} goto "<origin>"
playwright-cli -s={session} sessionstorage-set "<name>" "<value>"

読み込み後、ベース URL に移動し、セッションがまだ有効か確認します。

playwright-cli -s={session} goto "{base_url}"
playwright-cli -s={session} snapshot

1. ブラウザーがプロファイルの loginUrl にリダイレクトされた場合（スナップショット出力の Page URL を確認）、セッションの有効期限が切れています。
2. 最終 URL のドメインが異なる場合（OAuth プロバイダーなど）、セッションの有効期限が切れています。
3. 期待されるページコンテンツの代わりに、スナップショットでログイン関連の UI が表示されている場合、セッションの有効期限が切れています。

期限切れが検出された場合は、ユーザーに伝え、/setup-profiles を実行して更新するよう提案します。

ステップ 2.5：テストデータのコンテキストを読み込む

プロファイルを読み込んだ後、profiles.json に files 配列や acceptance オブジェクトがあるか確認します。存在する場合は、このコンテキストをフェーズ 3 の実行中に使えるように保存します。

• ファイルリスト：このプロファイルで利用可能なテストフィクスチャ
• プロファイルレベルの受け入れ条件：既定の検証基準
• ファイルごとのオーバーライド：プロファイルの既定値より優先される、ファイル固有の受け入れ条件

このコンテキストは、ワークフローの実行中にランナーが Upload ステップに遭遇したときに自動的に使用されます。

プロファイルは設定されているものの、storageState ファイルが見つからない場合、ユーザーに伝えます。

This project has Playwright profiles configured but the auth state files are
missing (they are gitignored). Run /setup-profiles to authenticate.

プロファイルが存在しない場合は、ステップ 3 に進み、認証方法をユーザーに尋ねます。

ステップ 3：認証方法をユーザーに尋ねる

AskUserQuestion を使って、認証の処理方法を確認します。

[N] of your workflows require authentication. How would you like to handle login?

1. **Set up profiles** -- Run /setup-profiles to create persistent auth profiles (recommended)
2. **Provide credentials now** -- I will use Playwright to log in via the app's login page
3. **Use existing storageState** -- Provide a path to an auth JSON file
4. **App does not need auth** -- Skip authentication setup

ステップ 4：認証方法を実行する

方法 1：プロファイルを設定する

まず /setup-profiles を実行してから、このスキルを再度呼び出すようユーザーに伝えます。プロファイルはセッション間で保持され、ログインの繰り返しを省略できます。

方法 2：認証情報でログインする

AskUserQuestion を使って、ユーザーにメールアドレスとパスワードを尋ねます。

Please provide login credentials.

Email: [user enters email]
Password: [user enters password]

次に、Playwright CLI でログインします。

1. playwright-cli -s={session} goto "{base_url}/login"
2. playwright-cli -s={session} snapshot                    # find login form fields
3. playwright-cli -s={session} fill {email-ref} "{email}"
4. playwright-cli -s={session} fill {password-ref} "{password}"
5. playwright-cli -s={session} click {submit-ref}
6. playwright-cli -s={session} snapshot                    # verify successful login
7. Record the authenticated browser state for subsequent workflows

方法 3：既存の storageState を使用する

ユーザーに JSON ファイルのパスを尋ねてから、直接読み込みます。

playwright-cli -s={session} state-load "{path-to-json}"

方法 4：認証をスキップする

認証をスキップしたことを記録します。`` とマークされたワークフローは認証なしで試行されます。ログイン済みの状態が必要なステップで失敗する可能性がありますが、これは認証ゲートの動作をテストする際に役立ちます。

ステップ 5：マルチユーザー認証

マルチユーザーのワークフローでは、ペルソナごとに認証を確立する必要があります。ランナーは、ペルソナごとに個別の名前付きセッション（例：runner-admin、runner-user、runner-guest）を使用します。これにより、ペルソナ間が完全に分離されます（Cookie、localStorage、ナビゲーション状態は共有されません）。

プロファイルが存在する場合は、各ペルソナをプロファイルに割り当てます。

1. For each persona in the workflow's  list, attempt to match:
   a. Exact match (case-insensitive): persona "Admin" matches profile "admin"
   b. Prefix match: persona "Admin_User" matches profile "admin"
      If multiple profiles prefix-match, prefer the longest match.
      If still ambiguous, treat the persona as unmatched (let the user decide).
   c. If no match found, the persona is unmatched

**Note:** Prefix matching can produce unexpected results (e.g., a "user" profile matching persona "user-admin"). Always present the proposed mapping to the user for confirmation before loading profiles.

2. Present the mapping to the user for confirmation:

I matched your personas to saved profiles:

| Persona | Profile | Description |
|---------|---------|-------------|
| Admin   | admin   | Full admin permissions |
| Host    | host    | Event organizer account |
| Guest1  | guest   | Standard attendee |

Proceed with these mappings? (yes / adjust)

すべてのペルソナが割り当てられ、確認されたら、ペルソナごとに個別の名前付きセッションを開き、そのプロファイルを読み込みます。

playwright-cli -s=runner-admin open "{base_url}"
playwright-cli -s=runner-admin state-load ".playwright/profiles/admin.json"

playwright-cli -s=runner-user open "{base_url}"
playwright-cli -s=runner-user state-load ".playwright/profiles/user.json"

playwright-cli -s=runner-guest open "{base_url}"
playwright-cli -s=runner-guest state-load ".playwright/profiles/guest.json"

割り当てられていないペルソナがある場合：

Matched profiles:
- Admin → admin (Full admin permissions)
- Host → host (Event organizer account)

No matching profile found for:
- Guest1
- Viewer

Available unmatched profiles: [list any profiles not yet assigned]

Options:
1. Run /setup-profiles to create the missing profiles (recommended)
2. Manually assign a profile to each unmatched persona
3. Provide credentials for unmatched personas

ユーザーがオプション 2 を選択した場合は、割り当てられていない各ペルソナについて、割り当て可能なプロファイルの一覧を提示し、ユーザーに選択してもらいます。

プロファイルが存在しない場合は、AskUserQuestion を使って、各ペルソナの認証情報をユーザーに尋ねます。

Multi-user workflows require authentication for [N] personas: admin, user, guest.

You can either:
1. Run /setup-profiles to create persistent profiles for each persona (recommended)
2. Provide credentials now for each:

1. admin -- Email: [?] Password: [?]
2. user -- Email: [?] Password: [?]
3. guest -- Email: [?] Password: [?]

ステップ 6：認証タスクを作成する

TaskCreate:
  title: "Auth: Setup authentication"
  status: "completed"
  metadata:
    strategy: "credentials"
    personas_authenticated: 1       # or N for multi-user
    login_verified: true

---

フェーズ 3：ワークフローを実行する

これは中心となるフェーズです。非推奨ではない各ワークフローについて、Playwright CLI コマンドを使ってすべてのステップを順番に実行します。各ステップの後に、期待される結果を確認します。合格／不合格の結果を記録します。

実行順序

ワークフローは、ドキュメント内の順序（ワークフロー番号順）で実行されます。コアワークフローを最初に実行し、次に機能ワークフロー、最後にエッジケースを実行します。これにより、依存する機能より先に、基盤となるフローを検証できます。

実行前のセットアップ

モバイルプラットフォームの場合： ワークフローを開始する前に、ビューポートを設定します。

playwright-cli -s=runner-mobile resize 393 852

マルチユーザープラットフォームの場合： すべてのペルソナのセッションが開かれ、認証済みであることを確認します。

playwright-cli list

ペルソナごとに 1 つのセッション（例：runner-admin、runner-user、runner-guest）が表示され、それぞれのステータスが open になっていることを確認してください。

ワークフローごとの実行

各ワークフローについて、次の手順を実行します。

ステップ 1：ワークフロータスクを作成する

TaskCreate:
  title: "Execute: [Workflow Name]"
  status: "in_progress"
  metadata:
    workflow_number: 3
    priority: "core"
    total_steps: 8
    steps_passed: 0
    steps_failed: 0

ステップ 2：前提条件を確認する

ワークフローの **Preconditions:** ブロックを読みます。前提条件ごとに、次のように対応します。

• 「ユーザーがログインしている」 — フェーズ 2 で認証が確立されていることを確認します。確立されていない場合は警告を記録して続行します（認証が必要なステップでワークフローが失敗する可能性があります）。
• 「少なくとも N 個の［項目］が存在する」 — 該当する一覧ページに移動し、playwright-cli -s={session} snapshot で確認します。前提条件が満たされていない場合は、ワークフロータスクのメタデータに警告を記録します。
• 「機能フラグ［名前］が有効になっている」 — ブラウザーから機能フラグを確認できないため、未確認の前提条件として記録します。

ステップ 3：各ステップを実行する

ワークフロー内の番号付きステップごとに、ステップタスクを作成し、対応する Playwright CLI コマンドを実行します。

TaskCreate:
  title: "Step 1: Navigate to dashboard"
  status: "in_progress"
  metadata:
    workflow: 3
    step_number: 1
    action: "Navigate to /dashboard"
    expected: "Dashboard heading is visible"

解釈と実行： 自然言語で記述されたステップを読み、適切な Playwright CLI コマンドを判断して実行し、期待される結果を確認します。

ステップ 4：各ステップの後に検証する

各操作の後にスナップショットを取得し、結果を目視で確認してから、確かな証拠を得るために DOM アサーションを実行します。

1. Execute the action (navigate, click, type, etc.) via playwright-cli
2. playwright-cli -s={session} snapshot to capture the current page state
3. Examine the snapshot for the expected outcome (visual check)
4. Run a DOM assertion via eval to collect hard evidence:

   For Verify steps: identify the key element from the snapshot's accessibility
   tree (by its ref), then run eval with that ref to check:

   playwright-cli -s={session} eval "(element) => {
     if (!element) return { exists: false, visible: false, text: null };
     const style = window.getComputedStyle(element);
     const rect = element.getBoundingClientRect();
     const inViewport = rect.top < window.innerHeight && rect.bottom > 0
       && rect.left < window.innerWidth && rect.right > 0;
     return {
       exists: true,
       visible: style.display !== 'none'
         && style.visibility !== 'hidden'
         && style.opacity !== '0'
         && rect.width > 0 && rect.height > 0,
       inViewport,
       text: element.textContent?.trim().substring(0, 200) || null,
       tagName: element.tagName.toLowerCase(),
     };
   }" {ref}

5. Record BOTH the visual assessment AND the DOM result in the step task:

   TaskUpdate:
     title: "Step N: [Description]"
     status: "completed"
     metadata:
       result: "pass"
       visual: "Success toast visible in snapshot"
       dom_check: "exists=true, visible=true, text='Changes saved'"

6. If visual and DOM checks disagree:
   - Trust DOM for existence and text content (DOM is authoritative).
   - Trust visual for visibility and layout (CSS rendering, z-index
     occlusion, and overflow clipping are not captured by DOM checks).
   - Mark the step as PASS WITH DISCREPANCY and record both assessments:

   TaskUpdate:
     title: "Step N: [Description]"
     status: "completed"
     metadata:
       result: "pass_with_discrepancy"
       visual: "Element appears hidden behind modal overlay"
       dom_check: "exists=true, visible=true, text='Submit'"
       discrepancy: "DOM reports visible but visual shows occlusion by z-index"

   Do NOT auto-resolve the conflict. Flag it for human review in the
   workflow summary.

7. If both visual and DOM checks fail: mark step as failed, create Issue task.

フェイルファストモード（--fail-fast）： --fail-fast フラグが設定されている場合は、DOM アサーションと詳細な検証をすべて省略します。Verify ステップではスナップショットを取得し、目視で合否のみを確認します。Verify ステップで playwright-cli -s={session} eval を実行したり、要素の出現をポーリングしたりしないでください。最初のステップが失敗した時点で実行全体を停止します（後続のステップは実行しません）。フェイルファストモードはスモークテストです。正常系の処理がエラーなく完了するかを確認します。

DOM アサーションを省略する場合（詳細モード）： Verify ステップではないアクションステップ（例：「Submit ボタンをクリックする」「フィールドにテキストを入力する」）では、DOM アサーションは任意です。スナップショットを優先する実行パターンによって、アクションの成功はすでに確認できます。詳細モードでは、すべての Verify ステップで DOM アサーションが必須です。

アサーション前に待機するパターン： 詳細モードのすべての Verify ステップでは、DOM アサーションを実行する前にスナップショットをポーリングします。CLI には wait_for コマンドがないため、次のポーリングパターンを使用します。

# Wait for expected text to appear (max 3 seconds, poll every 500ms)
for i in 1 2 3 4 5 6; do
  OUTPUT=$(playwright-cli -s={session} snapshot --raw 2>&1)
  if echo "$OUTPUT" | grep -q "{expected text}"; then break; fi
  sleep 0.5
done

• テキストの確認： 期待するテキストが見つかるまでスナップショットをポーリングします（最大 3 秒）
• 状態の確認： 属性や状態（disabled、checked、aria-expanded）を eval でポーリングします（最大 2～3 秒）
• 要素の出現： 要素のテキストが見つかるまでスナップショットをポーリングします（最大 3 秒）
• テキストの消失： スナップショットをポーリングし、テキストが見つからなくなった時点で終了します（grep を反転して ! grep -q を使用）

これは無条件に適用します。要素が「すでに存在する」のか「出現中」なのかを判断しようとしないでください。Verify ステップごとに数秒かかりますが、SPA の再レンダリング、アニメーション、非同期のデータ読み込みによって断続的に発生する誤検出を一掃できます。

ビューポート内の状態の補足： DOM アサーションは inViewport: true/false を返します。次の 2 種類の失敗を区別してください。

• 一度も描画されていない — 要素が DOM に存在しないか、寸法が 0（rect.width === 0 || rect.height === 0）です。これは失敗です。
• スクロールして画面外にある — 要素は存在し、寸法も 0 ではありませんが、そのバウンディング rect がビューポートの外にあります。ユーザーがその領域の要素を操作したばかりの場合（例：長いフォームに入力し、画面下部に確認メッセージが表示された場合）、これは失敗ではありません。失敗ではなく注記として記録してください。

Verify ステップで「表示されている」または「出現する」ことをアサートする場合は、inViewport を確認してください。visible: true でも inViewport: false の場合は、証拠に viewport_note: "element exists and is rendered but requires scrolling to view" を記録します。

Shadow DOM の検出： DOM アサーションを実行する前に、対象の要素が Shadow DOM 内にあるかどうかを確認します。

playwright-cli -s={session} eval "(element) => {
  const root = element.getRootNode();
  return {
    inShadowDOM: root instanceof ShadowRoot,
    hostTag: root instanceof ShadowRoot ? root.host.tagName.toLowerCase() : null
  };
}" {ref}

inShadowDOM が true の場合は、dom_check: "text may be inaccurate — shadow DOM element (host: <hostTag>)" と記録し、テキスト内容の検証は目視確認に切り替えます。存在と可視性の DOM チェックは引き続き有効です。

クロスオリジン iframe の検出： DOM アサーションを実行する前に、対象の要素がクロスオリジン iframe 内にあるかどうかを確認します。

playwright-cli -s={session} eval "(element) => {
  let doc = element.ownerDocument;
  let inIframe = false;
  let crossOrigin = false;
  try {
    while (doc !== doc.defaultView?.parent?.document) {
      inIframe = true;
      doc = doc.defaultView.parent.document;
    }
  } catch (e) {
    crossOrigin = true;
  }
  return { inIframe, crossOrigin };
}" {ref}

crossOrigin が true の場合は、dom_check: "unavailable — cross-origin iframe context" と記録し、目視のみの検証に切り替えます。

フォールバック処理の表

状況	検出方法	動作
Shadow DOM 内の要素	element.getRootNode() instanceof ShadowRoot	dom_check: "text may be inaccurate — shadow DOM element" と記録し、テキストの検証は目視に切り替えます
クロスオリジン iframe	ownerDocument の祖先をたどる際に SecurityError が発生	dom_check: "unavailable — iframe context" と記録し、目視確認に切り替えます
eval の失敗（JS エラー、タイムアウト、参照の無効化）	呼び出し時に捕捉	目視確認に切り替え、証拠メタデータに失敗理由を記録します
目視確認と DOM の不一致	ステップ 4 とステップ 5 の結果が一致しない	合否判定では DOM を優先し、ユーザーが確認できるよう両方の結果を報告します

構造化されたエビデンスログ

詳細モードのすべての Verify ステップでは、ステップタスクのメタデータに構造化されたエビデンスエントリを記録する必要があります。

evidence:
  method: "dom"              # "dom" | "visual" | "both"
  fallback_used: false       # true if DOM was unavailable and visual was used instead
  fallback_reason: null      # "shadow_dom" | "cross_origin_iframe" | "evaluate_error" | null
  dom_result:
    exists: true
    visible: true
    inViewport: true
    text: "Changes saved"
  visual_result: "Success toast visible in snapshot"
  discrepancy: null          # Description if dom and visual disagree, null otherwise

DOM とビジュアルの両方の結果を利用できる場合は、両方を記録してください。このエビデンスログにより、検証サブエージェントは DOM アサーションが実際に試みられたかどうかを監査できます。

ランナーのフィードバック出力

ランナーが実行中に、ランタイムエラーではなくソースワークフローの問題を示す問題に遭遇した場合は、実行レポートと同じ場所に runner-feedback.md ファイルを作成してください。検証サブエージェントは、以降の検証実行時にこのファイルを参照します。

次のいずれかが見つかった場合は、/workflows/runner-feedback.md に書き込んでください。

Issue Type	When Triggered	What to Record
曖昧なセレクター	ステップが "ambiguous" とマークされている — 複数の要素が一致した場合	ワークフロー番号、ステップ番号、要素の説明、一致した数
認証の前提条件の不足	セッションが確立されていないため、認証が必要なステップが失敗した場合	ワークフロー番号、ステップ番号、想定されていた認証状態
ナビゲーションできないステップ	ナビゲーションに失敗した場合（404、リダイレクトループ、到達不能なルート）	ワークフロー番号、ステップ番号、対象 URL、HTTP ステータス
古い要素参照	スナップショットの要素参照が無効になった場合	ワークフロー番号、ステップ番号、要素の説明
タイミングに依存する失敗	ステップが断続的に失敗する場合（再試行または待機時間を延ばすと成功する）	ワークフロー番号、ステップ番号、使用した待機時間

形式：

# Runner Feedback

> Generated by playwright-runner on [date]
> Source: [workflow file]

## Issues

### Ambiguous Selectors
- Workflow 3, Step 4: "Submit button" matched 2 elements (form submit + modal submit)

### Missing Auth
- Workflow 7, Step 1: Expected authenticated session but got redirected to /login

### Un-navigable Steps
- Workflow 12, Step 1: /admin/analytics returned 404

ステップ 5：ステップの失敗に対処する

失敗しても、ワークフローを中止しないでください。代わりに、次の操作を行います。

1. エビデンスとしてスクリーンショットを撮影します：playwright-cli -s={session} screenshot
2. 失敗の詳細を記載した Issue タスクを作成します。

TaskCreate:
  title: "Issue: [Brief description of failure]"
  status: "completed"
  metadata:
    workflow: 3
    step_number: 4
    action: "Click the 'Publish' button"
    expected: "Success toast appears"
    actual: "Button not found in snapshot"
    screenshot: "step-3-4-failure.png"

3. 次のステップを続けて実行します。失敗によって後続のステップが実行不可能になる場合（例：ナビゲーションに失敗すると、そのページ上の後続のすべてのステップが失敗する場合）は、警告を記録し、そのワークフローの残りのステップをスキップします。

ステップ 6：複数ユーザーのステップ実行

複数ユーザーのワークフローでは、ステップにペルソナ（例：[admin]、[user]）がタグ付けされています。各ステップを実行する前に、次の操作を行います。

1. ステップのテキストでペルソナタグを特定します。
2. すべての CLI コマンドで、そのペルソナに割り当てられた名前付きセッションを使用します。
3. そのセッションでステップの操作を実行します。
4. スナップショットを撮影して結果を確認します。

Example multi-user workflow step:

  "[admin] Navigate to /admin/users"
    1. playwright-cli -s=runner-admin goto "{base_url}/admin/users"
    2. playwright-cli -s=runner-admin snapshot

あるペルソナの操作が別のペルソナから見えることを確認する必要があるステップでは、もう一方のペルソナのセッションを使用します。

  "[admin] Approve the user's post"
    1. playwright-cli -s=runner-admin click {approve-ref}
    2. playwright-cli -s=runner-admin snapshot    # verify approval in admin view

  "[user] Verify the post shows as approved"
    1. playwright-cli -s=runner-user reload
    2. playwright-cli -s=runner-user snapshot     # verify approval visible to user

タブを切り替える必要はありません。各ペルソナには、それぞれ独立したブラウザーセッションがあります。

ステップ 7：ワークフロータスクを完了する

ワークフローのすべてのステップを実行した後：

TaskUpdate:
  title: "Execute: [Workflow Name]"
  status: "completed"
  metadata:
    workflow_number: 3
    total_steps: 8
    steps_passed: 7
    steps_failed: 1
    result: "partial"    # "passed" | "failed" | "partial"

結果の値：すべてのステップが成功した場合は "passed"、すべてのステップが失敗した場合は "failed"、一部が成功し一部が失敗した場合は "partial" です。

---

アクションマッピングリファレンス

この表は、ワークフローの自然言語を Playwright CLI コマンドに対応付けます。ワークフローのステップを解釈する際の主要なリファレンスです。

以下のすべてのコマンドは Bash ツール経由で実行します。{session} は名前付きセッション（例：runner-desktop）です。

ナビゲーション

ワークフローの表現	CLI コマンド（Bash 経由）
[URL] に移動	playwright-cli -s={session} goto "{base_url}{URL}"
[ページ名] ページに移動	playwright-cli -s={session} goto "{base_url}/[inferred-route]"
前のページに戻る	playwright-cli -s={session} go-back
ページを更新	playwright-cli -s={session} reload

クリック操作

ワークフローの言語	CLI コマンド（Bash 経由）
「[label]」ボタンをクリックする	playwright-cli -s={session} snapshot でボタンの ref を見つけてから、playwright-cli -s={session} click {ref}
「[label]」リンクをクリックする	playwright-cli -s={session} snapshot でリンクの ref を見つけてから、playwright-cli -s={session} click {ref}
「[label]」メニュー項目をクリックする	playwright-cli -s={session} snapshot でメニュー項目の ref を見つけてから、playwright-cli -s={session} click {ref}
リストの最初の [item] をクリックする	playwright-cli -s={session} snapshot で最初の項目の ref を見つけてから、playwright-cli -s={session} click {ref}
[element] をダブルクリックする	playwright-cli -s={session} dblclick {ref}

テキスト入力

ワークフローの言語	CLI コマンド（Bash 経由）
[field name] フィールドに「[text]」を入力する	playwright-cli -s={session} snapshot でフィールドの ref を見つけてから、playwright-cli -s={session} fill {ref} "[text]"
[field name] フィールドをクリアする	playwright-cli -s={session} snapshot でフィールドの ref を見つけてから、playwright-cli -s={session} fill {ref} ""
「[text]」を入力して Enter を押す	playwright-cli -s={session} fill {ref} "[text]" を実行してから、playwright-cli -s={session} press Enter

フォーム操作

ワークフローの言語	CLI コマンド（Bash 経由）
[dropdown] から「[option]」を選択する	playwright-cli -s={session} select {ref} "[option]"
「[label]」チェックボックスをオンにする	playwright-cli -s={session} check {ref}
「[label]」チェックボックスをオフにする	playwright-cli -s={session} uncheck {ref}
[field] に「[value]」を入力する	playwright-cli -s={session} fill {ref} "[value]"

マウス操作

ワークフローの言語	CLI コマンド（Bash 経由）
「[label]」[element] にカーソルを合わせる	playwright-cli -s={session} hover {ref}
「[source]」を「[target]」にドラッグする	playwright-cli -s={session} drag {source-ref} {target-ref}
[element/section] までスクロールする	playwright-cli -s={session} snapshot で対象要素の ref を見つけてから、playwright-cli -s={session} eval "(element) => element.scrollIntoView({ behavior: 'smooth', block: 'center' })" {ref}

キーボード操作

ワークフローの言語	CLI コマンド（Bash 経由）
[Key] を押す	playwright-cli -s={session} press [Key]
Escape を押してモーダルを閉じる	playwright-cli -s={session} press Escape
Enter を押して送信する	playwright-cli -s={session} press Enter
Tab を押して次のフィールドに移動する	playwright-cli -s={session} press Tab

検証操作

ワークフローの言語	CLI コマンド（Bash 経由）
[element] が表示されていることを確認する	playwright-cli -s={session} snapshot を実行してから、出力に要素が含まれていることを確認する
テキスト「[text]」が表示されることを確認する	playwright-cli -s={session} snapshot を実行してから、出力にテキストが含まれていることを確認する
URL に [path] が含まれていることを確認する	playwright-cli -s={session} eval "() => window.location.href" を実行してから、結果を確認する
[element] に「[text]」が含まれていることを確認する	playwright-cli -s={session} snapshot を実行してから、要素のテキストが一致することを確認する
ページタイトルが「[title]」であることを確認する	playwright-cli -s={session} eval "() => document.title" を実行してから、結果を確認する

待機操作

ワークフローの言語	CLI コマンド（Bash 経由）
[element] が表示されるまで待機する	playwright-cli -s={session} snapshot をループでポーリングし（最大 3s、間隔 500ms）、テキストを確認する
[element] が消えるまで待機する	playwright-cli -s={session} snapshot をループでポーリングし、テキストが消えたことを確認する
[N] 秒待機する	sleep [N]
読み込みが完了するまで待機する	playwright-cli -s={session} snapshot をループでポーリングし、「Loading」テキストが消えたことを確認する

ファイルのアップロード

ワークフローの言語	CLI コマンド（Bash 経由）
「[filename]」をアップロードする	playwright-cli -s={session} upload "[absolute-path]"

テストデータファイルの解決

Upload ステップを実行する際は、次の優先順位でアップロードするファイルを解決します。

1. ワークフローでパスが指定されている場合：Upload ステップで特定のファイルが指定されている場合（例：Upload "test-fixtures/valid-deck.pptx"）、そのパスをそのまま使用します。相対パスは、プロジェクトルートからの絶対パスに変換します。
2. プロファイルに一致するファイルがある場合：Upload ステップでパスなしのファイル名が指定されている場合（例：Upload "valid-deck.pptx"）、読み込まれたプロファイルの files 配列を確認し、ファイル名が一致するエントリを探します。見つかった場合は、その path を使用するか、url からダウンロードします。
3. プロファイルにファイルがあり、ステップが汎用的な場合：Upload ステップで汎用的な説明が使用されている場合（例：Upload a file to the dropzone）、かつプロファイルに files がある場合は、利用可能なファイルをユーザーに提示し、どれを使用するか尋ねます。
4. プロファイルにファイルがない場合：Upload ステップをそのまま実行し、ユーザーが対話形式でファイルを指定します。

受け入れ基準の検証

Upload ステップの完了後、読み込まれたプロファイルに acceptance 基準がある場合（および／または選択したファイルに上書き設定がある場合）、該当する各基準を自動的に検証します。

1. 有効な基準を計算する：ファイルレベルの acceptance（存在する場合）をプロファイルレベルの acceptance に対して浅くマージします。

   effective = { ...profile.acceptance, ...file.acceptance }
   

2. 各基準を検証する：スナップショットを使用して現在のページ状態を確認します。

   基準	検証方法
   uploadAccepted: true	アップロード後のスナップショットに、エラーのトースト／メッセージ／検証エラーが表示されていない
   uploadAccepted: false	スナップショットにエラーメッセージまたは検証エラーが表示されている
   processingCompletes: true	処理中を示すインジケーターが最終状態に変わるまで、スナップショットをポーリングする（最大 60 秒）
   resultDownloadable: true	スナップショットにダウンロードボタン、リンク、または「完了」を示すインジケーターが表示されている
   errorExpected: true	スナップショットにエラーメッセージが表示され、アプリが引き続き機能している（クラッシュしていない）
   expectedStatus: "X"	ステータスバッジ／インジケーター領域に「X」と一致するテキストがスナップショットに含まれている

3. 実行結果に記録する：

   Upload acceptance verification:
     ✓ uploadAccepted: PASS (no error message displayed)
     ✓ processingCompletes: PASS (status reached "clear" after 12s)
     ○ resultDownloadable: INCONCLUSIVE (no clear download indicator found)
   

PASS には ✓、FAIL には ✗、INCONCLUSIVE（スナップショットから基準を確実に検証できなかった場合）には ○ を使用します。

4. 失敗しても処理を止めない：結果を記録し、実行を続けます。受け入れ基準の検証は観察を目的としたものであり、ゲートではありません。

セッション管理（複数ユーザー）

ワークフローの記述	CLI コマンド（Bash 経由）
[persona] のビューに切り替える	persona の名前付きセッションを使用します：playwright-cli -s=runner-{persona} ...
[persona] 用に新しいセッションを開く	playwright-cli -s=runner-{persona} open "{base_url}"
アクティブなセッションをすべて一覧表示する	playwright-cli list

スクリーンショットとデバッグ

ワークフローの記述	CLI コマンド（Bash 経由）
スクリーンショットを撮る	playwright-cli -s={session} screenshot
現在のページ状態を取得する	playwright-cli -s={session} snapshot
コンソールのエラーを確認する	playwright-cli -s={session} console error

---

ステップ解釈ガイド

すべてのステップで、次の手順に従います：（1）[admin] のような persona タグがあるか確認し、その persona の名前付きセッション（runner-admin）を使用します。（2）主な動詞を特定し、上記のアクション対応表に照らし合わせます。（3）要素を対象とするアクションでは、まず playwright-cli -s={session} snapshot を実行し、テキスト／ラベル／プレースホルダー／testid で対象要素を見つけて、その ref を取得してから実行します。（4）アクションの後、再度 playwright-cli -s={session} snapshot を実行し、検証サブステップで合格／不合格を確認します。

曖昧なステップへの対応

ステップで要素が曖昧に指定されている場合（例：「ボタンをクリックする」で、どのボタンか指定されていない場合）、playwright-cli -s={session} snapshot でスナップショットを取得し、一致する要素を一覧表示します。一致する要素が 1 つならそれをクリックし、複数ある場合はコンテキストから最も適切なものを推定してクリックします。結果が予想外でも、ステップを "failed" ではなく "ambiguous" として記録します。

手動ステップの処理

[MANUAL] とマークされたステップは、Playwright CLI では実行できません。result: "skipped" および reason: "manual_step" を指定してステップタスクを作成し、次に実行可能なステップへ進んでください。

---

フェーズ 4：実行レポート

すべてのワークフローを実行した後、構造化された概要を作成します。

ステップ 1：レポートタスクの作成

TaskCreate:
  title: "Report: Execution Summary"
  status: "in_progress"

ステップ 2：結果の集計

すべてのワークフロータスクとステップタスクを確認し、最終レポートを作成します。以下を計算してください。

• 実行したワークフローの合計数
• 成功したワークフロー数（すべてのステップが成功）
• 失敗したワークフロー数（いずれかのステップが失敗）
• 一部成功したワークフロー数（成功と失敗が混在）
• 実行したステップの合計数
• 成功／失敗／スキップしたステップ数
• 検出した問題の数（Issue タスクの数）

ステップ 3：レポートの提示

次の形式で実行レポートをユーザーに提示します。

Workflow Execution Report
=========================
Platform: [desktop/mobile/multi-user] | Base URL: [URL] | Date: [date]

Overall: [X] passed, [Y] failed, [Z] partial out of [N] workflows

Workflow Results:
  [pass] Workflow 1: User Registration (8/8 steps)
  [FAIL] Workflow 3: Create New Post (6/8 steps)
    - Step 4 FAILED: "Publish" button not found
    - Step 7 FAILED: URL did not change to /posts/

Issues: [N] total (each with expected/actual state and screenshot path)

Summary: [N] workflows, [S] steps, [P] passed, [F] failed, [M] skipped

フェイルファストモードのレポート： フェイルファストモードで実行する場合、レポートの形式が変わります。

Overall: [X] passed, [Y] failed, [Z] skipped (not attempted) out of [N] workflows

「skipped」の数は、ランナーが最初の失敗で停止したため、開始されなかったワークフローの数を表します。フェイルファストモードでは一部成功という結果にはなりません。ワークフロー全体が成功するか、実行全体が停止するかのどちらかです。

ステップ 4：レポートファイルの書き込み

実行レポートを /workflows/execution-report-[platform]-[date].md に書き込みます。

1. Format the report as markdown.
2. Write to /workflows/execution-report-[platform]-[YYYY-MM-DD].md.
3. Inform the user of the file location.

ステップ 5：レポートタスクとメインタスクの完了

TaskUpdate:
  title: "Report: Execution Summary"
  status: "completed"
  metadata:
    report_path: "/workflows/execution-report-desktop-2025-01-20.md"
    workflows_passed: 20
    workflows_failed: 2
    workflows_partial: 1
    total_steps: 142
    steps_passed: 136
    steps_failed: 4
    steps_skipped: 2

TaskUpdate:
  title: "Run: [Platform] Workflows"
  status: "completed"
  metadata:
    platform: "desktop"
    base_url: "http://localhost:3000"
    result: "partial"
    workflows_passed: 20
    workflows_failed: 2
    workflows_partial: 1
    issues_found: 3
    report_path: "/workflows/execution-report-desktop-2025-01-20.md"

最終概要

完了メッセージをユーザーに提示します。

Workflow execution complete.

Report: /workflows/execution-report-desktop-2025-01-20.md

Results: 20 passed, 2 failed, 1 partial (23 total)
Issues: 3 issues captured with screenshots

Next steps:
  - Review the execution report for failure details
  - Fix the issues identified in the report
  - Re-run with "run desktop workflows" to verify fixes
  - Convert passing workflows to CI tests with "convert desktop workflows to playwright"

---

フェーズ 5：セッションの振り返り

完了する前に、references/reflection-protocol.md を読み込み、記載された手順を実行します。

---

セッションの復旧

スキルが呼び出され、既存のタスクリストが見つかった場合は、この判断ツリーを使って再開位置を決定します。

判断ツリー

Check TaskList for "Run: [Platform] Workflows"

CASE 1: No task list exists
  -> Start from Phase 1

CASE 2: Auth task is "in_progress"
  -> Authentication was started but not completed
  -> Re-attempt authentication from Phase 2

CASE 3: Auth task is "completed", one or more workflow tasks exist
  -> Find the last workflow task with status "in_progress"
  -> Find the last step task within that workflow
  -> If step is "in_progress": re-attempt that step
  -> If step is "completed": move to the next step
  -> Resume execution from that point

CASE 4: All workflow tasks are "completed", no Report task
  -> All workflows have been executed
  -> Resume from Phase 4 (generate report)

CASE 5: Report task is "completed"
  -> Everything is done
  -> Show the existing report and ask if the user wants to re-run

CASE 6: Some workflow tasks are "completed", none "in_progress"
  -> Execution was interrupted between workflows
  -> Find the first workflow task with status "pending" or missing
  -> Resume from that workflow

再開時は必ずユーザーに伝える

I found an existing execution session for [platform] workflows.

Current state: [describe where things left off]
  - Workflows completed: [N] of [M]
  - Last workflow: [name]
  - Last step: [step description]

I will resume from [next workflow/step]. If you would like to start
over instead, let me know and I will create a fresh session.

---

モバイル実行の詳細

モバイルワークフローを実行する際、ランナーはモバイルのビューポートをシミュレートし、タッチ操作を前提とした UI パターンを考慮する必要があります。

ビューポートの設定

モバイルワークフローのステップを実行する前に、ビューポートを設定します。

playwright-cli -s=runner-mobile resize 393 852

これは iPhone 14 Pro の画面をシミュレートします。ビューポートは実行開始時に一度設定し、実行中はその状態を維持する必要があります。

モバイル固有のアクションの対応付け

モバイルワークフローでは、タッチ操作を前提とした表現が使われることがあります。以下のように、同等の Playwright CLI コマンドに対応付けてください。

モバイルワークフローの表現	CLI コマンド（Bash 経由）
「[label]」ボタンをタップする	playwright-cli -s={session} click {ref}（Playwright ではタップはクリックに相当）
[element] を左にスワイプする	タッチスワイプをシミュレートするには playwright-cli -s={session} eval "() => { ... }" {ref} を使うか、playwright-cli -s={session} press ArrowLeft を実行します
下にスワイプして更新する	playwright-cli -s={session} reload
[element] を長押しする	playwright-cli -s={session} click {ref}（長押しは直接サポートされていないため、制限事項を記録してください）
下に引っ張って更新する	playwright-cli -s={session} reload
戻る矢印をタップする	playwright-cli -s={session} go-back
リストの最下部までスクロールする	playwright-cli -s={session} eval "() => window.scrollTo({ top: document.body.scrollHeight, behavior: 'smooth' })"

モバイル検証パターン

モバイルのレイアウトはデスクトップとは異なります。モバイル固有の要素を検証する場合は、以下を確認してください。

• 下部ナビゲーションバー -- スナップショットで下部ナビゲーションの項目が表示されていることを確認します。
• ハンバーガーメニュー -- まずメニューアイコンをクリックし、次にスナップショットでスライドアウトメニューが表示されることを確認します。
• 固定ヘッダー -- 下にスクロールし、スナップショットでヘッダーが表示されたままであることを確認します。
• タッチターゲット -- 要素が 44x44px より小さく見える場合は記録します（getBoundingClientRect() を使って eval で測定できます）。

---

マルチユーザー実行の詳細

マルチユーザーワークフローでは、同じアプリケーション内で複数のペルソナが同時または順番に操作します。ランナーは、各ペルソナをシミュレートするために別々のブラウザータブを使用します。

セッション管理

Persona-to-session mapping (established during Phase 2):
  admin -> runner-admin
  user  -> runner-user
  guest -> runner-guest

ペルソナが指定された各ステップの前に、次を実行します。

1. Read the persona tag: [admin], [user], [guest]
2. Use that persona's named session for all commands
3. Execute the step: playwright-cli -s=runner-{persona} <command>
4. playwright-cli -s=runner-{persona} snapshot to verify the outcome

ペルソナ間の検証

複数ユーザーのワークフローでは、あるペルソナの操作が別のペルソナから見えることを検証する必要がよくあります。パターンは次のとおりです。

Step N: [admin] Approve the post
  1. playwright-cli -s=runner-admin click {approve-ref}
  2. playwright-cli -s=runner-admin snapshot       # verify in admin view

Step N+1: [user] Verify post shows as approved
  1. playwright-cli -s=runner-user reload
  2. playwright-cli -s=runner-user snapshot         # verify in user view

タブを切り替える必要はありません。各ペルソナには完全に分離された独自のセッションがあります。

並行処理のシミュレーション

タブを順次切り替える方法では、真の並行処理は実行できません。「同時に」や「同じタイミングで」と指定されているワークフローでは、操作を短い間隔で順次実行してください。

"[admin] and [user] both open the document editor"
  1. playwright-cli -s=runner-admin goto "{base_url}/editor/doc-1"
  2. playwright-cli -s=runner-user goto "{base_url}/editor/doc-1"
  3. playwright-cli -s=runner-admin snapshot    # verify editor loaded
  4. playwright-cli -s=runner-user snapshot     # verify editor loaded + admin's presence

セッションが分かれているため、手順 1 と 2 は並行して実行することもできます（並列の Bash 呼び出しを使用）。

手順のメタデータに、真の並行処理を順次実行によってシミュレーションしたことを記録してください。

ペルソナの認証情報の管理

フェーズ 2 では、セッション中、ペルソナの認証情報をメモリに保存してください。

personas = {
  admin: { email: "[email protected]", tab_index: 0 },
  user:  { email: "[email protected]",  tab_index: 1 },
  guest: { email: "[email protected]", tab_index: 2 }
}

認証情報をディスクに書き込んだり、タスクのメタデータ、レポート、出力ファイルに含めたりしないでください。

---

エラー処理

アプリケーションが起動していない

playwright-cli -s={session} goto でベース URL にアクセスできない場合、またはエラーページが返される場合：

1. Inform the user: "Cannot reach [base_url]. Is the application running?"
2. Use AskUserQuestion to ask if they want to:
   a. Provide a different URL
   b. Wait and retry
   c. Cancel execution
3. If retry: sleep 5, then attempt navigation again.

認証の失敗

ログインフローでリダイレクトが正常に行われない場合：

1. Run playwright-cli -s={session} snapshot to capture the current state.
2. Check for error messages in the snapshot (e.g., "Invalid credentials").
3. Inform the user of the specific error.
4. Ask if they want to provide different credentials or skip auth.

要素が見つからない

手順で指定されている要素がスナップショット内に見つからない場合：

1. Run playwright-cli -s={session} snapshot.
2. Log the full snapshot content in the step task metadata.
3. Mark the step as "failed" with reason "element_not_found".
4. Include the element description and what was found instead.
5. Continue to the next step.

タイムアウト／ページの読み込み失敗

妥当な時間内にページが読み込まれない場合：

1. sleep 10
2. playwright-cli -s={session} snapshot to check if the page eventually loaded.
3. If still not loaded, mark the step as "failed" with reason "timeout".
4. playwright-cli -s={session} screenshot for evidence.
5. Continue to the next step.

想定外のダイアログ／ポップアップ

実行中に想定外のダイアログが表示された場合：

1. playwright-cli -s={session} dialog-accept (dismiss it to continue).
2. Log the dialog in the step task metadata.
3. Continue with the current step.

ブラウザーのコンソールエラー

各ワークフローの最後に、必要に応じてコンソールエラーを確認してください。

1. playwright-cli -s={session} console error
2. If errors are found, log them in the workflow task metadata.
3. These do not cause step failures but are included in the report.

---

ワークフロー作成標準との互換性

このランナーは、ジェネレータースキルで使用されるワークフロー作成標準に完全に準拠しています。標準の動詞形式（Navigate、Click、Type、Select、Check、Uncheck、Toggle、Clear、Scroll、Hover、Wait、Verify、Upload、Drag、Press、Refresh）はすべて、上記のアクションマッピングリファレンスに記載されている playwright-cli コマンドに直接対応します。ランナーは各手順の行頭にあるこれらの動詞を認識し、Bash 経由で対応する CLI コマンドを実行します。

---

スナップショット優先の実行パターン

Playwright CLI はスナップショット駆動型です。CSS セレクターを使用する Playwright API のコードとは異なり、CLI はスナップショット内の要素参照を使用します。要素を対象とするすべての操作は、次のパターンに従います。

PATTERN: Snapshot -> Find -> Act -> Verify

1. SNAPSHOT: Run `playwright-cli -s={session} snapshot` via Bash.
   The snapshot returns a YAML accessibility tree with all visible elements
   and their refs (e.g., ref=e12).

2. FIND: Search the snapshot output for the target element.
   Match by: visible text, role, label, placeholder, or test ID.
   Extract the element's ref value.

3. ACT: Run the appropriate CLI command with the ref via Bash.
   Example: `playwright-cli -s={session} click e12`

4. VERIFY: Run `playwright-cli -s={session} snapshot` again via Bash.
   Check that the expected outcome is present in the updated snapshot.

このパターンは基本です。要素参照を見つけるためにスナップショットを取得する前に、要素をクリック、入力、操作しようとすることは絶対に避けてください。要素参照は一時的なもので、スナップショットごとに変わります。必ず直近のスナップショットから取得した要素参照を使用してください。

実行シーケンスの例

手順：Click the "Save Changes" button の場合

1. playwright-cli -s={session} snapshot
   -> Returns: ... button "Save Changes" [ref=e47] ...

2. playwright-cli -s={session} click e47
   -> Button is clicked

3. playwright-cli -s={session} snapshot
   -> Returns: ... text "Changes saved successfully" ...
   -> Verification: success text found -> PASS

手順：Type "[email protected]" in the email field の場合

1. playwright-cli -s={session} snapshot
   -> Returns: ... textbox "Email" [ref=e23] ...

2. playwright-cli -s={session} fill e23 "[email protected]"
   -> Text is entered

3. playwright-cli -s={session} snapshot
   -> Returns: ... textbox "Email" value="[email protected]" [ref=e23] ...
   -> Verification: field value matches -> PASS

---

制約

• Bash 経由の CLI のみ -- このスキルでは、すべてのブラウザー操作に Bash ツール経由で playwright-cli コマンドを使用します。ブラウザー操作はすべて playwright-cli -s={session} <command> の呼び出しで行います。MCP ツールの使用、Playwright コードの生成、npx playwright test の実行は行いません。
• ファイルを生成しない -- このスキルではテストファイルを生成しません。ワークフローを対話形式で実行し、実行レポートを作成します。CI 用の Playwright テストプロジェクトを生成するには、コンバータースキルを使用してください。
• 失敗しても続行 -- ステップが失敗した場合、ランナーは失敗を記録して次のステップに進みます。単一の失敗が原因でワークフローや実行全体を中断することはありません。
• 認証情報はメモリ内のみ -- ユーザーの認証情報はセッション内に保持され、ディスク、タスクのメタデータ、出力ファイルには書き込まれません。
• 操作の前にスナップショットを取得 -- 要素を操作する際は、事前に必ず playwright-cli -s={session} snapshot を実行して要素の参照 ID を取得します。参照 ID は一時的なもので、スナップショットをまたいでキャッシュしてはいけません。
• レポートは必ず書き込む -- すべてのワークフローが成功した場合でも、ランナーは実行レポートファイルを書き込みます。
• ビューポートを維持 -- モバイル実行では、393x852 のビューポートを一度設定し、実行中はそのまま維持する必要があります。実行中にサイズを変更しないでください。
• ペルソナごとに 1 セッション -- 複数ユーザーでの実行では、ペルソナごとに名前付きセッション（例：runner-admin、runner-user）を 1 つ使用します。セッションは認証設定時に開き、実行中はそのまま再利用します。実行中にペルソナのセッションを閉じないでください。実行全体の完了後にのみ playwright-cli close-all を実行してください。