如何在 Robot Framework 浏览器测试中检测 CAPTCHA

摘要

• Robot Framework 可以调用一个小型 Python 关键字库，该库使用官方 CapSolver Core SDK 来检查 CAPTCHA 页面。
• 示例会将检测到的 CAPTCHA 类型、页面 URL 和 sitekey 返回给 Robot 测试。
• 使用 Google 的公共 reCAPTCHA 测试密钥，对自有的开发页面运行测试。
• 该关键字会自行打开和关闭浏览器；它不会附着在 SeleniumLibrary 或 Browser Library 的会话上。
• 检测用于确认输入发现步骤。它既不会求解 CAPTCHA，也不能证明生产表单会接受求解结果。

当页面显示 CAPTCHA 而不是下一个断言期望的内容时，Robot Framework 浏览器测试可能失败。仅仅增加通用超时时间并不能解释这一改变。一个特定的 CAPTCHA 检查可以给测试提供有用的结果：受支持的求解器工作流所需的挑战类型和参数。

Robot Framework 是一个用于验收测试和机器人流程自动化的开源框架。其关键字语法允许团队表达检查逻辑，而底层操作由 Python 库实现。本教程将一个 Python 关键字连接到 CapSolver 的官方 Core SDK，并验证 Robot 能从浏览器页面接收到真实的检测结果。

CAPTCHA 检测在 Robot 测试中的位置

CAPTCHA 检测应该放在一个已知的页面检查点上，在测试把被拦截的页面当作正常应用响应处理之前。

例如，一个被允许的浏览器工作流本来期望出现搜索表单，却到达了挑战页面。首要的有用问题是：是否存在受支持的 CAPTCHA。识别结果随后可以指导一个可控的下一步：使用有文档的求解集成、暂停等待人工操作，或记录一个特定的测试失败。

这不同于把每一个缺失元素都当成 CAPTCHA。页面也可能因为应用脚本未加载、路由改变或选择器错误而失败。将 CAPTCHA 检测和这些诊断区分开来。

Robot Framework 用户指南 记录了 Python 测试库和关键字执行机制。下面这个小库利用的就是这一扩展点。它只是一个集成示例，并不意味着 Robot Framework 自带原生的 CapSolver 库。

在同一个环境中安装依赖包

在同一个 Python 环境中安装 Robot Framework、Playwright 和 Core SDK，使测试运行器可以导入这三者。

示例使用 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 奖励码

立即提升你的自动化预算！
在为 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 则将其结果转化为可读的测试断言。仅在具备正确页面所有权和应用结果检查的前提下，单独添加付费求解步骤并进行验证。

常见问题

问：这个 Robot 测试会求解 CAPTCHA 吗？

不会。它只检测固件的 CAPTCHA 并返回其公共参数。测试不会发起付费求解，也不会验证生产表单的提交。

问：这是官方的 Robot Framework 插件吗？

不是。这个 Python 关键字封装只是基于 Robot Framework 已文档化的库机制和官方 Core SDK 的示例。完整封装代码已包含在文中，以便检查其行为。

问：我能在 SeleniumLibrary 测试中使用同一个关键字吗？

可以调用该关键字，但它会打开一个独立的 Playwright 浏览器。它不会检查或延续 SeleniumLibrary 的浏览器会话。对已有会话的集成需要明确且受支持的衔接方案。

问：为什么固件会返回空列表？

请检查小组件脚本是否已加载、是否在提供预期页面，以及 SDK 是否支持当前挑战类型。仅凭空结果本身无法确定原因。

问：这个示例需要求解器 API 密钥吗？

示范的参数检测检查不会提交付费求解任务。生产求解步骤需要该操作文档中说明的凭据和前提条件。

问：每个自动化测试都应该调用 CAPTCHA 求解器吗？

不应该。在合适情况下，对常规自有站点回归测试使用提供方的测试机制。将求解器集成测试保留给其真正要验证的工作流，并保持范围可控。