重要 - パス解決: このスキルはさまざまな場所にインストールできます(プラグインシステム、手動インストール、グローバル、またはプロジェクト固有)。コマンドを実行する前に、このSKILL.mdファイルを読み込んだ場所に基づいてスキルディレクトリを決定し、以下のすべてのコマンドでそのパスを使用してください。$SKILL_DIR を実際に発見されたパスに置き換えてください。

一般的なインストールパス:

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

Playwright ブラウザ自動化

汎用ブラウザ自動化スキル。リクエストされたすべての自動化タスク用にカスタム Playwright コードを記述し、ユニバーサルエクスキューターで実行します。

重要なワークフロー - 以下のステップを順番に従ってください:

1. Dev サーバーの自動検出 - localhost テストの場合、常に最初にサーバー検出を実行します:

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

   • 1 つのサーバーが見つかった場合: 自動的に使用し、ユーザーに通知
   • 複数のサーバーが見つかった場合: どれをテストするかをユーザーに質問
   • サーバーが見つからない場合: URL を尋ねるか、dev サーバーを起動するのを手伝う

2. スクリプトを /tmp に書き込む - テストファイルをスキルディレクトリに書き込まない; 常に /tmp/playwright-test-*.js を使用

3. デフォルトでは表示されるブラウザを使用 - ユーザーが明示的にヘッドレスモードを要求しない限り、常に headless: false を使用

4. URL をパラメータ化 - 常に環境変数またはスクリプト上部の定数で URL を設定可能にする

仕組み

1. テスト/自動化したいことを説明する
2. 実行中の dev サーバーを自動検出する(外部サイトをテストする場合は URL を尋ねるか、dev サーバー起動を手伝う)
3. /tmp/playwright-test-*.js にカスタム Playwright コードを記述する(プロジェクトをクラッターさせない)
4. cd $SKILL_DIR && node run.js /tmp/playwright-test-*.js で実行する
5. 結果をリアルタイムで表示、デバッグ用にブラウザウィンドウが表示される
6. テストファイルは OS によって /tmp から自動クリーンアップされる

セットアップ(初回)

cd $SKILL_DIR
npm run setup

Playwright と Chromium ブラウザをインストールします。1 回限りです。

実行パターン

ステップ 1: Dev サーバーを検出(localhost テストの場合)

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

ステップ 2: URL パラメータを含むテストスクリプトを /tmp に書き込む

// /tmp/playwright-test-page.js
const { chromium } = require('playwright');

// パラメータ化された URL (自動検出またはユーザー提供)
const TARGET_URL = 'http://localhost:3001'; // <-- 自動検出またはユーザーから

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  await page.goto(TARGET_URL);
  console.log('Page loaded:', await page.title());

  await page.screenshot({ path: '/tmp/screenshot.png', fullPage: true });
  console.log('📸 Screenshot saved to /tmp/screenshot.png');

  await browser.close();
})();

ステップ 3: スキルディレクトリから実行

cd $SKILL_DIR && node run.js /tmp/playwright-test-page.js

一般的なパターン

ページをテスト(複数ビューポート)

// /tmp/playwright-test-responsive.js
const { chromium } = require('playwright');

const TARGET_URL = 'http://localhost:3001'; // 自動検出

(async () => {
  const browser = await chromium.launch({ headless: false, slowMo: 100 });
  const page = await browser.newPage();

  // デスクトップテスト
  await page.setViewportSize({ width: 1920, height: 1080 });
  await page.goto(TARGET_URL);
  console.log('Desktop - Title:', await page.title());
  await page.screenshot({ path: '/tmp/desktop.png', fullPage: true });

  // モバイルテスト
  await page.setViewportSize({ width: 375, height: 667 });
  await page.screenshot({ path: '/tmp/mobile.png', fullPage: true });

  await browser.close();
})();

ログインフローをテスト

// /tmp/playwright-test-login.js
const { chromium } = require('playwright');

const TARGET_URL = 'http://localhost:3001'; // 自動検出

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  await page.goto(`${TARGET_URL}/login`);

  await page.fill('input[name="email"]', 'test@example.com');
  await page.fill('input[name="password"]', 'password123');
  await page.click('button[type="submit"]');

  // リダイレクト待機
  await page.waitForURL('**/dashboard');
  console.log('✅ Login successful, redirected to dashboard');

  await browser.close();
})();

フォームに入力して送信

// /tmp/playwright-test-form.js
const { chromium } = require('playwright');

const TARGET_URL = 'http://localhost:3001'; // 自動検出

