screenshots

最近の変更の影響を受けたコンポーネントのスクリーンショットを、実行中のアプリケーション（E2E 認証を使用）または Storybook から撮影します。

使用方法：

• /screenshots — 変更されたコンポーネントを検出し、自動的にスクリーンショットを撮影します
• /screenshots navigate to /settings, open the "Profile" tab, screenshot the form — カスタム指示に従ってスクリーンショットを撮影します

手順：

1. カスタム指示を確認します：

   • $ARGUMENTS が指定されていて空でない場合は、手順 2（前提条件）を実行してから、**手順 6（カスタム指示モード）**に進みます
   • $ARGUMENTS が空の場合は、以下の自動検出フロー（手順 2～5、その後 7～10）に進みます

2. 前提条件を確認します：

   • playwright-cli --help を実行して、Playwright CLI が利用可能であることを確認します
   • コマンドが失敗した場合（見つからない、またはエラーが発生した場合）は、次のメッセージを表示して停止します：

     ## 前提条件が不足しています：Playwright CLI
     
     Playwright CLI がインストールされていません。このスキルでスクリーンショットを撮影するには、Playwright CLI が必要です。
     
     次のコマンドでインストールしてください：npm install -g @playwright/cli@latest
     

3. ベースブランチを決定します：

   • 現在のディレクトリに .agent ファイルがあるか確認します。ファイルに baseBranch=<value> の行が含まれている場合は、その値をベースブランチとして使用します
   • .agent ファイルがない場合、または baseBranch キーがない場合は、main をデフォルトとして使用します

4. 変更されたコンポーネントを特定します：

   • git diff --name-only $(git merge-base HEAD <base-branch>)..HEAD を実行して、ベースブランチと比較して最近変更されたファイルを特定します
   • コンポーネントファイルを対象とします：拡張子が .tsx、.jsx、.vue、.svelte のファイル
   • テストファイル（*.test.*、*.spec.*）、ストーリーファイル（*.stories.*）、型定義ファイル（*.d.ts）は除外します
   • 変更にコンポーネントファイルがない場合は、開発者に伝えて停止します
   • 変更されたコンポーネントの一覧を開発者に提示します

5. 開発者に「アプリと Storybook のどちらを使用しますか？」と尋ねます：

   • AskUserQuestion を使って、コンポーネントごと（または数が多い場合はまとめて）に尋ねます：
     • Storybook — コンポーネントにストーリーがある場合は、Storybook からスクリーンショットを撮影します
     • App — 実行中のアプリケーションにコンポーネントが表示される場合に選択します
     • Skip — このコンポーネントのスクリーンショットは撮影しません

6. カスタム指示モード（$ARGUMENTS が指定されている場合）：

   このモードでは、スクリーンショットを撮影する対象を開発者が全面的に指定できます。$ARGUMENTS に記述された指示に従って、訪問するページ、実行する操作（ボタンのクリック、フォームへの入力、メニューを開くなど）、スクリーンショットを撮影するタイミングを決定します。一時的な E2E テストを作成して実行し、その後テストファイルを元に戻すことで、スクリーンショットを撮影します。

   a. E2E テストのセットアップを調査します：

   • 既存の E2E／Playwright テストファイルをコードベース内で検索します（例：*.e2e.ts、*.e2e-spec.ts、e2e/、tests/ 配下のファイル、または Playwright のテストディレクトリ）
   • テストランナーの設定ファイル（例：playwright.config.ts）を特定し、ベース URL、テストディレクトリ、グローバルセットアップ（認証、ストレージ状態など）を確認します
   • 既存のテストで認証をどのように処理しているかを確認し、同じ方法（例：storageState、グローバルセットアップ、beforeEach でのログイン）を再利用します b. 一時的な E2E テストファイルを作成します：
   • プロジェクトの E2E テストディレクトリに、既存の規約に従って新しいテストファイルを作成します（例：e2e/tmp-screenshots.e2e.ts）。
   • テストでは、以下を行います。
     • プロジェクトで既に使用されている認証パターンを使って認証を処理します。
     • $ARGUMENTS で指定されたページ／ルートに移動します。
     • 要求された操作（要素のクリック、入力欄への入力、オプションの選択、ホバー、スクロールなど）を実行します。
     • スクリーンショットを撮る前に、毎回アニメーション／トランジションが完了するまで待機します。page.waitForTimeout() を使うか、特定の CSS 状態（例：要素の opacity: 1、トランジションクラスの削除、要素が安定した状態になること）を待ちます。モーダルやオーバーレイの場合は、撮影前に開くアニメーションが完全に終わっていることを確認します。
     • page.screenshot({ path: '.tmp/<descriptive-name>.png' }) または対象を絞って撮影する場合は element.screenshot() を使ってスクリーンショットを撮ります。
     • ページや操作の状況が分かる、説明的なファイル名を付けます（例：.tmp/settings-profile-tab.png、.tmp/modal-confirm-delete.png）。
   • .tmp/ ディレクトリが存在しない場合は作成します：mkdir -p .tmp

   c. 一時テストを実行します：

   • プロジェクトの Playwright テストコマンドを使って、一時テストファイルのみを実行します（例：playwright-cli test e2e/tmp-screenshots.e2e.ts）。
   • テストが失敗した場合は、エラーを表示し、修正を試みて再実行します。妥当な範囲で試してもなお失敗する場合は、エラーを表示してクリーンアップに進みます。

   d. 結果を確認します：

   • Read ツールを使って生成された各スクリーンショットを確認し、開発者に提示します。

   e. クリーンアップ — 一時テストファイルを元に戻します：

   • 既存のテストファイルを変更した場合は、git restore <test-file-path> を実行して元に戻します。
   • 新規作成したテストファイルの場合は、rm <test-file-path> を実行して削除します。
   • git status で、一時的なテストの変更が残っていないことを確認します。

   f. 概要：

   • すべてのスクリーンショットを撮影してクリーンアップを終えた後、保存したファイルとそれぞれに写っている内容を一覧にして提示します。
   • その後、停止します（自動検出の手順には進みません）。

