Patchright Automation に CAPTCHA ソルバーを追加する方法

要約

• Patchright は Chromium ブラウザを操作しますが、回答が必要な CAPTCHA には別途「解答ステップ」が必要です。
• reCAPTCHA の検出はページ本体の JavaScript 環境の状態に依存する場合がありますが、Patchright は既定で隔離された環境でスクリプトを評価します。
• 小さなページアダプタを使うことで、公式の CapSolver Core SDK に同じ Patchright ページを第 2 のブラウザを開かずに参照させられます。
• まずローカルのテストウィジェットから始め、課金される解答とアプリケーション側の応答を個別に検証してから、大きなワークフローに統合してください。

Patchright のスクリプトは、正しくナビゲーションしてフォームを見つけても、reCAPTCHA ウィジェットで止まることがあります。ブラウザライブラリを切り替えても、ウィジェットやアプリケーションが要求する回答は自動では得られません。その時点で CAPTCHA ソルバーが必要であり、さらにアプリケーションがその結果を受け入れたかどうかの確認も必要です。

この Patchright CAPTCHA ソルバーのチュートリアルでは、Python のブラウザセッションを公式の Core SDK を通して CapSolver に接続します。重要なポイントはページの JavaScript 環境です。見えている DOM を読むことと、reCAPTCHA の「ページ所有の設定」を読むことは別の操作です。以下の例ではその違いを扱い、ページを 1 つだけ開いたまま、ローカルの開発用フィクスチャで検出を確認します。自分が所有している、または自動化の許可があるページに対してのみ、この方法を使ってください。

Patchright とは何か、CAPTCHA ソルバーが役立つ場面

Patchright は、Playwright とよく似た Python 自動化インターフェースを持つ、コミュニティ主導の派生プロジェクトです。公式の Python リポジトリに、Chromium のサポートと、Playwright の代替インポートとしての使い方が記載されています。Firefox と WebKit は Patchright ではサポートされていません。

開発者は Patchright を使ってページを操作し、要素と対話し、ブラウザのワークフローを構築します。サポートされている CAPTCHA が、正当なワークフローのフォーム送信や期待する結果への到達を妨げている場合に、ソルバーが意味を持ちます。すでにページへ通常どおりアクセスできているのであれば、有料の解答リクエストを送る理由はありません。

この連携には 3 つの責務があります。Patchright はナビゲーションとページのライフサイクルを担当します。ソルバーは対応するチャレンジ入力を読み取り、解答をリクエストします。あなたのアプリケーションのワークフローは、フォームや遷移先のページが本当に成功したかどうかを判断します。CAPTCHA 用語集には、この分離の裏にある検証メカニズムが説明されています。

自分のアプリケーションの定常的なテストには、CAPTCHA ベンダーの開発用設定を優先してください。有料ソルバーとの連携確認は、通常のフォームバリデーションが機能しているかをテストする作業とは別物です。

reCAPTCHA 検出に正しいページコンテキストが必要な理由

reCAPTCHA の検出では、ウィジェットがページ本体の JavaScript 環境の中に作成した設定が必要になることがあります。Patchright の evaluate() に関するドキュメントでは、isolated_context オプションは既定で True です。そのため、ウィジェットが表示されていても、通常の評価ではページ所有の JavaScript グローバルが見えない場合があります。

本ガイドで用いる制御された例では、既定の評価からは window.___grecaptcha_cfg が見えず、isolated_context=False で評価した場合には見える、という状況になりました。この reCAPTCHA パスでは、SDK がそのページ状態にアクセスできる必要があります。タイムアウトや空の検出結果が返ってきた場合、サイトキーを変えたり、解答リクエストを繰り返す前に、コンテキストを必ず確認してください。

以下のアダプタは、SDK による評価をページ本体の JavaScript 環境へ転送します。Patchright のインストール済みファイルを書き換えたり、すべてのブラウザ操作で環境を切り替えたりはしません。ナビゲーションや通常のロケータは raw_page のまま使い、SDK に渡すページオブジェクトだけがこのラッパーを使います。ここでは、後述のバージョン向けに検証済みの連携例として扱ってください。公式な Patchright との提携や、すべての環境での互換性を主張するものではありません。

パッケージをインストールして前提条件を確認する

この例では、Python 3.12、Patchright 1.64.1、capsolver-core 0.1.1 を使用します。パッケージは隔離された環境にインストールし、Patchright の Chromium ランタイムもインストールしてください。セットアップ確認ではバージョンを固定し、パッケージのアップグレードによって挙動が密かに変わらないようにします。

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "patchright==1.64.1" "capsolver-core==0.1.1"
python -m patchright install chromium

