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

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

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

Playwright ブラウザ自動化

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

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

1. 開発サーバーの自動検出 - localhost テスト用に、必ず最初にサーバー検出を実行してください:

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

   • 1 つのサーバーが見つかった場合: それを自動的に使用し、ユーザーに通知
   • 複数のサーバーが見つかった場合: ユーザーに使用するサーバーを選択するよう質問
   • サーバーが見つからない場合: URL を入力するようにするか、開発サーバー起動を支援する

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

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

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

動作方法

1. テスト/自動化したい内容を説明
2. 実行中の開発サーバーを自動検出 (または外部サイト テスト用に URL を要求)
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: 開発サーバーを検出 (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();
})();

インライン実行 (簡単なタスク)

クイック 1 回限りのタスク用に、ファイルを作成せずにコードをインラインで実行できます:

# クイックスクリーンショットを取得
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();
"

インラインとファイルの使い分け:

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

利用可能なヘルパー

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

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

// 実行中の開発サーバーを検出 (重要 - 最初にこれを使用してください!)
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()]
[出力: Found server on port 3001]
http://localhost:3001 で開発サーバーが実行されているのが見つかりました

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

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

Claude: ログインフローをテストします。まず実行中のサーバーを確認します...
[実行: detectDevServers()]
[出力: Found servers on ports 3000 and 3001]
2 つの開発サーバーが見つかりました。どちらをテストしますか?
- http://localhost:3000
- http://localhost:3001

ユーザー: "3001 を使って"

[ログイン自動化を /tmp/playwright-test-login.js に作成]
[実行: cd $SKILL_DIR && node run.js /tmp/playwright-test-login.js]
[報告: ✅ Login successful, redirected to /dashboard]

注釈

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

使用時期

このスキルは概要で説明されたワークフローまたはアクションを実行するのに適しています。

制限事項

• このスキルは、上記で説明されたスコープに明確に一致するタスク用にのみ使用してください。
• 出力を環境固有の検証、テスト、または専門家のレビューの代わりとしないでください。
• 必要な入力、権限、セキュリティ境界、または成功基準が不足している場合は、一時停止して説明を求めてください。