在自有流程上使用 CaptchaAI 进行多步 QA 测试

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

多步骤流程里最容易让 CI 变红的，是中间某一步的 CAPTCHA widget 没按预期出现，或 token 在断言前就已过期。先看排查表，再落实设计与幂等约定，可把脆性问题降到最低。

常见故障与排查方式

为什么多步骤流程需要单独设计 CAPTCHA 处理

给每一步分配独立的 qa_case_id 与 step_id，只在页面确实渲染出 widget 时才调用 CaptchaAI —— 纯状态检查类步骤本就不会触发验证码，提前判断能省掉调用。

三步 CI 场景：注册 → 短信验证 → 开通功能

国内团队常把这条链路搬进 CI，用清华 TUNA 等镜像加速依赖安装：

1. 注册：提交表单触发 widget，记为 step_id=register
2. 短信验证：校验验证码，通常不触发图形 CAPTCHA
3. 开通功能：Turnstile 二次校验，step_id 与环境写进结构化日志，方便回放

保证幂等性：同一 step_id 复用 token

token 仍在有效期内时，同一 step_id 的重试应复用已有 token，而非重新调用 CaptchaAI，既省请求量，也避免结果不一致。

全链路可观测性：日志、指标与分布式追踪

为每个 qa_case_id 建仪表盘，展示各步耗时与后端结果；同时采集 token 总耗时、HTTP 响应码、任务编号、队列深度等指标。

不同环境的日志写入独立通道，用 OpenTelemetry 等工具以同一个 correlation id 串联各步骤，凭单一 id 回放整个场景，排查时间通常能砍半。

上线前检查清单

• 测试范围限定在自有应用或经授权资源。
• CaptchaAI key 存放在 CI secret 仓库或 vault，不入库。
• 每次运行记录调用耗时与响应状态码。
• 为瞬时错误配置幂等重试与上限。
• 测试可在 CI 中复现重复运行。

示例：Python 端到端 QA 调用

下面的 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 等授权环境，只需在 staging 副本中复现与生产一致的 CAPTCHA 配置。

API key 能不能直接写进脚本里？

不能。请通过 CI secret 管理器、环境变量或 vault 注入；一旦发现 key 已提交进代码仓库，必须立即轮换。

遇到 ERROR_NO_SLOT_AVAILABLE 或超时该怎么重试？

按幂等策略重试，配合指数退避（1s、2s、4s）并设置上限；5xx 与 ERROR_NO_SLOT_AVAILABLE 可自动重试，鉴权类持久性错误不重试。

安全相关指南

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

请在自有环境中使用 CaptchaAI 验证多步骤 CAPTCHA 集成。