playwright

Playwright ブラウザー自動化

概要

Playwright を使うと、Web テスト、スクリーンショットの撮影、フォーム入力、スクレイピングのためにブラウザーを自動化できます。このスキルでは、グローバルなインストールが不要な自己完結型のスクリプトを作成するために、uv を使った Python を使用します。

前提条件

• Python 3.10+
• uv パッケージマネージャー
• Playwright のブラウザーバイナリー（一度限りのセットアップ）

セットアップ（初回のみ）

Claude：ブラウザーのインストールコマンドを直接実行しないでください。 これらのコマンドをユーザーに提示し、手動で実行してもらってください。ブラウザーバイナリーを約200MBダウンロードする、一度限りのセットアップです。

ユーザーに次のコマンドの実行を促します。

# Install Chromium (recommended, ~200MB)
uv run --with playwright playwright install chromium

# Or install all browsers
uv run --with playwright playwright install

インストールを確認するには：

uv run /path/to/plugins/playwright/scripts/check_setup.py

クイックスタート

任意の URL のスクリーンショットを撮影します。

uv run /path/to/plugins/playwright/scripts/screenshot.py https://example.com

出力：/tmp/screenshot-{timestamp}.png

よく使われるパターン

スクリーンショットを撮影する

# Default (visible browser)
uv run scripts/screenshot.py https://example.com

# Full page, headless
uv run scripts/screenshot.py https://example.com --full-page --headless

# Custom output path
uv run scripts/screenshot.py https://example.com -o /tmp/my-shot.png

ページに移動してコンテンツを抽出する

# Get page title and URL
uv run scripts/navigate.py https://example.com

# Extract all links as JSON
uv run scripts/navigate.py https://example.com --links

# Get page text content
uv run scripts/navigate.py https://example.com --text

フォームに入力して送信する

uv run scripts/fill_form.py https://example.com/login \
  --field "[email protected]" \
  --field "password=secret123" \
  --submit

JavaScript を実行する

uv run scripts/evaluate.py https://example.com "document.title"
uv run scripts/evaluate.py https://example.com "document.querySelectorAll('a').length"

カスタムスクリプトの作成

次のテンプレートを /tmp/my-automation.py に保存します。

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.10"
# dependencies = ["playwright==1.56.0"]
# ///
"""Custom Playwright automation script."""

import os
import sys
from playwright.sync_api import sync_playwright

HEADLESS = os.getenv("HEADLESS", "0").lower() in ("1", "true", "yes")

def main():
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=HEADLESS)
        page = browser.new_page()

        try:
            page.goto("https://example.com")
            print(f"Title: {page.title()}")

            # Use semantic locators (preferred)
            page.get_by_role("button", name="Submit").click()
            page.get_by_label("Email").fill("[email protected]")

            # Screenshot
            page.screenshot(path="/tmp/result.png")

        except Exception as e:
            page.screenshot(path="/tmp/error.png")
            print(f"Error: {e}", file=sys.stderr)
            return 1
        finally:
            browser.close()

    return 0

if __name__ == "__main__":
    sys.exit(main())

次のコマンドで実行します。

uv run /tmp/my-automation.py

最新のロケーター API

CSS セレクターよりも、セマンティックロケーターを優先してください。

# PREFERRED: Semantic locators (accessible, stable)
page.get_by_role("button", name="Submit").click()
page.get_by_label("Email").fill("[email protected]")
page.get_by_placeholder("Search...").fill("query")
page.get_by_text("Welcome back").wait_for()
page.get_by_test_id("submit-btn").click()

# AVOID: Raw CSS selectors (fragile)
page.locator("button.btn-primary").click()  # Don't use

ロケーターを組み合わせる：

# OR: Match either
page.get_by_role("button", name="New").or_(
    page.get_by_text("Create")
).click()

# Filter: Narrow down
page.locator("tr").filter(has_text="Active").first.click()

クイックリファレンス

操作	コード
ページに移動	page.goto("https://url")
クリック	page.get_by_role("button", name="X").click()
入力欄に入力	page.get_by_label("Email").fill("value")
テキストを取得	page.get_by_role("heading").text_content()
スクリーンショット	page.screenshot(path="/tmp/shot.png")
待機	page.get_by_text("Loaded").wait_for()
JS を評価	page.evaluate("document.title")

環境変数

変数	説明	デフォルト
HEADLESS	ヘッドレスモードでブラウザーを実行する	0（ヘッドあり）
SLOW_MO	操作を遅くする（ms）	0
VIEWPORT	ブラウザーのビューポート	1280x720
TRACE	トレースを有効にする	0（オフ）

例：

HEADLESS=1 SLOW_MO=250 uv run scripts/screenshot.py https://example.com

デバッグ用のトレース

複雑な自動化をデバッグするには、トレースを有効にします。

context.tracing.start(screenshots=True, snapshots=True, sources=True)
# ... your automation ...
context.tracing.stop(path="/tmp/trace.zip")

トレースを表示します。

uv run --with playwright playwright show-trace /tmp/trace.zip

トラブルシューティング

「Browser not found」

ユーザーにブラウザーバイナリーのインストールを促します（直接実行しないでください）。

uv run --with playwright playwright install chromium

「Timeout waiting for element」

適切な待機方法を使用します。

# Wait for element to be visible
page.get_by_text("Loaded").wait_for(state="visible")

# Wait for network idle
page.goto(url, wait_until="networkidle")

「Element not interactable」

要素が表示されていることを確認し、スクロールして表示領域に移動します。

element = page.get_by_role("button", name="Submit")
element.scroll_into_view_if_needed()
element.click()

ヘッドレスモードの問題

ヘッドありモードでデバッグします。

HEADLESS=0 uv run scripts/screenshot.py https://example.com

コンテナー／CI の問題

次の Chromium フラグを使用します。

browser = p.chromium.launch(
    headless=True,
    args=["--disable-dev-shm-usage", "--no-sandbox"]
)

高度な使用方法

詳細なドキュメントについては、次を参照してください。

• references/api-reference.md - API リファレンス全体
• references/selectors.md - セレクターパターン
• references/custom-scripts.md - スクリプトテンプレート
• references/troubleshooting.md - よくある問題