7. Storybook のパスを使うコンポーネントの場合：

   a. 対応するストーリーファイルを探します：

   • コンポーネントの隣、または同じディレクトリにある .stories.tsx、.stories.jsx、.stories.ts、.stories.js ファイルを探します。
   • ストーリーファイルが見つからない場合は、開発者に伝えてこのコンポーネントをスキップします。

   b. ストーリーメタデータを抽出します：

   • ストーリーファイルを読み取ります。
   • デフォルトエクスポートから meta.title（または default.title）を抽出します。
   • デフォルトエクスポートおよびストーリーではないエクスポート（args、argTypes など）を除き、すべての名前付きエクスポート（ストーリー名）を抽出します。

   c. ストーリー URL を作成します：

   • タイトルをケバブケースに変換します。スペース、/、特殊文字を - に置き換え、すべて小文字にします。
   • 各ストーリー名をケバブケースに変換します。
   • ストーリー ID を作成します：<title-kebab-case>--<story-name-kebab-case>
   • iframe URL を作成します：http://localhost:6006/iframe.html?id=<story-id>&viewMode=story

   d. Storybook が起動していることを確認します：

   • http://localhost:6006 にアクセスできるか確認します（例：curl -s -o /dev/null -w "%{http_code}" http://localhost:6006）。
   • Storybook が起動していない場合（接続拒否、または 200 以外のレスポンス）は、開発者に起動を依頼し、確認が取れるまで待ちます。

   e. スクリーンショットを撮影します：

   • .tmp/ ディレクトリが存在しない場合は作成します：mkdir -p .tmp
   • 各ストーリーについて、以下を実行します。

     playwright-cli screenshot --browser chromium --wait-for-timeout 2000 "<iframe-URL>" .tmp/<component-name>-<story-name>.png
     

   • ストーリーが複数ある場合は、並列でスクリーンショットを撮影します（Bash で & と wait を使用）。
   • --wait-for-timeout 2000 がデフォルトであることを開発者に伝えます。負荷の高いコンポーネントの場合は、待機時間を延ばすよう依頼できます。 f. 結果を確認する：
   • Read ツールを使って生成されたスクリーンショットをそれぞれ確認し、開発者に提示します

8. App パスを使用するコンポーネントの場合：

   実行中のアプリのスクリーンショットは、一時的な e2e テストを作成して実行した後、変更を元に戻すことで取得します。

   a. 移動先の URL／ルートを開発者に尋ねる：

   • AskUserQuestion を使って、実行中のアプリでコンポーネントが表示される URL またはルートを確認します
   • 目的の状態にするために必要な操作（例：「編集」ボタンをクリックする、「ドロップダウンを開く」）があるかどうかも尋ねます

   b. e2e テストのセットアップを調べる：

   • 既存の e2e／Playwright テストファイルと設定を検索します（手順 6a と同じです）
   • 既存のテストで認証をどのように処理しているか確認し、同じ方法を再利用します

   c. 一時的な e2e テストファイルを作成する：

   • プロジェクトの e2e テストディレクトリに新しいテストファイルを作成します（例：e2e/tmp-screenshots.e2e.ts）
   • テストでは、以下を行います。
     • プロジェクト既存の認証パターンを使って認証を処理する
     • 指定された URL／ルートに移動する
     • 目的のコンポーネントの状態にするために必要な操作を行う
     • 撮影前にアニメーション／トランジションの完了を待ちます。page.waitForTimeout() を使用するか、特定の CSS 状態（例：opacity: 1、トランジションクラスが削除された状態、要素が安定した状態）を待ちます。モーダル、ドロップダウン、オーバーレイでは、表示アニメーションが完全に終了するまで待ちます。
     • page.screenshot({ path: '.tmp/<component-name>-app.png' }) を使ってスクリーンショットを撮影するか、対象を絞って撮影する場合は element.screenshot() を使います
   • .tmp/ ディレクトリが存在しない場合は作成します：mkdir -p .tmp

   d. 一時テストを実行する：

   • 一時テストファイルのみを実行します（例：playwright-cli test e2e/tmp-screenshots.e2e.ts）
   • テストが失敗した場合は、エラーを表示して修正を試み、再実行します

   e. 結果を確認する：

   • Read ツールを使って生成されたスクリーンショットをそれぞれ確認し、開発者に提示します

   f. クリーンアップ — 一時テストファイルを元に戻す：

   • ファイルを新規作成した場合は、rm <test-file-path> を実行します
   • git status で一時的なテスト変更が残っていないことを確認します

9. まとめ：

   • すべてのスクリーンショットを撮影した後、以下のようにまとめを提示します。

     ## スクリーンショットの撮影完了
     
     `.tmp/` に保存しました：
     - .tmp/ComponentA-Default.png（Storybook）
     - .tmp/ComponentA-WithProps.png（Storybook）
     - .tmp/ComponentB-app.png（App - /dashboard）
     
     スクリーンショットは、プロジェクトの .tmp/ ディレクトリに保存されています。
     

10. 例外的なケースへの対応：

• スクリーンショットのコマンドが失敗した場合は、エラーを表示し、残りのスクリーンショットの撮影を続けます
• .tmp/ ディレクトリを作成できない場合は、エラーを表示して停止します
• ストーリーファイルに名前付きエクスポート（ストーリー）がない場合は、そのファイルをスキップし、開発者に伝えます
• 開発者がすべてのコンポーネントをスキップした場合は、その旨を伝えて停止します