web-automation

ABOUTME: Playwright を使用したウェブ自動化、デバッグ、E2E テスト用の Claude Code スキル

ABOUTME: インタラクティブな自動化、受動的な監視、スクリーンショット、セキュリティ検証を扱います

Playwright によるウェブ自動化

Playwright を使用して、Python または JavaScript/TypeScript でブラウザーを自動化し、デバッグします。

詳細なパターン：references/python-patterns.md と references/javascript-patterns.md を参照してください。

---

クイックリファレンス

タスク	ヘルパースクリプト
ログイン／フォーム入力	examples/python/form_interaction.py
スクリーンショットの撮影	examples/python/screenshot_capture.py
Cookie の同意を処理	scripts/cookie_consent.py
ページ要素の検出	examples/python/element_discovery.py
ネットワークトラフィックの取得	scripts/network_inspector.py
コンソールエラーのデバッグ	scripts/console_debugger.py
全体のデバッグ（ネットワーク＋コンソール）	scripts/combined_debugger.py
ウェブサイトの見た目を比較	examples/python/visual_compare.py

必ず最初にヘルパーを実行してください：

uv run ~/.claude/skills/web-automation/examples/python/element_discovery.py http://localhost:3000
uv run ~/.claude/skills/web-automation/examples/python/screenshot_capture.py http://localhost:3000 --output /tmp/shots

---

動作モード

モード	使用する場面	例
インタラクティブ	クリック、入力、移動	ログインフロー、フォーム送信
受動的	観察のみ	ネットワークの取得、コンソールの監視
E2E テスト	自動テストスイート	Playwright Test フレームワーク

---

呼び出すタイミング（積極的に実行）

1. UI の修正確認 - フロントエンドのコードを変更した後
2. フォームフィールド／ドロップダウンのテスト - 正しい値が表示されることを確認
3. 見た目の変更確認 - スクリーンショットを撮影
4. バグの再現 - 再現手順を自動化
5. セキュリティ検証 - Gemini／静的解析で問題が見つかった後

---

🔄 再開セッションのチェックポイント

┌─────────────────────────────────────────────────────────────┐
│  SESSION RESUMED - WEB AUTOMATION VERIFICATION              │
│                                                             │
│  1. Was I in the middle of browser automation?              │
│     → Run: ps aux | grep -E "chromium|playwright|node"      │
│                                                             │
│  2. Were there UI verification tasks pending?               │
│     → Check summary for "verify", "test UI", "screenshot"   │
│                                                             │
│  3. Did previous automation capture any findings?           │
│     → Check /tmp/ for screenshots, debug outputs            │
└─────────────────────────────────────────────────────────────┘

---

判断フロー

Task:
    +-- Need to interact? (click, type, submit) → Interactive mode
    +-- Just observe/capture? → Passive mode (combined_debugger.py)
    +-- Security verification? → Passive mode + grep for sensitive patterns

---

重要：オーバーレイの処理

オーバーレイは自動化を妨げます。 page.goto() の後は必ず閉じてください。

Python（簡易パターン）

page.goto('https://example.com')
page.wait_for_load_state('networkidle')

# Dismiss cookie consent
for sel in ['button:has-text("Accept all")', '[class*="cookie"] button[class*="accept"]']:
    try:
        btn = page.locator(sel).first
        if btn.is_visible(timeout=2000):
            btn.click()
            break
    except:
        continue

最終手段（すべてのオーバーレイを削除）

page.evaluate('''() => {
    const patterns = ['cookie', 'consent', 'modal', 'overlay', 'popup', 'backdrop'];
    for (const p of patterns) {
        document.querySelectorAll(`[class*="${p}"], [id*="${p}"]`).forEach(el => {
            if (getComputedStyle(el).position === 'fixed') el.remove();
        });
    }
    document.body.style.overflow = 'auto';
}''')

完全な実装：references/python-patterns.md を参照してください。

---

基本パターン

Python

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()
    page.goto('http://localhost:3000')
    page.wait_for_load_state('networkidle')  # CRITICAL
    # ... automation
    browser.close()

JavaScript

import { test, expect } from '@playwright/test';

