Robot FrameworkのブラウザテストでCAPTCHAを検出する方法

要約

• Robot Framework から、公式の CapSolver Core SDK を使う小さな Python キーワードライブラリを呼び出して、CAPTCHA ページを検査できる。
• サンプルでは、検出された CAPTCHA の種類、ページ URL、sitekey を Robot のテストに返す。
• Google の公開 reCAPTCHA テストキーを使った、自前の開発用ページに対してテストを実行する。
• このキーワードは自身でブラウザを開閉し、SeleniumLibrary や Browser Library のセッションには接続しない。
• 検出は入力要素の特定ステップを確認するものであり、CAPTCHA を解くことも、本番フォームがソルバー結果を受け入れることを証明することもしない。

Robot Framework のブラウザテストは、次のアサーションが期待するコンテンツではなく CAPTCHA が表示されるようになった場合に失敗しうる。単にタイムアウトを長くしても、その変化の理由は説明できない。特定の CAPTCHA チェックを行えば、有用な結果――承認されたソルバーワークフローに必要なチャレンジの種類とパラメータ――をテストに渡せる。

Robot Framework は、受け入れテストおよびロボティック・プロセス・オートメーションのためのオープンソースフレームワークである。キーワード構文でテストチームがチェック内容を表現し、Python ライブラリが実際の処理を実装する。このチュートリアルでは、Python キーワードを CapSolver 公式 Core SDK に接続し、Robot がブラウザページから得た実際の検出結果を受け取れることを確認する。

Robot テストにおける CAPTCHA 検出の位置付け

CAPTCHA 検出は、テストがブロックされたページを通常のアプリケーション応答として扱う前に、把握できているページチェックポイントで行う。

たとえば、許可されたブラウザワークフローでは検索フォームが表示されるはずなのに、代わりにチャレンジページに到達した場合を考える。まず有用なのは、サポート対象の CAPTCHA が存在するかどうかだ。その認識結果をもとに、次のステップを制御できる：ドキュメント化されたソルビング連携を使う、人による操作を待つ、あるいは特定のテスト失敗として記録するなど。

これは、すべての「見つからない要素」を CAPTCHA とみなすアプローチとは異なる。ページの失敗は、アプリケーションスクリプトのロード失敗、ルーティングの変更、セレクタの誤り、といった理由でも発生しうる。そうした診断と CAPTCHA 検出は分けておくこと。

Robot Framework ユーザーガイドでは、Python テストライブラリとキーワード実行について説明している。以下の小さなライブラリは、その拡張ポイントを利用している。これは統合例であり、Robot Framework に CapSolver のネイティブライブラリが同梱されている、という主張ではない。

パッケージを 1 つの環境にインストールする

Robot Framework、Playwright、Core SDK を同じ Python 環境にインストールし、テストランナーがいずれもインポートできるようにする。

この例では Python 3.12、Robot Framework 7.5、Playwright 1.64.0、capsolver-core 0.1.1 を使用する。フレームワークのプロジェクト背景やサポートされるインストール方法は、公式リポジトリを参照すること。

python -m pip install robotframework==7.5 playwright==1.64.0 capsolver-core==0.1.1
python -m playwright install chromium

インストールとテスト実行は同じインタプリタで行う。よくあるセットアップの失敗は、ある環境にブラウザライブラリをインストールし、別の環境から Robot を実行してしまうことだ。その場合、ページが開かれる前にインポートが失敗する。

この例はウィジェットを検出し、その公開パラメータを読み取るだけだ。有料ソルビングには有効なソルバー API キー、アカウントの準備、および別途承認されたワークフローが必要になる。以下のテストは有料結果を一切生成しない。

自前の CAPTCHA フィクスチャを作成する

専用のフィクスチャ用ディレクトリに index.html を作成し、自分のマシン上で配信する。

Google は、自動テストに関するガイダンスの中で公開 reCAPTCHA v2 テストキーを文書化している。このフィクスチャでは、そのキーを使って本番サイトの設定を使わずに認識可能なウィジェットを読み込む。

<!doctype html><html><head><title>Owned CAPTCHA test fixture</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>

そのディレクトリでローカルサーバーを起動する:

python -m http.server 8766 --bind 127.0.0.1

ウィジェットスクリプトは、依然として Google へのネットワークアクセスを必要とする。フィクスチャのウィジェットが読み込まれない場合は、空の検出結果を解釈する前にその前提条件を確認すること。ローカルサーバーはフィクスチャをループバックインターフェース上にのみ公開する。

テストキーは、配線や認識の確認には有用だが、本番チャレンジの難易度、有料ソルビングの性能、アプリケーションの受け入れについて代表性のある証拠にはならない。こうした検証はリリースチェックリストの中で別テストとして扱うこと。

Python キーワードライブラリを追加する

次のライブラリを CaptchaCheck.py として、Robot テストファイルと同じ場所に保存する。

このライブラリは、Core SDK に記載されている get_captcha_info メソッドを呼び出す。Robot 向けのラッパーは意図的に小さくしてあり、イベントループを開始し、ブラウザを開き、情報を読み取り、finally ブロックでブラウザを閉じるだけのものになっている。

import asyncio
from robot.api.deco import keyword
from capsolver_core import create_capsolver
from playwright.async_api import async_playwright

@keyword("Inspect CAPTCHA Page")
def inspect_captcha_page(url):
    return asyncio.run(_inspect(url))

async def _inspect(url):
    async with async_playwright() as pw:
        browser = await pw.chromium.launch(headless=True)
        try:
            page = await browser.new_page()
            await page.goto(url, wait_until="networkidle")
            async with create_capsolver() as cap:
                infos = await cap.get_captcha_info(page)
            return [{"type": item.type.value, "url": item.website_url,
                     "site_key": item.website_key} for item in infos]
        finally:
            await browser.close()

