安全范围： 本指南仅适用于你自有或经授权的 QA、staging 与预发布环境。内容覆盖针对你自己 CAPTCHA 集成的诊断、测试与可观测性模式 — 不涉及第三方站点或未授权流程。
Puppeteer 跑 staging 表单的 CAPTCHA 冒烟测试，最大的坑往往不是“识别不出验证码”，而是换了个环境就找不到 widget。这篇给出一套可直接搬进 CI 的模式：用 Puppeteer 定位 reCAPTCHA、Turnstile 或 GeeTest widget，把 sitekey 和 pageurl 提交给 CaptchaAI，再把 token 写回表单并验证 — 全程只在自己的环境里跑，不触碰生产流量，也不自动化第三方站点。
适用范围与开始前的检查清单
- 仅限自有或经授权的 staging 表单，覆盖表单渲染、widget 加载与 token 提交，用虚拟用户、测试表单、虚拟 checkout。
- CaptchaAI 的 API Key 存放在 CI secret 仓库或 vault 中，绝不写进源代码。
- 按
qa_case_id记录调用耗时与响应状态码，为瞬时错误配置幂等重试并设上限，确保测试能在 CI 中反复运行。
配置用于 QA 的 Puppeteer 环境
npm install puppeteer
const puppeteer = require('puppeteer');
async function launchQa() {
return puppeteer.launch({ headless: 'new', args: ['--no-sandbox'] });
}
在自有 staging 页面上定位 CAPTCHA widget
const browser = await launchQa();
const page = await browser.newPage();
await page.goto('https://staging.example.com/qa-form');
const sitekey = await page.$eval('.g-recaptcha', el => el.dataset.sitekey);
把 sitekey 提交给 CaptchaAI
把 sitekey 和当前页面的 pageurl 提交给 CaptchaAI，再轮询结果：
const fetch = require('node-fetch');
const KEY = process.env.CAPTCHAAI_API_KEY;
async function solve(sitekey, pageurl) {
const submit = await fetch(`https://ocr.captchaai.com/in.php?key=${KEY}&method=userrecaptcha&googlekey=${sitekey}&pageurl=${pageurl}&json=1`).then(r => r.json());
while (true) {
await new Promise(r => setTimeout(r, 5000));
const res = await fetch(`https://ocr.captchaai.com/res.php?key=${KEY}&action=get&id=${submit.request}&json=1`).then(r => r.json());
if (res.status === 1) return res.request;
}
}
校验内部 QA 接口的响应
把 token 以合适的 body 字段提交到内部 QA backend endpoint（例如 https://staging.example.com/checkout-test），检查响应状态码。
日志、追踪与可观测性
为每个 qa_case_id 记录求解耗时、响应状态与重试次数，汇总中位数和 P90（仅作 staging 参考值）。再采集 HTTP 响应码、任务编号与队列深度，写入独立日志通道，用 OpenTelemetry 等分布式追踪关联 correlation id —— 凭一个 id 即可重放链路，排查耗时通常能减半。
常见故障与处理方式
| 问题 | 处理方式 |
|---|---|
| 测试找不到 widget | 检查 staging 环境中的选择器与等待时机 |
CaptchaAI 返回 ERROR_NO_SLOT_AVAILABLE |
在内部 pipeline 中按指数退避重试 |
| 后端 QA 拒绝 token | 对照真实配置核对 action / sitekey / secret |
| 端到端时延偏高 | 在自有环境中重新测量，并检查内部网络抖动 |
Python 示例：在 QA 环境提交并查询任务
下面的 Python 示例展示了在自有 staging 环境中，通过 CaptchaAI 测试一个 CAPTCHA widget 的最小流程；本地 pip 源慢时可加 -i 参数指向国内镜像（如清华 TUNA）再装 requests。
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()
若 staging 环境部署在无法稳定访问 Google 托管脚本的网络里，reCAPTCHA widget 可能加载失败——国内团队 CI 中很常见，可把该 CI runner 放到海外区域，或优先跑 Turnstile 与 GeeTest（国内更常见 GeeTest（极验），CaptchaAI 目前支持到 v3）冒烟测试。
常见问题
这些测试会接触生产流量吗？
不会。示例都假设 staging.example.com 或你自有的 QA 域名等授权环境，请在自己的 staging 副本中复现生产 CAPTCHA 配置再测试。
CaptchaAI 的 API Key 应该放在哪里？
不要写进代码仓库。通过 CI secret 管理器、环境变量或 vault 注入；已提交到仓库的 Key 必须立即轮换。
轮询超时或返回 ERROR_NO_SLOT_AVAILABLE 该怎么处理？
用幂等重试配合指数退避（如 1s、2s、4s）并设上限。网络错误、5xx 与 ERROR_NO_SLOT_AVAILABLE 适合重试；持久性鉴权错误不要重试，应直接报警。
为什么脚本有时找不到 CAPTCHA widget？
多数是等待时机不对——widget 异步渲染，load 事件触发时可能还没插入 DOM。用 waitForSelector 显式等选择器出现，比固定 sleep 更可靠。
QA 场景下 Puppeteer 用 headless 还是 headed 模式更稳？
日常回归用 headless: 'new'，速度快、适合 CI；只有需要肉眼确认渲染或调试选择器时才切 headed 模式本地跑。
相关阅读
- CaptchaAI 快速入门
- 授权 CAPTCHA QA 测试方法
- 自有表单的 endpoint 测试
- 浏览器测试失败但 API 通过时排查
- 使用 API 解决 reCAPTCHA v2
- 使用 API 解决 Cloudflare Turnstile
- 使用 API 解决 GeeTest v3
在自有环境中用 CaptchaAI 验证 CAPTCHA 集成。
