面向自有 QA 的 Puppeteer + CaptchaAI 进阶模式

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

Puppeteer 驱动的 QA 套件规模变大后，最先出问题的往往是并发失控，而非 CAPTCHA 本身——staging 被打满、context 互相干扰、日志分不清是哪次 run 出错。下面几种模式已在自有环境验证。

并发控制：按 case 限流，而不是按机器打满

把并发粒度落在 qa_case_id 上，而不是多开浏览器实例——不会刷爆 staging 或撞配额，出问题也能快速定位到具体 case。

复用 BrowserContext，压缩总耗时

在不会破坏状态的相邻步骤间复用同一个 BrowserContext，能省下重复启动开销，压缩总耗时——相邻步骤没有切换登录态、没有跨用户操作即可。

干净退出，避免 CI 句柄泄漏

始终在 finally 块里关闭 page 与 context，CI 长时间运行后未关闭的 handle 会吃满内存，表现为随机超时而非崩溃——退出逻辑提前做干净，比事后排查省事。

常见报错与处理

可观测性：让每次 QA 运行都能被复盘

给每次 QA 运行打上结构化日志，至少覆盖：

• token 耗时
• HTTP 响应码
• 任务编号
• 队列深度

按环境拆分独立日志通道，用 OpenTelemetry 之类工具串联 correlation id——凭一个 id 就能重放整条链路，诊断时间通常能减半。

上线前检查清单

1. 测试范围只覆盖自有应用或已授权资源，不越界。
2. CaptchaAI key 放进 CI secret 仓库或 vault，绝不写进源码。
3. 每次运行落盘调用耗时与响应状态码，方便回溯。
4. 瞬时错误的重试策略必须幂等，并设好上限。
5. 测试能在 CI 里稳定重复运行。

出海团队提示：staging 常跑 Turnstile，而非国内常见的极验滑块；CI 镜像配清华 TUNA 源可减少安装超时。

最小可用示例：Python 调用 CaptchaAI

下面的 Python 示例展示了在自有 staging 环境中用 CaptchaAI 测试 CAPTCHA widget 的最小流程。

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.example.com 或你自有 QA 域名等授权环境，在 staging 副本中复现生产配置即可。

API key 可以写在代码里吗？

不可以，用 CI secret 管理器、环境变量或 vault 注入；已经提交到仓库的 key 要立即轮换。

对瞬时错误应该怎么重试？

幂等重试，配合指数退避（1s、2s、4s）和上限；网络错误、5xx 和 ERROR_NO_SLOT_AVAILABLE 适合重试，持久性鉴权错误不应重试。

这套模式只适用于 Turnstile 吗？

提交、轮询、重试这套结构对 reCAPTCHA v2、GeeTest v3 同样适用，换个 method 参数即可。

延伸阅读

• CaptchaAI 快速入门
• 授权 CAPTCHA QA 测试
• 自有表单的 CAPTCHA endpoint 测试
• 浏览器测试失败但 API 测试通过的调试
• 使用 API 解决 reCAPTCHA v2
• 使用 API 解决 Cloudflare Turnstile
• 使用 API 解决 GeeTest v3

在自有环境中用 CaptchaAI 验证你的 CAPTCHA 集成，把 QA 流程跑得更稳。