検出の例では CapSolver の API キーは必要ありません。実際の解答には、あなた自身の有効なキーと十分なアカウント残高が必要です。クライアントは create_capsolver(api_key=...) オプションで設定し、キーはアプリケーションのシークレット設定に保持してください。Core SDK ガイドには、クライアントの作成、検出、解答、および結果フィールドが記載されています。

以下のセットアップ確認は、Google の公開 reCAPTCHA テストキーを使ったローカルページに対して実行されました。有料解答・トークンの書き戻し・解答済みトークンをアプリケーションが受け入れるかの確認は、このガイドでは行っていません。このフィクスチャを本番の成功率テストとして使わないでください。

ローカルで Patchright と SDK のセットアップ確認を実行する

セットアップ確認では 1 つのローカルフィクスチャを開き、テストウィジェットの初期化を待ち、公式 SDK が返す CAPTCHA パラメータを出力します。これを patchright_sdk_check.py として保存し、上記の環境で Python から実行してください。

ローカル URL はブラウザルート経由で配信されるため、別途 Web サーバーを立ち上げる必要はありません。ウィジェットスクリプトは依然として Google から読み込まれるため、ネットワークアクセスは必要です。公開サイトキーは Google の reCAPTCHA テストガイダンスから取得したもので、開発用キーであり、秘密情報ではありません。

import asyncio
import json

from capsolver_core import create_capsolver
from patchright.async_api import async_playwright

TEST_URL = "http://127.0.0.1:8765/"
HTML = """<!doctype html><html><head><title>CAPTCHA integration check</title></head>
<body><h1>Owned development page</h1>
<div class="g-recaptcha" data-sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"></div>
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
</body></html>"""


class MainWorldPage:
    def __init__(self, page):
        self._page = page

    @property
    def url(self):
        return self._page.url

    async def evaluate(self, expression, arg=None):
        return await self._page.evaluate(expression, arg, isolated_context=False)

    async def wait_for_selector(self, selector, **kwargs):
        return await self._page.wait_for_selector(selector, **kwargs)


async def main():
    async with async_playwright() as p:
        browser = await p.chromium.launch(headless=True)
        try:
            raw_page = await browser.new_page()
            await raw_page.route(
                TEST_URL, lambda route: route.fulfill(content_type="text/html", body=HTML)
            )
            await raw_page.goto(TEST_URL)
            page = MainWorldPage(raw_page)
            for _ in range(60):
                ready = await page.evaluate(
                    "() => !!window.___grecaptcha_cfg && "
                    "Object.keys(window.___grecaptcha_cfg.clients || {}).length > 0"
                )
                if ready:
                    break
                await asyncio.sleep(0.5)
            else:
                raise RuntimeError("Test widget did not initialize")

            async with create_capsolver() as cap:
                infos = await cap.get_captcha_info(page)
                result = [{"type": info.type.value, "url": info.website_url,
                           "site_key": info.website_key} for info in infos]
                print(json.dumps({"captcha_parameters": result}))
                assert result and result[0]["type"] == "reCaptchaV2"
        finally:
            await browser.close()


if __name__ == "__main__":
    asyncio.run(main())

正常に実行されると、type が reCaptchaV2 の項目が 1 つ、ローカルページの URL、公開テストサイトキーが返ってきます。これは Patchright がページを開き、SDK がアダプタ経由で初期化済みウィジェットを読み取れたことを示します。ただし、解答済みトークンは含まれておらず、本番フォームがトークンを受け入れるかどうかの証明にもなりません。

ウィジェットの読み込みや検出が失敗した場合も含め、finally の中でブラウザは閉じられます。SDK クライアントも非同期コンテキストを抜けます。統合を長いスクリプトに組み込む際にも、このクリーンアップ処理は残しておいてください。特にチャレンジが例外を引き起こすようなケースでは重要です。

CapSolver ボーナスコードを利用する

自動化予算を即座に底上げしましょう！
CapSolver アカウントへのチャージ時にボーナスコード CAP26 を使うと、チャージごとに 5% のボーナス が無制限で付与されます。
今すぐ CapSolver ダッシュボード で引き換えてください。

検出確認の後に解答処理を追加する

解答処理は、ブラウザと SDK のアクティブなコンテキスト内、ページを閉じたりナビゲーションしたりする前に行う必要があります。権限のあるアプリケーションページ上で、上記のとおりにラップした現在の Patchright ページを使い、API キー付きで SDK クライアントを生成し、公式のブラウザモード呼び出しを使います。

次の行は変更していない公式 SDK 呼び出しです。有効な API キーが必須であり、この Patchright アダプタと組み合わせた有料実行については本ガイドではテストしていません。cap とラップ済み page がスコープ内にある間に置き、単体スクリプトとして走らせないでください。

results = await cap.solve_on_page(page)