(async () => {
  const browser = await chromium.launch({ headless: false, slowMo: 50 });
  const page = await browser.newPage();

  await page.goto(`${TARGET_URL}/contact`);

  await page.fill('input[name="name"]', 'John Doe');
  await page.fill('input[name="email"]', 'john@example.com');
  await page.fill('textarea[name="message"]', 'Test message');
  await page.click('button[type="submit"]');

  // 送信を確認
  await page.waitForSelector('.success-message');
  console.log('✅ Form submitted successfully');

  await browser.close();
})();

破損したリンクをチェック

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  await page.goto('http://localhost:3000');

  const links = await page.locator('a[href^="http"]').all();
  const results = { working: 0, broken: [] };

  for (const link of links) {
    const href = await link.getAttribute('href');
    try {
      const response = await page.request.head(href);
      if (response.ok()) {
        results.working++;
      } else {
        results.broken.push({ url: href, status: response.status() });
      }
    } catch (e) {
      results.broken.push({ url: href, error: e.message });
    }
  }

  console.log(`✅ Working links: ${results.working}`);
  console.log(`❌ Broken links:`, results.broken);

  await browser.close();
})();

エラーハンドリング付きスクリーンショット取得

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  try {
    await page.goto('http://localhost:3000', {
      waitUntil: 'networkidle',
      timeout: 10000,
    });

    await page.screenshot({
      path: '/tmp/screenshot.png',
      fullPage: true,
    });

    console.log('📸 Screenshot saved to /tmp/screenshot.png');
  } catch (error) {
    console.error('❌ Error:', error.message);
  } finally {
    await browser.close();
  }
})();

レスポンシブデザインをテスト

// /tmp/playwright-test-responsive-full.js
const { chromium } = require('playwright');

const TARGET_URL = 'http://localhost:3001'; // 自動検出

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  const viewports = [
    { name: 'Desktop', width: 1920, height: 1080 },
    { name: 'Tablet', width: 768, height: 1024 },
    { name: 'Mobile', width: 375, height: 667 },
  ];

  for (const viewport of viewports) {
    console.log(
      `Testing ${viewport.name} (${viewport.width}x${viewport.height})`,
    );

    await page.setViewportSize({
      width: viewport.width,
      height: viewport.height,
    });

    await page.goto(TARGET_URL);
    await page.waitForTimeout(1000);

    await page.screenshot({
      path: `/tmp/${viewport.name.toLowerCase()}.png`,
      fullPage: true,
    });
  }

  console.log('✅ All viewports tested');
  await browser.close();
})();

インライン実行(シンプルなタスク)

クイックワンオフタスクでは、ファイルを作成せずにコードをインラインで実行できます:

# クイックスクリーンショット
cd $SKILL_DIR && node run.js "
const browser = await chromium.launch({ headless: false });
const page = await browser.newPage();
await page.goto('http://localhost:3001');
await page.screenshot({ path: '/tmp/quick-screenshot.png', fullPage: true });
console.log('Screenshot saved');
await browser.close();
"

インライン vs ファイル使用時:

• インライン: クイックワンオフタスク(スクリーンショット、要素の存在確認、ページタイトル取得)
• ファイル: 複雑なテスト、レスポンシブデザインチェック、ユーザーが再実行したいもの

利用可能なヘルパー

lib/helpers.js のオプショナルユーティリティ関数:

const helpers = require('./lib/helpers');

// 実行中の dev サーバーを検出(重要 - これを最初に使用!)
const servers = await helpers.detectDevServers();
console.log('Found servers:', servers);

// 再試行を含むセーフクリック
await helpers.safeClick(page, 'button.submit', { retries: 3 });

// クリアを含むセーフタイプ
await helpers.safeType(page, '#username', 'testuser');

// タイムスタンプ付きスクリーンショット取得
await helpers.takeScreenshot(page, 'test-result');

// Cookie バナーを処理
await helpers.handleCookieBanner(page);

// テーブルデータを抽出
const data = await helpers.extractTableData(page, 'table.results');

完全なリストは lib/helpers.js を参照してください。

カスタム HTTP ヘッダー

環境変数経由ですべての HTTP リクエストにカスタムヘッダーを設定します。以下の用途に便利です:

• 自動化されたトラフィックをバックエンドに識別させる
• LLM 最適化レスポンスを取得する(例: スタイル付き HTML ではなくプレーンテキストエラー)
• グローバルに認証トークンを追加する

設定

単一ヘッダー(一般的なケース):

PW_HEADER_NAME=X-Automated-By PW_HEADER_VALUE=playwright-skill \
  cd $SKILL_DIR && node run.js /tmp/my-script.js

