Playwright Scraper

````skill --- name: playwright-scraper description: ログイン認証・ページネーション・ダウンロード機能を伴うWebスクレイピング実装に使用。「Playwrightでサイト○○からデータを取得したい」「ログインしてZIPをダウンロードしたい」という依頼で起動。ロケーター判定 → スクレイピングロジック実装 → ダウンロード・待機処理の統合で進める。 ---

Playwright Scraper

概要

Playwrightを使った動的Webスクレイピング実装ガイド。 ログイン認証・ページネーション・ZIPダウンロードなど複数ステップの自動化を、Locator中心で実装する。

Locatorは要素操作時に自動待機・自動リトライを行うため、query_selector / wait_for_selector による手動待機より堅牢。

作業手順

Step 1: ロケーター判定

ユーザーが提供したページソース（HTML）から適切なロケーターを決定する。

• ページソースをファイルで受け取り（または URL を直接検査）
• 優先順位: セマンティックロケーター > CSSセレクタ > XPath

1. page.get_by_role() – ロール + アクセシブル名（最優先）
2. page.get_by_label() – フォームラベル
3. page.get_by_placeholder() – プレースホルダー
4. page.get_by_text() – 表示テキスト
5. page.locator("css=...") – CSS（HTMLが変わりやすい場合の最終手段）

• JSON形式でロケーターマップを出力（ユーザーが確認/修正可能）

使用ツール: scripts/selector_detector.py で自動判定

# 出力例: selectors.json
{
  "login_form": {
    "email_input": "get_by_label('メールアドレス')",
    "password_input": "get_by_label('パスワード')",
    "login_button": "get_by_role('button', name='ログイン')"
  },
  "download_link": "get_by_role('link', name='ダウンロード')"
}

Step 2: スクレイピングロジック実装

認証・ページネーション・ダウンロード処理を組み立て。

ログイン処理:

• ブラウザを起動（Chromium推奨）
• Locator経由でフォーム入力 → ログインボタンクリック（Locatorが自動待機）
• ページロード完了を待機（page.wait_for_load_state() 利用）

# ✅ Locatorベースのログイン例
page.get_by_label("メールアドレス").fill(email)
page.get_by_label("パスワード").fill(password)
page.get_by_role("button", name="ログイン").click()
page.wait_for_load_state("networkidle")

ページネーション:

• page.locator() で次ページリンクを Locator として取得
• locator.is_visible() / locator.count() で存在確認
• クリックは Locator 経由（自動待機込み）

# ✅ Locatorベースのページネーション例
next_btn = page.get_by_role("link", name="次へ")
while next_btn.is_visible():
    next_btn.click()
    page.wait_for_load_state("networkidle")

ダウンロード:

• page.expect_download() コンテキストマネージャーを使用（イベント購読管理が明確）
• Locator 経由でリンク・ボタンをクリック（withブロック内）
• ダウンロード完了を確実に待機（download.path() がブロック）

# ✅ expect_download()コンテキストマネージャーを使用（推奨）
with page.expect_download() as download_info:
    page.get_by_role("link", name="ダウンロード").click()  # Locator使用
download = download_info.value
file_path = Path(download.path())  # ダウンロード完了まで自動ブロック

Step 3: エラーハンドリング・ロギング統合

タイムアウト / Locator見つからず / ダウンロード失敗 時の対応。

• 具体的な例外で捕捉（playwright.sync_api.TimeoutError など）
• 構造化ログで追跡（logger.debug() / logger.error() with exc_info）
• リトライ機構は必要に応じて（最大3回程度）
• Locatorは自動リトライするため、固定待機 (time.sleep) は不要

実装例

入力:

target_url: "https://example.com/login"
selectors_file: "config/selectors.json"  # Step 1 の出力
credentials:
  email: "${EMAIL}"          # 環境変数参照
  password: "${PASSWORD}"
download_dir: "./downloads"
page_limit: 5                     # ページネーション上限

期待する出力:

