QA de CAPTCHA para busca interna em staging

No dia em que a busca interna do seu produto ganha um reCAPTCHA v3, a suíte de testes para de chegar ao backend: a requisição volta 200, mas com uma página de verificação no lugar dos resultados. A saída não é desligar a proteção no ambiente de teste — é reproduzir o fluxo em staging, com sitekey de QA, dados fictícios e endpoint de verificação separado, resolvendo o desafio pela API da CaptchaAI para que o teste percorra o mesmo caminho de produção. Abaixo, como montar esse ambiente e quando liberar a mudança.

Escopo seguro deste guia

Tudo aqui vale apenas para ambientes próprios: QA, staging ou pré-produção com autorização explícita. As páginas são internas, os usuários são fictícios e o endpoint de verificação é seu. Nada se aplica a serviços de terceiros ou a controles de acesso fora do seu domínio — se a busca que você quer testar não é sua, este guia não é o caminho.

Por que a busca interna é o fluxo mais difícil de testar

Login e checkout costumam ter uma rota de teste combinada. A busca, não: é pública, recebe tráfego automatizado de verdade e ganha reCAPTCHA v3 cedo. Daí três sintomas na suíte:

• Falha silenciosa. O status continua 200 e o assert quebra em um seletor, não no CAPTCHA — o time procura bug de front-end onde não há.
• Não reproduz local. A pontuação do reCAPTCHA v3 depende do ambiente; o runner de CI e o notebook de quem desenvolve não recebem o mesmo tratamento.
• Gambiarra permanente. Alguém desativa o desafio em staging "só para o teste passar" e staging deixa de representar produção.

Resolver o desafio dentro da própria suíte devolve a paridade: mesmo widget, mesma verificação no backend.

Monte a página de staging antes de escrever o teste

Antes do primeiro assert, a página de QA precisa de quatro itens: uma sitekey (chave pública do widget) emitida só para o domínio de staging, um usuário fictício sem vínculo com dados reais, um payload de busca previsível e um endpoint de verificação separado do de produção. Assim o teste percorre o caminho técnico — widget, token, verificação — sem gerar efeito para clientes ou faturamento.

Versione essas definições junto com os testes: quando a sitekey for rotacionada, é esse arquivo que explica a quebra em trinta segundos.

Dados fictícios e identificadores rastreáveis

Use identificadores previsíveis: qa_user_001, qa_session_001 e qa_case_001. O backend deve aceitar apenas tokens vinculados à página de staging e gravar o resultado em uma tabela de testes, nunca na tabela de produção.

Há também uma leitura jurídica: a LGPD trata dado pessoal independentemente do ambiente, então uma base de QA populada com dump de produção vira risco desnecessário. Dados sintéticos resolvem o teste e encurtam a conversa de conformidade. Em Portugal, o mesmo vale para o RGPD.

Envie a tarefa à CaptchaAI a partir do runner de QA

O runner autorizado envia a tarefa, guarda o ID e espera o token. Registrar o ID é o que permite correlacionar depois um teste vermelho com uma resolução específica.

import os, time, requests

API_KEY = os.environ['CAPTCHAAI_API_KEY']
SITEKEY = os.environ['QA_CAPTCHA_SITEKEY']

def criar_tarefa_captcha(pageurl):
    resposta = requests.post('https://ocr.captchaai.com/in.php', data={
        'key': API_KEY,
        'method': 'userrecaptcha',
        'googlekey': SITEKEY,
        'pageurl': pageurl,
        'json': 1,
    }).json()
    return resposta['request']

def aguardar_resultado(task_id):
    while True:
        time.sleep(5)
        resposta = requests.get('https://ocr.captchaai.com/res.php', params={
            'key': API_KEY,
            'action': 'get',
            'id': task_id,
            'json': 1,
        }).json()
        if resposta.get('status') == 1:
            return resposta['request']

task_id = criar_tarefa_captcha('https://staging.example.com/captcha-demo')
token_qa = aguardar_resultado(task_id)
print({'token_recebido': bool(token_qa)})

Valide o token no backend de teste

