Quando o teste de CAPTCHA falha no pipeline de QA e funciona na sua máquina, o culpado quase nunca é o widget: é o caminho de saída da rede. Runners em nuvem saem por faixas de IP compartilhadas, com latência e reputação diferentes das do seu notebook, e o desafio raro vira constante. A saída é montar um ambiente staging próprio no qual egress, token e validação de backend sejam medidos com números — é o que este guia mostra, com Python e a API da CaptchaAI.
O escopo é ambiente próprio: páginas internas, sitekey de QA, dados fictícios e endpoints da sua equipe — nunca serviços de terceiros.
Por que o caminho de saída da rede muda o resultado do teste
Um desafio de verificação é avaliado com sinais de contexto, e o endereço de origem é um deles. Dois runners idênticos podem ter taxas de desafio bem diferentes conforme a saída de rede. Não se trata de disfarçar a origem, e sim de estabilizar e documentar o egress do ambiente de teste.
Três decisões definem a estabilidade da suíte:
- Consistência do endereço de saída. Carregar a página, obter o token e enviar o formulário devem passar pelo mesmo caminho. Trocar de endereço no meio do fluxo é a causa número um de token recusado.
- Proximidade geográfica. Um runner em
sa-east-1(São Paulo) testando uma aplicação na mesma região reduz o RTT e torna os tempos comparáveis. - Ritmo das requisições. Uma suíte que dispara em rajada mede o próprio limite de requisições, não a integração. Intervalos de 3 a 15 segundos deixam a métrica legível.
Modelo de ambiente staging para CAPTCHA
Monte uma página interna com sitekey de QA, usuário fictício, payload previsível e um endpoint de verificação separado da produção, reproduzindo o fluxo técnico completo sem efeito real para usuários ou clientes.
Use identificadores explícitos de teste: qa_user_001, qa_session_001, qa_case_001. O backend deve aceitar apenas tokens vinculados ao domínio staging e gravar cada resultado em uma tabela de testes. Essa separação permite rodar a suíte várias vezes por dia sem sujar métricas de negócio — e, no contexto brasileiro, mantém o exercício alinhado às obrigações da LGPD, já que nenhum dado pessoal real circula pelo teste.
A CaptchaAI cobre reCAPTCHA v2 e v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3 e CAPTCHAs de imagem/OCR e de grade; CaptchaFox (beta), Friendly Captcha (beta) e Lemin (beta) estão em beta. hCaptcha, FunCaptcha e GeeTest v4 não são suportados — se a página de QA usar um desses, troque a sitekey do caso.
Enviar a tarefa a partir do runner autorizado
Envie a tarefa do runner de QA e registre o ID retornado para rastreabilidade.
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)})
Duas observações: a chave de API vem de variável de ambiente, nunca do repositório; e a pausa de 5 s antes da primeira consulta é intencional, porque consultar res.php imediatamente só devolve "não pronto".
Validar o token no backend de QA
Encaminhe o token para um endpoint interno como https://staging.example.com/qa-captcha/verify, que valida a resposta junto ao provedor e devolve apenas um resultado de teste, sem acionar lógica de negócio. Se falhar aqui, o problema está entre o token e o backend, não na resolução. Mantenha o mesmo caminho de saída entre obter o token e enviá-lo.
Logging: o que registrar em cada execução
Registre, por caso: sitekey, pageurl, tipo de CAPTCHA, região do runner, horário de envio, tempo até o token, status do backend e o identificador do caso QA. Com isso você separa uma regressão de código de uma variação de rede, sem expor dado sensível. Acompanhe também a taxa de sucesso na primeira tentativa: quando ela cai sem mudança de código, o suspeito costuma ser o egress.
Cenário de exemplo: suíte noturna de uma equipe em São Paulo
Uma equipe roda 200 casos de formulário toda noite, a partir de workers em sa-east-1, contra um clone staging da própria aplicação. Cinco a dez tarefas simultâneas bastam: o BASIC (US$ 15/mês, 5 threads) atende suítes pequenas e o STANDARD (US$ 30/mês, 15 threads) dá folga para paralelizar. A cobrança é por thread simultânea, com resoluções ilimitadas no plano — dimensionar é decisão de concorrência, não de volume mensal.
Solução de problemas
| Sintoma | Causa provável | O que fazer |
|---|---|---|
| Token recusado pelo backend | Caminho de saída mudou entre resolver e enviar | Fixe o egress durante todo o caso |
| Desafio em todos os casos | Runner em faixa saturada ou disparo em rajada | Espace as requisições e revise a saída |
| Tempos muito variáveis | Runners em regiões diferentes | Padronize a região e repita a medição |
| Erro de sitekey inválida | Sitekey de produção na página staging | Use a sitekey de QA do domínio autorizado |
| Token expirado no envio | Fila interna entre resolução e submissão | Reduza o intervalo ou reenvie o caso |
Use backoff exponencial apenas dentro da suíte de QA e limite as tentativas por caso, para que uma falha de ambiente não vire consumo silencioso de threads.
Critérios antes de publicar a mudança
Antes de promover a alteração, confirme que os exemplos usam dados fictícios, que nenhum endpoint de produção é acionado e que os logs permitem auditoria. A página staging precisa de domínio autorizado, sitekey esperada, backend separado e política clara de expiração de token. Trate os números como amostra interna: repita a medição e compare apenas cenários equivalentes.
Perguntas frequentes
Preciso de proxies para testar CAPTCHA em staging?
Não necessariamente. O que importa é que o caminho de saída seja estável e conhecido. Se a suíte já roda em uma região fixa e com egress previsível, isso basta para medições comparáveis.
Por que o mesmo teste passa localmente e falha no CI?
Quase sempre por diferença de egress e de ritmo. Padronize a região do runner, espace as requisições e refaça a medição antes de mexer no código.
Posso usar a sitekey de produção na página de QA?
Não. Ela costuma ser restrita ao domínio real e devolve erro de chave inválida no domínio staging. Gere uma sitekey de QA vinculada ao domínio de testes.
Quantas threads a suíte precisa?
Depende da concorrência, não do total de casos. Cinco casos simultâneos cabem no BASIC (US$ 15/mês, 5 threads); acima disso, o STANDARD (US$ 30/mês, 15 threads) evita fila. Como as resoluções são ilimitadas por thread, rodar a suíte mais vezes por dia não muda o plano.
Quais tipos de CAPTCHA posso usar na página de QA?
Use reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3 ou CAPTCHAs de imagem/OCR. Os tipos não suportados aparecem na seção do modelo de staging.
Guias relacionados seguros
- Início rápido da CaptchaAI
- Testes QA autorizados de CAPTCHA
- Testes de endpoint CAPTCHA em formulários próprios
- Depuração quando o navegador falha e a API funciona
- Resolver reCAPTCHA v2 com API
- Resolver Cloudflare Turnstile com API
- Resolver GeeTest v3 com API
Monte seu ambiente de validação e resolva o primeiro desafio com a CaptchaAI.