複数ヘッダー(JSON 形式):

PW_EXTRA_HEADERS='{"X-Automated-By":"playwright-skill","X-Debug":"true"}' \
  cd $SKILL_DIR && node run.js /tmp/my-script.js

仕組み

helpers.createContext() を使用するときにヘッダーが自動的に適用されます:

const context = await helpers.createContext(browser);
const page = await context.newPage();
// このページからのすべてのリクエストはカスタムヘッダーを含みます

生の Playwright API を使用するスクリプトでは、注入された getContextOptionsWithHeaders() を使用します:

const context = await browser.newContext(
  getContextOptionsWithHeaders({ viewport: { width: 1920, height: 1080 } }),
);

高度な使用方法

包括的な Playwright API ドキュメントについては、API_REFERENCE.md を参照してください:

• セレクターとロケーターのベストプラクティス
• ネットワーク インターセプション & API モッキング
• 認証とセッション管理
• ビジュアル回帰テスト
• モバイルデバイスエミュレーション
• パフォーマンステスト
• デバッグテクニック
• CI/CD 統合

ヒント

• 重要: サーバーを最初に検出 - localhost テスト用のテストコードを記述する前に、常に detectDevServers() を実行する
• カスタムヘッダー - PW_HEADER_NAME/PW_HEADER_VALUE 環境変数を使用して、自動化されたトラフィックをバックエンドに識別させる
• /tmp を使用してテストファイルを保存 - /tmp/playwright-test-*.js に書き込む、スキルディレクトリやユーザーのプロジェクトには書き込まない
• URL をパラメータ化 - 検出/提供された URL を、すべてのスクリプト上部の TARGET_URL 定数に配置する
• デフォルト: 表示されるブラウザ - ユーザーが明示的に「ヘッドレス」または「バックグラウンド」実行をリクエストしない限り、常に headless: false を使用する
• ヘッドレスモード - ユーザーが明示的に「ヘッドレス」を要求する場合のみ headless: true を使用する
• 遅延: slowMo: 100 を使用してアクションを視認可能にし、フォローしやすくする
• 待機戦略: 固定タイムアウトの代わりに waitForURL、waitForSelector、waitForLoadState を使用する
• エラーハンドリング: ロバストな自動化のために常に try-catch を使用する
• コンソール出力: console.log() を使用して進捗を追跡し、何が起こっているかを表示する

トラブルシューティング

Playwright がインストールされていない:

cd $SKILL_DIR && npm run setup

モジュールが見つからない: run.js ラッパー経由でスキルディレクトリから実行していることを確認してください

ブラウザが開かない: headless: false をチェックし、ディスプレイが利用可能であることを確認してください

要素が見つからない: 待機を追加: await page.waitForSelector('.element', { timeout: 10000 })

使用例

ユーザー: "マーケティングページが見栄え良くテストしてください"

Claude: マーケティングページを複数のビューポートでテストします。まず実行中のサーバーを検出しましょう...
[実行: detectDevServers()]
[出力: ポート 3001 でサーバーが見つかった]
dev サーバーが http://localhost:3001 で実行されているのを見つけました

[URL をパラメータ化した /tmp/playwright-test-marketing.js にカスタム自動化スクリプトを書き込み]
[実行: cd $SKILL_DIR && node run.js /tmp/playwright-test-marketing.js]
[/tmp/ のスクリーンショット付きで結果を表示]

ユーザー: "ログインが正しくリダイレクトされるかチェックしてください"

Claude: ログインフローをテストします。まず実行中のサーバーをチェックしましょう...
[実行: detectDevServers()]
[出力: ポート 3000 と 3001 でサーバーが見つかった]
2 つの dev サーバーが見つかりました。どれをテストしますか?
- http://localhost:3000
- http://localhost:3001

ユーザー: "3001 を使用してください"

[ログイン自動化を /tmp/playwright-test-login.js に書き込み]
[実行: cd $SKILL_DIR && node run.js /tmp/playwright-test-login.js]
[報告: ✅ ログイン成功、/dashboard にリダイレクト]

注釈

• 各自動化は特定のリクエスト用にカスタム作成される
• 事前構築されたスクリプトに限定されない - あらゆるブラウザタスクが可能
• ハードコード化された URL を排除するために実行中の dev サーバーを自動検出
• テストスクリプトは /tmp に書き込まれるため自動クリーンアップ(クラッターなし)
• run.js 経由での適切なモジュール解決でコード実行が確実
• プログレッシブ開示 - API_REFERENCE.md は高度な機能が必要なときだけ読み込まれる