use-profiles

Playwright 認証プロファイルの使用

目的

ブラウザー自動化を行う前に、保存済みの Playwright storageState 認証プロファイルを読み込みます。これにより、ブラウザーセッションを開始するたびに手動でログインする必要がなくなります。

適用条件

以下のすべてに該当する場合、このスキルが適用されます。

1. 現在のプロジェクトに .playwright/profiles.json ファイルがある
2. ブラウザー自動化を開始しようとしている（Bash 経由で Playwright CLI を使用）
3. 対象ページで認証が必要である

プロファイルの確認

プロジェクトのルートで .playwright/profiles.json を確認します。利用可能なプロファイルを見つけるために、ファイルを読み込みます。ファイルには、次のようなエントリーが含まれています。

{
  "profiles": {
    "admin": {
      "loginUrl": "https://example.com/login",
      "description": "Full permissions",
      "createdAt": "2026-03-31T12:00:00Z"
    }
  }
}

各プロファイルには、対応する .playwright/profiles/<role-name>.json の storageState ファイルがあります。

プロファイルの選択

会話の文脈に基づいて、使用するプロファイルを決定します。

• ユーザーが特定のロール（例：「管理者ダッシュボードをテストする」「スピーカービューを確認する」）に言及した場合、そのロールを設定ファイルのプロファイル名と照合します。
• ユーザーがロールを指定せず、プロファイルが1つだけの場合は、自動的に使用します。
• ユーザーがロールを指定せず、複数のプロファイルがある場合は、どれを使用するか尋ねます。利用可能なプロファイルとその説明を提示します。

プロファイルの読み込み

認証が必要なページに移動する前に、Bash ツール経由で playwright-cli を使用してプロファイルを読み込みます。以下の {session} プレースホルダーは、現在の名前付きセッション（例：runner-desktop、qa-ux）を指します。これは、呼び出し元のスキルまたはコマンドによって設定されます。

1. .playwright/profiles/<role-name>.json に storageState ファイルがあることを確認します。ファイルがない場合はユーザーに伝え、作成するために /setup-profiles の実行を提案します。

2. プロファイルの Cookie と localStorage をブラウザーセッションに読み込みます。

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

   これにより、storageState JSON からすべての Cookie とオリジンごとの localStorage が復元されます。Playwright の storageState() と同じ形式です。

3. プロファイル JSON に sessionStorage フィールドが含まれている場合（標準の storageState には含まれず、/setup-profiles によって追加されます）、対象オリジンに移動した後、別途復元します。

   playwright-cli -s={session} goto "<origin>"
   

   次に、sessionStorage の各エントリーについて、以下を実行します。

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

4. 認証が必要な対象ページに移動します。Cookie はリクエストとともに送信され、localStorage はすでに読み込み済みで、sessionStorage も復元されているため、サーバー側、クライアント側、SPA の認証ライブラリ（Supabase、Firebase、Auth0）がセッションを認識します。

テストデータファイルと受け入れ基準

プロファイルを読み込んだ後、profiles.json に files 配列や acceptance オブジェクトがあるか確認します。これらは任意のフィールドであり、含まれていないプロファイルも多数あります。

利用可能なファイルの提示

プロファイルに files がある場合、概要を呼び出し元に伝えます。

このプロファイルには、利用可能なテストデータファイルが N 個あります。

1. valid-deck.pptx — 問題のないデッキで、すべてのチェックに合格します
2. profanity-deck.pptx — ノートに不適切な表現が含まれており、検出されるはずです
3. (cloud) oversized-deck.pptx — 200MB のデッキで、サイズ制限をテストします

プロファイルの受け入れ基準：アップロードが受け付けられ、処理が完了する

クラウド上のファイル（path ではなく url が指定されているファイル）には、区別できるように (cloud) を付けます。

この情報は提示するだけで、このスキルでは利用しません。利用するかどうか、また利用方法は、利用側（ワークフロー生成ツール、ランナー、エージェント）が決定します。

ファイルパスの検証

path フィールドがある各ファイルエントリーについて、プロジェクトルートからの相対パスで指定された場所にファイルが存在することを確認します。ファイルが見つからない場合は、次のように警告します。

プロファイル「speaker」は、存在しないテストファイル「test-fixtures/valid-deck.pptx」を参照しています。ファイルが移動または削除された可能性があります。

ファイルが見つからなくても処理を失敗させたり、ブロックしたりしないでください。警告するだけにします。url があるファイルは検証しません（認証が必要な場合や、プライベートネットワーク上にある場合があります）。

受け入れ基準の概要

プロファイルに acceptance がある場合、設定された基準を人が読める形式で要約します。フィールドは次のように対応付けます。

フィールド	要約テキスト
uploadAccepted: true	アップロードが受け入れられる
processingCompletes: true	処理が完了する
resultDownloadable: true	結果をダウンロードできる
errorExpected: true	エラーが予想される
expectedStatus: "clear"	予想されるステータス："clear"

個々のファイルに acceptance のオーバーライドがある場合は、プロファイルのデフォルト設定をオーバーライドするファイルを示します。

ファイル "corrupted.pptx" はプロファイルの受け入れ基準をオーバーライドします：アップロードが拒否され、エラーが予想されます

セッション有効期限の検出

プロファイルを読み込み、対象ページに移動した後、次のヒューリスティックを順に使ってセッションが引き続き有効かどうかを確認します。

1. URL リダイレクト： ブラウザーがプロファイル設定の loginUrl に一致する URL にリダイレクトされた場合、セッションの有効期限が切れている可能性があります。スナップショット出力の Page URL 行で URL を確認します。
2. 認証プロバイダーへのリダイレクト： 最終 URL が別のドメイン（例：accounts.google.com、auth0.com）にある場合、アプリは OAuth プロバイダーにリダイレクトされています。セッションの有効期限が切れています。
3. ページコンテンツの確認： Bash 経由で playwright-cli -s={session} snapshot を実行し、ログイン関連の要素（サインインフォーム、「Log in」／「Sign in」ボタン、「session expired」というテキスト）を探します。対象ページに認証済みコンテンツが表示される想定なのに、代わりにログイン UI が表示される場合、セッションの有効期限が切れています。

有効期限切れが検出された場合：

• プロファイルのセッションの有効期限が切れているようであることをユーザーに伝えます
• /setup-profiles を実行して更新するよう提案します
• 自動的なログインは試みないでください

これらのヒューリスティックはベストエフォートです。ユーザーはいつでも /setup-profiles を手動で実行して、任意のプロファイルを更新できます。

プロファイルが見つからない場合

.playwright/profiles.json が存在していても、参照されているプロファイルの storageState ファイルが見つからない場合（例：新規クローン直後）は、次のようにユーザーに伝えます。

"このプロジェクトには Playwright プロファイルが設定されていますが、認証状態ファイルがありません（これらのファイルは gitignore されるため、ローカルで作成する必要があります）。認証するには /setup-profiles を実行してください。"

プロファイル設定がない場合

.playwright/profiles.json が存在しない場合、このスキルは適用されません。ユーザーが認証済みのブラウザー自動化について明示的に尋ねている場合を除き、プロファイルの作成を提案しないでください。