戻り値のリストには単純な辞書が入っており、Robot のアサーションで扱いやすい。空リストは、この検査では一致する情報が返されなかったことを意味するだけであり、「ワークフロー上のどこにもチャレンジが存在しない」という主張に変換すべきではない。

ページロード待機は、この小さなフィクスチャに対しては妥当だが、永続的なネットワークアクティビティを伴う本番アプリケーションでは、別のページ固有の準備条件が必要になる場合がある。networkidle をあらゆるアプリケーションにコピーして、「該当ウィジェットのレンダリング完了を証明する条件」とみなさないこと。

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

自動化予算を今すぐ増強しよう！
チャージ時にボーナスコード CAP26 を使うと、チャージ金額に対して 5% 追加ボーナス を無制限で受け取れます。
今すぐ CapSolver ダッシュボード で引き換えてください。

Robot テストを実行して結果を確認する

次を captcha.robot としてライブラリと同じ場所に保存し、ローカルフィクスチャサーバーが利用可能な状態で実行する。

*** Settings ***
Library    CaptchaCheck.py
Library    Collections

*** Variables ***
${PAGE_URL}    http://127.0.0.1:8766/

*** Test Cases ***
Identify The Fixture CAPTCHA
    ${items}=    Inspect CAPTCHA Page    ${PAGE_URL}
    Should Not Be Empty    ${items}
    ${first}=    Get From List    ${items}    0
    Should Be Equal    ${first}[type]    reCaptchaV2
    Log    ${items}

python -m robot --outputdir results captcha.robot

このテストは、検出器が結果を返すことと、そのフィクスチャが reCaptchaV2 として識別されることをアサートする。ログには返却されたページ URL と公開 sitekey が記録される。Robot が生成するレポートで、これらのアサーションがパスしたかどうかを確認できる。

パスした場合、次の具体的な連鎖が成り立ったことを示す：Robot が Python キーワードを呼び出し、Playwright がフィクスチャを開き、Core SDK が実ページを検査し、返却されたデータが Robot のアサーションまで届いた、という流れだ。コードは例外が発生してもブラウザを確実に閉じる。

失敗は発生した段階で読み解くこと。インポートエラーは依存関係の問題、ナビゲーションエラーはページアクセスの問題、タイムアウトはフィクスチャが安定状態にならなかった可能性を示す。型のアサーション失敗は、返却データがフィクスチャの期待と一致しなかったことを意味する。これらはそれぞれ異なる修正が必要である。

検出をソルバーのワークフローに慎重に接続する

検出はソルバ決定のための情報を提供するが、次のステップではタスクが必要とするページコンテキストを保持しなければならない。

公式 SDK ガイドでは、ブラウザソルビングを別の操作として説明している。本番ワークフローで同一ページ上で解いて処理を継続する必要がある場合、そのページとブラウザコンテキストを操作の間も保持しておくこと。このチュートリアルの診断キーワードはブラウザを閉じるため、既存のログイン済みセッションを引き継ぐステップとして、そのまま使えるわけではない。

すでに SeleniumLibrary や Robot Framework Browser を使っているチームは、自分たちのアクティブなブラウザと、この例が開くブラウザを明確に区別すること。同じ URL を共有しても、Cookie、これまでの操作、ページオブジェクトは共有されない。「テストのアクティブブラウザでチャレンジを解いた」と主張しながら、実際には別ブラウザで処理してしまうことのないようにする。

通常の自社サイトの回帰テストでは、プロバイダのテストキーを使う方がシンプルな場合も多い。本当にテスト目的が統合の検証を必要とする場合にだけ、実際のソルバパスを利用すること。reCAPTCHA テストキーのガイドでは、その境界について詳しく説明している。

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

小さく明示的なチェックポイントを使って、「認識された CAPTCHA」と「一般的な要素の失敗」とを区別しよう。CapSolver は本例で検出機能を提供し、Robot Framework はその結果を読みやすいテストアサーションに変換する。有料ソルビングは、ページの所有権とアプリケーションの結果チェックが正しく設定された、別個に検証されたステップとしてのみ追加すること。

FAQ

Q: この Robot テストは CAPTCHA を解きますか？

いいえ。フィクスチャの CAPTCHA を検出し、その公開パラメータを返すだけだ。テストは有料のソルビングを要求せず、本番フォーム送信の検証も行わない。

Q: これは公式の Robot Framework プラグインですか？

いいえ。Python キーワードラッパーは、Robot Framework のドキュメント化されたライブラリ機構と公式 Core SDK をベースにした例である。挙動を検証できるよう、ラッパーの実装そのものを掲載している。

Q: SeleniumLibrary のテスト内でも同じキーワードを使えますか？

呼び出すことはできるが、別の Playwright ブラウザが開かれる。SeleniumLibrary のブラウザセッションを検査したり、そのまま続行したりはしない。既存セッションとの統合には、明示的かつサポートされたハンドオフが必要になる。

Q: フィクスチャが空リストを返すのはなぜですか？

ウィジェットスクリプトがロードされたか、想定したページが配信されているか、SDK が存在するチャレンジをサポートしているかを確認すること。空の結果だけでは原因を特定できない。

Q: この例にソルバー API キーは必要ですか？

ここで示したパラメータ検出チェックは、有料ソルビングタスクを送信しない。本番でのソルビングステップには、その操作向けにドキュメント化された認証情報と前提条件が必要になる。

Q: すべての自動テストで CAPTCHA ソルバーを呼び出すべきですか？

いいえ。適切な場面では、通常の自社サイトの回帰テストにはプロバイダのテストメカニズムを使うこと。ソルバー統合テストは、それ自体が検証対象となるワークフローに限定して実施する。