在自有搜索结果页上对 CAPTCHA 进行 QA 测试

安全范围： 本指南仅适用于你自有或经授权的 QA、staging 与预发布环境。内容覆盖针对你自己 CAPTCHA 集成的诊断、测试与可观测性模式 — 不涉及第三方站点或未授权流程。

结果页前面挂了验证码，自动化回归照样跑得通：在 staging 用合成数据重建索引，脚本走一遍 widget，识别交给 CaptchaAI 的 API，最后确认后端 token 校验没被跳过。

搜索页为什么频繁触发验证码

搜索是高频入口，风控最激进：短时间内模式一致的查询会被判为自动化流量，而回归用例发的正是这种查询。国内站点多用 GeeTest（极验）滑块，海外站点以 reCAPTCHA v3 与 Turnstile 为主，一条流水线要覆盖两条路径。

第一步：用合成数据搭 staging 索引

不要同步生产库。用 fixture 生成合成文档灌进索引，查询词固定为 qa-term-001 到 qa-term-050，断言就能写死。网络安全法、数据安全法与 PIPL 也要求如此：真实个人信息不进测试环境。

第二步：走通 CaptchaAI 验证码识别

staging 用独立的 sitekey 与 secret，白名单只填该域名。脚本固定三步：提取 sitekey、提交任务、轮询拿 token。超时按官方 SLA 上限设：reCAPTCHA v3 < 4 秒，Turnstile < 10 秒，GeeTest v3 < 12 秒，reCAPTCHA v2 < 60 秒。

第三步：确认后端真的在校验 token

断言三条：带合法 token 的请求返回预期结果；缺少 g-recaptcha-response 的请求被拒绝；已消费的 token 重复提交被拒。后两条才是回归价值所在：字段名写错或校验被注释掉，只有它们能发现。

示例：一次最小的 QA 识别调用

API Key、页面地址与 sitekey 从环境变量读取。

import os
import requests

API_KEY = os.environ['CAPTCHAAI_KEY']
QA_PAGE_URL = os.environ['QA_PAGE_URL']  # 例如 https://staging.example.com/qa-login
QA_SITE_KEY = os.environ['QA_SITE_KEY']


def submit_qa_recaptcha() -> str:
    payload = {
        'clientKey': API_KEY,
        'task': {
            'type': 'NoCaptchaTaskProxyless',
            'websiteURL': QA_PAGE_URL,
            'websiteKey': QA_SITE_KEY,
        },
    }
    response = requests.post(
        'https://api.captchaai.com/createTask',
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()['taskId']


def fetch_qa_result(task_id: str) -> dict:
    payload = {'clientKey': API_KEY, 'taskId': task_id}
    response = requests.post(
        'https://api.captchaai.com/getTaskResult',
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

拿到 token 后填进表单的 g-recaptcha-response 字段提交即可。

日志与指标

每次运行留下结构化日志：token 耗时、HTTP 响应码、任务编号、队列深度，用 correlation id 串起来便于重放。若耗时整体抬高而服务侧平稳，多半是本地网络问题。

常见故障与处理方式

接入 CI 前的检查清单

• 测试范围限定在自有或授权资源。
• API Key 放在 CI secret 或 vault，不进源代码。
• staging 用独立密钥，不复用生产 sitekey。
• 瞬时错误用幂等重试加指数退避（1s、2s、4s）。

常见问题

staging 能复用生产的 sitekey 吗？

不建议。单独注册一套密钥对，白名单只填 staging 域名，QA 流量就不会混进线上风控数据。

CaptchaAI 覆盖哪些验证码类型？

正式支持 reCAPTCHA v2/v3（含 Enterprise）、Cloudflare Turnstile 与 Challenge、GeeTest v3、图片/OCR 与九宫格；CaptchaFox、Friendly Captcha、Lemin 为测试版。hCaptcha 与 FunCaptcha 暂不支持，GeeTest v4 为即将支持。

并行跑回归需要多少线程？

线程指同时在跑的验证码数量，不是识别次数。串行跑用例 BASIC（$15/月，5 线程）够用；几十条并行再看 ADVANCE（$90/月，50 线程）。

相关阅读

• 快速上手
• 授权测试的范围
• 自有表单的接口测试
• 浏览器侧失败、API 侧正常
• 识别 reCAPTCHA v2
• 识别 Cloudflare Turnstile
• 识别 GeeTest v3

在自有环境中用 CaptchaAI 验证你的验证码集成。