• ${download_dir}/data_*.zip ダウンロード成功
• scrape_log.json 構造化ログ（取得項目数・エラー・実行時間）
• Locator見つからず時は詳細メッセージ（HTML スナップショット相対パス等）

使用する同梱リソース

• [scripts/selector_detector.py](scripts/selector_detector.py): ページソースからロケーター候補を自動抽出
• [scripts/basic_scraper.py](scripts/basic_scraper.py): ログイン・ページネーション・ダウンロードの実装例
• [references/docs_links.md](references/docs_links.md): 公式ドキュメント・API リファレンス
• [references/best_practices.md](references/best_practices.md): ログイン待機・タイムアウト・リトライの実装パターン

ダウンロード完了待機のパターン比較

Playwrightでファイルダウンロードを実装する際、完了待機の方法は3つのパターンがあります：

パターンA: page.expect_download() コンテキストマネージャー（推奨 ⭐）

# ✅ イベント購読の寿命管理が明確（withブロック内で完結）
with page.expect_download() as download_info:
    page.get_by_role("link", name="ダウンロード").click()
download = download_info.value
file_path = Path(download.path())  # ダウンロード完了までブロック
target_path = self.download_dir / download.suggested_filename
shutil.copy2(file_path, target_path)

メリット:

• イベント購読が明確 - withブロック内で管理
• 最新のPlaywright推奨パターン
• ダウンロード完了を確実に待機
• ファイルが確実に書き込まれたことを保証
• basic_scraper.py で採用

パターンB: page.on() + download.path()（非推奨）

# ❌ イベント購読の寿命管理が暗黙的
def handle_download(download):
    file_path = Path(download.path())
    target_path = self.download_dir / download.suggested_filename
    shutil.copy2(file_path, target_path)

page.on("download", handle_download)
page.get_by_role("link", name="ダウンロード").click()

問題点:

• イベントハンドラの購読終了管理が曖昧
• 複数ダウンロード時に順序や完了保証が不明確

パターンC: page.wait_for_load_state() のみ（非推奨）

# ❌ ダウンロード完了を明示的に待機しない
page.on("download", handle_download)
page.get_by_role("link", name="ダウンロード").click()
page.wait_for_load_state("networkidle")  # リスク: race condition

問題点:

• ダウンロード完了を保証しない（ネットワークイベント終了と異なる）
• ファイルが部分的に書き込まれる可能性

推奨: パターンA (page.expect_download() コンテキストマネージャー）を使用してください。

Locator 優先の理由

| 比較項目 | query_selector | Locator | |---|---|---| | 要素待機 | 手動（wait_for_selector 必要） | 自動（操作時に自動待機） | | Stale Element | 再取得が必要 | 自動リトライで回避 | | 複数セレクタ試行 | ループで個別実装 | locator.or_() で宣言的に記述 | | アクセシビリティ | CSSのみ | ロール/ラベルで意味ベース検索可 | | 公式推奨 | 非推奨（旧API） | 推奨（Current API） |

参考URL

• Locators（主要）: https://playwright.dev/python/docs/locators
• Page API: https://playwright.dev/python/docs/api/class-page
• Locator API: https://playwright.dev/python/docs/api/class-locator
• Error クラス: https://playwright.dev/python/docs/api/class-error
• Best Practices: https://playwright.dev/python/docs/best-practices

チェックリスト

実装完了時に以下を確認:

• [ ] query_selector / wait_for_selector を使わず Locator を使用している
• [ ] セマンティックロケーター（get_by_role, get_by_label 等）を優先している
• [ ] ログイン後のページロード完了を明示的に待機している
• [ ] ダウンロード時に page.expect_download() コンテキストマネージャーでダウンロードを待機している
• [ ] 認証情報を環境変数で管理している（ハードコード禁止）
• [ ] タイムアウト時に具体的なエラーメッセージを出力している
• [ ] 構造化ログ（JSON or 標準format）で実行過程を記録している
• [ ] make check-all で Python syntax / lint / typecheck に合格している

````

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [studiogadget](https://github.com/studiogadget)
- **Source:** [studiogadget/skills](https://github.com/studiogadget/skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.