Com o token em mãos, encaminhe-o ao endpoint interno — por exemplo https://staging.example.com/qa-captcha/verify. Ele verifica a resposta junto ao provedor do CAPTCHA e devolve só um resultado de teste com o motivo. O campo enviado continua sendo g-recaptcha-response — manter o nome idêntico ao de produção é o que garante que o teste exercita o mesmo código.

O que registrar em log

Grave, em cada execução: sitekey, pageurl, tipo de CAPTCHA, horário de envio, tempo até o token, status do backend e identificador do caso de QA. Isso basta para reconstruir uma regressão sem guardar nada sensível.

Trate o tempo de resolução como série, não como número isolado. Um runner em São Paulo (região sa-east-1) e outro na Europa produzem RTT diferentes; comparar regiões distintas sem anotar isso rende discussão inútil no PR.

Quando o teste falha: checklist de diagnóstico

Percorra nesta ordem:

1. A sitekey usada é a de staging, e não a de produção?
2. O domínio de staging está autorizado para essa sitekey?
3. O token expirou entre a resolução e o envio? Pipelines lentos estouram a janela com facilidade.
4. O relógio do runner está sincronizado?
5. O navegador headless e a chamada de API apontam para a mesma pageurl?

Retentativas com backoff exponencial só dentro da suíte de QA e com limite — nunca em loop aberto.

Threads, paralelismo e custo da suíte

A CaptchaAI cobra por thread concorrente, com resoluções ilimitadas dentro do plano — modelo que combina com CI, onde o pico é curto. O que importa é quantos casos com CAPTCHA rodam ao mesmo tempo, não quantas execuções por dia. Até cinco simultâneos cabem no BASIC (US$ 15/mês, 5 threads); pipelines mais paralelos pedem STANDARD (US$ 30/mês, 15 threads) ou ADVANCE (US$ 90/mês, 50 threads).

Sobre cobertura: reCAPTCHA v2 e v3, Cloudflare Turnstile e Cloudflare Challenge, GeeTest v3, CAPTCHAs de imagem/OCR e desafios em grade são suportados. hCaptcha e FunCaptcha (Arkose Labs) não são; o GeeTest v4 está anunciado como "em breve". CaptchaFox, Friendly Captcha e Lemin estão em beta.

Critérios para liberar a mudança

Antes de aprovar o PR, confirme: a documentação do teste aponta para ambiente próprio; os exemplos usam dados fictícios; nenhum endpoint de produção é acionado; e os logs têm correlação suficiente para auditoria. A página de staging precisa ter domínio autorizado, sitekey esperada, backend separado e política clara de expiração de token.

Quando os números variarem, trate-os como amostra interna: repita a medição, anote a janela e compare só cenários equivalentes.

Perguntas frequentes

Posso usar a sitekey de produção no ambiente de staging?

Não. Emita uma sitekey específica para o domínio de staging: isso mantém as execuções automatizadas fora da telemetria de produção e permite revogar a chave de QA sem afetar usuários reais.

O token expira antes de o pipeline terminar. O que faço?

Resolva o CAPTCHA o mais perto possível do envio do formulário, não no início do job. Se essa etapa for longa, quebre o teste em dois passos: o log de "tempo até o token" costuma denunciar o gargalo.

E se a página de staging usar hCaptcha?

Não dá para cobrir esse caso pela API: o hCaptcha não é suportado atualmente, assim como o FunCaptcha (Arkose Labs). Combine com o time responsável pela proteção uma rota de QA alternativa para esses cenários.

Quantas threads preciso para rodar os testes em paralelo?

Uma thread por caso com CAPTCHA executando ao mesmo tempo. Conte os jobs paralelos no pior cenário — várias branches em merge na mesma janela — e dimensione por esse pico, não pela média.

Guias relacionados seguros

• Comece pelo início rápido da CaptchaAI
• Como estruturar testes de CAPTCHA autorizados
• Testar endpoints de CAPTCHA em formulários próprios
• O navegador falha e a API funciona: como depurar
• Resolver reCAPTCHA v2 pela API
• Resolver Cloudflare Turnstile pela API
• Resolver GeeTest v3 pela API

Feche o ciclo de QA da sua busca interna com a CaptchaAI.