続行する前に、返された項目を確認してください。SDK は error、solution、filled を公開しており、失敗した試行、返却された解答、トークンの書き戻しを区別できます。必要な解答が欠けている、または該当する結果でエラーが報告されている場合は、フォームを送信しないでください。

reCAPTCHA v2 では、公式タスクパラメータがページ URL、サイトキー、タスクタイプの関係を説明しています。検出されたチャレンジが想定したページのものか確認してください。別環境からコピーしたキーや古いページ状態から得たキーは、形式が正しくても有用な入力にはなりません。

アプリケーション結果を確認してから先に進む

アプリケーションの成功確認は、解答と書き戻しの後に行う別のチェックです。ワークフロー上、フォーム送信やページ固有のコールバック待機が必要な場合もあります。Google の サーバー側検証ガイドでは、アプリケーションがレスポンスを検証しなければならない理由が説明されています。自分のアプリケーションにおける成功シグナル（確認メッセージや期待する結果セクションなど）を定義し、そのシグナルが現れない場合は処理を中断しましょう。

HTTP レスポンスやトークン文字列、filled=True を、ブラウザタスク全体の成功の証拠として扱うことは避けてください。ページがレスポンスを拒否した場合には、役立つエラー要約を残し、再試行前に原因を調査しましょう。CAPTCHA トークンと Cookie のガイドには、ソルバーの出力を解釈する際の背景情報が載っています。

検出結果が空、または後続処理が失敗した場合のトラブルシュート

トラブルシュートは、失敗した最初のステップから始めてください。ページ読み込み、ウィジェット初期化、コンテキストアクセス、解答、アプリケーション側の受け入れ、のどこで止まっているかを切り分けます。

最初は 1 ページ・1 回の試行から始めてください。どの失敗が一時的なものかを理解してから、回数に上限を設けた再試行を追加します。ナビゲーション後に以前の結果を使い回すと、解答が誤ったページ状態と結び付くおそれがありますし、原因を特定しないまま闇雲に再試行すると、元の問題を解決しないままコストだけ増やしてしまいます。

Patchright と SDK のバージョンを上げる前には、必ず両者の組み合わせをテストしてください。API が見慣れているというだけでは、すべての Playwright 拡張や SDK に対して同一の挙動が保証されるわけではありません。ここで紹介した小さな検出チェックを互換性テストとして残し、自分の環境では別途、認証付きの解答とアプリケーション確認を行ったうえで本番運用に移行してください。

アプリケーションチェックまで含めて統合を完了する

有用な Patchright 連携とは、「現在のブラウザページ」「対応する CAPTCHA タスク」「観測可能なアプリケーション結果」を結び付けるものです。まずページコンテキストへのアクセスを確認し、自分の認証情報で有料解答を検証し、最後に意図したブラウザ操作が完了したことを確かめてください。これにより、CapSolver は CAPTCHA ステップに集中でき、すべてのナビゲーション問題を解決できるかのように扱うことを避けられます。

CapSolver で信頼性の高い自動化ワークフローを構築する

権限のある Patchright ワークフローで、対応する CAPTCHA レスポンスが必要になったときには、CapSolver を試してください。実際にチャレンジが発生した場合のみ解答処理を行い、その結果を検証してからワークロードを拡大しましょう。

よくある質問（FAQ）

Q: Patchright 自体は reCAPTCHA を解いてくれますか？

いいえ。ブラウザの制御だけでは reCAPTCHA の解答トークンは得られません。権限のあるページで CAPTCHA レスポンスが依然として求められる場合は、対応ソルバーのステップを追加するか、アプリケーションの開発用テスト設定を利用してください。

Q: ウィジェットが表示されているのに検出結果が空になるのはなぜですか？

スクリプトが、ウィジェットが設定を初期化したものとは別の JavaScript 環境を読んでいる可能性があります。サイトキーが不足していると決めつける前に、初期化状況とメイン環境へのアクセスを確認してください。

Q: これは公式の Patchright 連携ですか？

いいえ。これは公式の Patchright パッケージと CapSolver SDK を用いた連携例です。カスタムアダプタと検出スクリプトは記載のバージョンで実行しましたが、有料解答はテストしていません。

Q: ローカルのセットアップ確認に API キーは必要ですか？

いいえ。セットアップ確認では公開されている開発用ウィジェットのパラメータを読み取るだけです。解答用呼び出しには、別途有効な API キーとアカウント残高が必要です。

Q: この例を Firefox や WebKit でも使えますか？
いいえ。Patchright ドキュメントは Chromium ベースのブラウザをサポートしています。以下の例では、Chromium ランタイムを起動します。

Q: トークンの再入力（fill-back）は、そのフォームが検証に合格したことを意味しますか？

いいえ。トークンの再入力と申請の受理は別の結果です。ワークフローを続行する前に、必要な操作を行ったあとのアプリケーションのレスポンスを必ず確認してください。