playwright-skill

Playwright ブラウザー自動化

ユーザーの依頼に合わせた、目的を絞った Playwright スクリプトを作成して実行します。スキルの実行ツールとヘルパーを優先して使用しますが、必要に応じて Playwright API 全体を使用してください。

パスの解決

このスキルは複数の場所にインストールできるため、まずスキルのディレクトリを解決します。SKILL_DIR にこの SKILL.md ファイルがあるディレクトリを設定し、以下のコマンドをそのまま実行してください。

export SKILL_DIR=<absolute path of the directory containing this SKILL.md>
export TMP_DIR="$(node -p 'require("node:os").tmpdir()')"

コマンド間でシェルの状態が保持されない場合は、各コマンドの $SKILL_DIR と $TMP_DIR を実際のパスに置き換えてください。

一般的なインストール先：

• プラグインシステム：~/.claude/plugins/marketplaces/playwright-skill/skills/playwright-skill
• グローバルへの手動インストール：~/.claude/skills/playwright-skill
• プロジェクト固有：<project>/.claude/skills/playwright-skill

ワークフロー

1. localhost で作業する場合は、URL を記述する前に稼働中のサーバーを検出します。

   node -e "require('$SKILL_DIR/lib/helpers').detectDevServers().then(s => console.log(JSON.stringify(s)))"
   

   結果が 1 件のみの場合は、自動的にその結果を使用します。複数の結果がある場合は、どの URL を使うかユーザーに確認します。結果がない場合は、URL を尋ねるか、サーバーの起動を提案します。

2. ユーザーがプロジェクトへの保存を求めない限り、再利用可能なスクリプトは $TMP_DIR/playwright-test-*.js に作成します。PW_SCRIPT_DIR を使用してスクリプトを保持します。

3. デフォルトでは表示可能なブラウザーを使用します。headless: true を使用するのは、ユーザーから求められた場合、または環境にディスプレイがない場合のみです。

4. 対象 URL は定数または環境変数に指定します。

5. node "$SKILL_DIR/run.js" <script.js> を使ってスクリプトを実行します。

6. 実行した操作、失敗、成果物のパスを報告します。結果のページを確認するまでは、成功したと断言しないでください。

セットアップ

1 回だけ実行します。

cd "$SKILL_DIR" && npm run setup

これにより Playwright と Chromium がインストールされます。Firefox または WebKit が必要な場合は、cd "$SKILL_DIR" && npm run install-all-browsers を使用してください。

最小限の例

const os = require('node:os');
const path = require('node:path');
const { chromium } = require('playwright');

const targetUrl = process.env.TARGET_URL || 'http://localhost:3000';
const artifactDir = process.env.PW_ARTIFACT_DIR || os.tmpdir();

(async () => {
  const browser = await chromium.launch({ headless: false });
  try {
    const page = await browser.newPage();
    await page.goto(targetUrl);
    console.log('Page loaded:', await page.title());
    await page.screenshot({ path: path.join(artifactDir, 'page.png'), fullPage: true });
  } finally {
    await browser.close();
  }
})();

実行します。

node "$SKILL_DIR/run.js" "$TMP_DIR/playwright-test-page.js"

短時間で完了する単発のタスクでは、インライン実行を使用します。

node "$SKILL_DIR/run.js" -e "const browser = await chromium.launch({headless: false}); try { const page = await browser.newPage(); await page.goto('https://example.com'); console.log(await page.title()); } finally { await browser.close(); }"

-e プロセスはスニペットの処理が完了するとすぐに終了するため、スニペット内でブラウザーを閉じてください。

現在の Playwright のパターン

ユーザーが目にする内容を表すロケーターを、次の順で優先して使用してください。

1. アクセシブルな名前を指定した page.getByRole()
2. フォームコントロールには page.getByLabel()
3. 表示されているコンテンツには page.getByText()
4. アプリケーションがテスト用の契約を提供している場合は page.getByTestId()

アクションは実行可能な状態になるまで自動的に待機します。waitForSelector()、固定時間のスリープ、networkidle の代わりに、ウェブファーストのアサーションまたはロケーターの waitFor() を使用してください。

