Um token de reCAPTCHA vencido ou reenviado fora da janela certa é uma causa clássica de falso negativo em suíte de QA: o teste falha, mas a integração está correta — o problema é o tempo. Este guia mostra como montar, em ambiente próprio, um diagnóstico repetível do ciclo de vida do token para reCAPTCHA v2, reCAPTCHA v3 e Cloudflare Turnstile: emissão, janela de validade, tentativa de reuso e expiração.
Escopo seguro do diagnóstico
Este guia vale apenas para ambientes próprios, QA, staging ou pré-produção com autorização explícita da equipe. Os exemplos usam páginas internas, dados fictícios e endpoints de validação controlados por você — nada aqui automatiza serviços de terceiros, compras reais, filas públicas ou controles de acesso fora do seu ambiente.
Por que o token expira durante o teste
Cada tipo de CAPTCHA tem uma janela de validade diferente, e conhecer esses números evita que você confunda um bug real de integração com um teste mal cronometrado:
| Tipo de CAPTCHA | Janela de validade típica | Implicação para o teste |
|---|---|---|
| reCAPTCHA v2 | ~120 segundos | Token de uso único na maioria dos sites — consuma logo após receber |
| reCAPTCHA v3 | ~120 segundos | A pontuação pode variar a cada nova emissão; não valide reuso |
| Cloudflare Turnstile | ~300 segundos | Janela mais longa, mas ainda expira — cubra o caso de expiração no teste |
Use essa tabela para calibrar os timeouts do seu runner de QA: se a suíte demora mais que a janela de validade para consumir o token, o teste falha mesmo com a integração correta.
Monte o cenário de QA em staging
Crie uma página interna com sitekey de QA, usuário fictício, payload previsível e endpoint de verificação separado de produção. O objetivo é reproduzir o fluxo técnico completo — emissão, consumo e expiração — sem gerar efeitos reais para usuários, clientes ou parceiros.
Contas e dados fictícios do teste
Use identificadores como qa_user_001, qa_session_001 e qa_case_001. O backend deve aceitar apenas tokens vinculados à página staging e gravar cada resultado em uma tabela de testes separada da produção.
Envie a tarefa CaptchaAI pelo runner de QA
Envie a tarefa a partir do runner autorizado e registre o ID retornado — é esse identificador que conecta a emissão do token ao resultado da validação no passo seguinte.
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 a resposta no backend de QA
Depois de receber o token, encaminhe-o para um endpoint interno como https://staging.example.com/qa-captcha/verify. O backend valida a resposta junto ao provedor CAPTCHA e retorna apenas um resultado de teste — nunca aplique esse token em um fluxo de produção real.
Registre logs para rastrear regressões
Registre sitekey, pageurl, tipo de CAPTCHA, tempo de envio, tempo de resposta, status do backend e identificador do caso QA. Esses campos ajudam a separar uma falha real de integração de uma janela de expiração mal calculada.
Aplique aos logs de QA o mesmo cuidado de minimização de dados que a LGPD exige em produção: use só os identificadores fictícios do teste, nunca dados reais de usuários, e defina uma retenção curta para essa tabela. Meça também o tempo de rede do runner: um runner hospedado longe do backend (por exemplo, fora da região sa-east-1 da AWS quando o backend é servido de São Paulo) pode consumir parte da janela de validade do token só em latência — o que se parece com uma falha de integração sem ser uma.
Diagnostique problemas comuns no teste
| Sintoma | Causa provável | Como confirmar |
|---|---|---|
| Teste falha de forma intermitente | Token expirou entre a emissão e o consumo | Compare o timestamp de emissão com o de consumo no log |
| Backend rejeita um token válido | sitekey ou domínio staging não corresponde ao esperado | Confirme a sitekey e o domínio permitido no backend de teste |
| Retentativa nunca conclui | Backoff sem teto máximo, mascarando a falha real | Defina um número máximo de tentativas e registre cada retentativa |
| Resultado diverge entre navegador e API | Relógio do runner dessincronizado | Sincronize o horário (NTP) no ambiente de CI/QA |
Faça retentativas com backoff apenas dentro da suíte QA, sempre com teto máximo — um loop sem limite mascara o sintoma em vez de expor a causa.
Critérios antes de liberar a mudança testada
Antes de considerar a mudança validada, confirme que a documentação aponta para ambiente próprio, que os exemplos usam dados fictícios, que nenhum endpoint de produção é acionado pelo teste e que os logs têm correlação suficiente para auditoria. A página staging deve ter domínio autorizado, sitekey esperada, configuração de backend separada e política clara de expiração. Quando o resultado do diagnóstico variar entre execuções, trate os números como amostra interna: repita a medição, anote a janela de execução e compare apenas cenários equivalentes.
Perguntas frequentes sobre o diagnóstico de tokens CAPTCHA em QA
Esse diagnóstico substitui o teste de carga da minha suíte de QA?
Não. Ele verifica a correção do ciclo de vida do token — emissão, consumo e expiração —, não o comportamento sob volume. Rode os dois tipos de teste separadamente e compare resultados apenas dentro do mesmo tipo.
Por que o token do reCAPTCHA não pode ser reaproveitado entre dois casos de teste?
Porque a maioria dos sites valida o token uma única vez. Se o caso de teste B tentar consumir o mesmo token que o caso A já usou, o backend vai rejeitar — e isso não indica bug na sua integração, indica que o teste está simulando um reuso que o próprio provedor não permite.
Como simulo a expiração do token sem esperar o tempo real no CI?
Isole o backend de validação do fluxo de emissão e alimente-o com um token propositalmente antigo, emitido antes da janela documentada na tabela acima. Isso testa a lógica de rejeição do seu backend sem depender do tempo real de espera.
Cloudflare Turnstile e reCAPTCHA se comportam da mesma forma na expiração?
Não exatamente. O Turnstile tem uma janela de validade mais longa (~300 segundos) que o reCAPTCHA v2/v3 (~120 segundos). Se a sua suíte cobre os dois tipos, use timeouts diferentes para cada um em vez de um valor único.
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
- Como resolver reCAPTCHA v2 pela API
- Como resolver o Cloudflare Turnstile pela API
- Como resolver GeeTest v3 pela API
Teste o ciclo de vida do token CAPTCHA no seu próprio ambiente com a CaptchaAI.