test('example', async ({ page }) => {
  await page.goto('/');
  await page.waitForLoadState('networkidle');
  await expect(page.locator('.element')).toBeVisible();
});

---

一般的な操作

操作	Python	JavaScript
スクリーンショット	page.screenshot(path='/tmp/s.png')	await page.screenshot({ path: '/tmp/s.png' })
ページ全体	page.screenshot(path='/tmp/s.png', full_page=True)	await page.screenshot({ path: '/tmp/s.png', fullPage: true })
入力欄への入力	page.fill('input[name="email"]', '[email protected]')	await page.fill('input[name="email"]', '[email protected]')
ドロップダウンの選択	page.select_option('select#id', 'value')	await page.selectOption('select#id', 'value')
クリック	page.click('button[type="submit"]')	await page.click('button[type="submit"]')
ネットワークの待機	page.wait_for_load_state('networkidle')	await page.waitForLoadState('networkidle')
要素の待機	page.wait_for_selector('.result')	await page.waitForSelector('.result')

---

セレクター戦略（優先順位順）

1. ロールベース：page.get_by_role('button', name='Submit')
2. テキストベース：page.get_by_text('Click me')
3. テスト ID：page.get_by_test_id('submit-btn')
4. CSS：page.locator('.btn-primary')
5. XPath（最終手段）：page.locator('//button[@type="submit"]')

---

検証チェックリスト

検証項目	方法
ドロップダウンの値	page.locator('select').input_value()
入力テキスト	page.locator('input').input_value()
要素の表示状態	page.locator('.element').is_visible()
テキストコンテンツ	page.locator('.element').text_content()
ページ URL	操作後の page.url

---

パッシブデバッグスクリプト

スクリプト	目的	例
combined_debugger.py	ネットワーク + コンソール + エラー	uv run ... --duration 30 --output /tmp/debug.json
network_inspector.py	ネットワークのみ	uv run ... --errors-only
console_debugger.py	コンソール／エラーのみ	uv run ... --with-stack-traces

セキュリティ検証

# After Gemini found sensitive data logging
uv run ~/.claude/skills/web-automation/scripts/console_debugger.py \
    http://localhost:3000 --duration 60 --output /tmp/security.json

grep -i "password\|token\|secret\|bearer" /tmp/security.json

---

ビジュアル比較

**「視覚的にブラウズできません」と決して言わないでください。**代わりに：

# Compare two sites
uv run ~/.claude/skills/web-automation/examples/python/visual_compare.py \
    https://reference-site.com \
    http://localhost:3000 \
    --output /tmp/compare

# Then read the screenshots using Read tool

---

言語の選択

ユースケース	推奨	理由
既存の JS/TS プロジェクト	JavaScript	ツールの一貫性
既存の Python プロジェクト	Python	ツールの一貫性
簡易スクリプト	Python	uv run によるセットアップがより簡単
テストスイート	JavaScript	より優れた @playwright/test フレームワーク

---

テストフレームワークとの統合

references/test-framework.md を参照してください：

• 統合テストランナー（test_utils.py）
• サーバーの自動検出と起動
• フレームワークの検出（Playwright、Jest、pytest など）

# Detect and run tests with server
uv run ~/.claude/skills/web-automation/scripts/test_utils.py . --run --with-server

---

よくある落とし穴

落とし穴	解決策
オーバーレイによってクリックが妨げられる	ページを読み込むたびに必ずオーバーレイを閉じる
JS の読み込み前に DOM を検査する	まず必ず wait_for_load_state('networkidle') を使用する
CI でブラウザーをヘッドフルモードにする	必ず headless: true を使用する
不安定なセレクター	CSS クラスよりロール／テキストセレクターを優先する
競合状態	wait_for_timeout ではなく、明示的な待機を使用する

---

前提条件

Python

スクリプトにはインライン依存関係（PEP 723）が含まれており、uv run が自動的にインストールします。

JavaScript

npm init -y
npm install -D @playwright/test
npx playwright install chromium

---

E2E テストの実行

JavaScript

npx playwright test                    # Run all
npx playwright test --ui               # UI mode
npx playwright test --headed           # See browser

Python

pip install pytest-playwright
pytest tests/