await page.getByLabel('Email').fill('[email protected]');
await page.getByRole('button', { name: 'Sign in' }).click();
await page.waitForURL('**/dashboard');
await page.getByRole('heading', { name: 'Dashboard' }).waitFor();

よくあるタスク

レスポンシブ表示の確認

{
  const os = require('node:os');
  const path = require('node:path');

  const artifactDir = process.env.PW_ARTIFACT_DIR || os.tmpdir();
  const viewports = [
    { name: 'desktop', width: 1440, height: 900 },
    { name: 'mobile', width: 390, height: 844 },
  ];

  for (const viewport of viewports) {
    await page.setViewportSize(viewport);
    await page.goto(targetUrl);
    await page.screenshot({ path: path.join(artifactDir, `${viewport.name}.png`), fullPage: true });
  }
}

ログインフロー

ユーザーから提供されたテスト用認証情報を使用してください。実際の認証情報を捏造したり、公開したりしないでください。ログイン後の遷移と、ログイン後に表示される要素の両方を確認してください。

await page.goto(`${targetUrl}/login`);
await page.getByLabel('Email').fill(process.env.TEST_EMAIL);
await page.getByLabel('Password').fill(process.env.TEST_PASSWORD);
await page.getByRole('button', { name: /sign in|log in/i }).click();
await page.waitForURL('**/dashboard');
await page.getByRole('heading', { name: /dashboard/i }).waitFor();

スクリプトと成果物の保存

PW_SCRIPT_DIR=./playwright-tests node "$SKILL_DIR/run.js" "$TMP_DIR/playwright-test-login.js"
PW_ARTIFACT_DIR=./playwright-artifacts node "$SKILL_DIR/run.js" "$TMP_DIR/playwright-test-page.js"

PW_SCRIPT_DIR はファイルベースのスクリプトを実行前にコピーし、同名のファイルがすでに存在する場合はタイムスタンプを追加します。PW_ARTIFACT_DIR はヘルパーがスクリーンショットを出力する場所を指定します。デフォルトはオペレーティングシステムの一時ディレクトリです。

既存の Chrome セッションへの接続

Chrome をリモートデバッグを有効にして起動し、Playwright から接続します。

const browser = await chromium.connectOverCDP('http://127.0.0.1:9222');
const page = browser.contexts()[0].pages()[0];

この方法では、そのセッションの Cookie と拡張機能を再利用します。ユーザーが明示的に求めない限り、機密情報には使用しないでください。接続したブラウザーからはユーザーのアクセス権限が利用されるためです。

ヘルパー

const helpers = require(`${process.env.PW_SKILL_DIR}/lib/helpers`);

const servers = await helpers.detectDevServers();
const browser = await helpers.launchBrowser('chromium');
const context = await helpers.createContext(browser);
const page = await context.newPage();
await helpers.handleCookieBanner(page);
await helpers.takeScreenshot(page, 'result');

利用可能なヘルパーは detectDevServers、getExtraHeadersFromEnv、launchBrowser、createContext、handleCookieBanner、takeScreenshot です。操作、待機、データ抽出、認証、テーブル、再試行には、Playwright のロケーターとアサーションを直接使用してください。

設定

• PW_BROWSER：launchBrowser() で使用する chromium、firefox、または webkit。
• PW_CHANNEL：chrome や msedge など、インストール済みのブラウザチャンネル。
• PW_EXECUTABLE_PATH：ブラウザー実行ファイルの明示的なパス。
• PW_HEADLESS：true または false。デフォルトではブラウザーを表示します。
• SLOW_MO：アクションの遅延時間（ミリ秒）。
• PW_HEADER_NAME と PW_HEADER_VALUE：追加する HTTP ヘッダーを 1 つ指定します。
• PW_EXTRA_HEADERS：追加する HTTP ヘッダーの JSON オブジェクト。
• PW_SCRIPT_DIR：ファイルベースのスクリプトを保持するディレクトリ。
• PW_ARTIFACT_DIR：ヘルパーが生成するスクリーンショットの保存先ディレクトリ。

ネットワークインターセプト、API モック、認証状態、動画、ビジュアルチェック、デバイスエミュレーション、CI のパターンについては、API_REFERENCE.md を参照してください。