Uma suíte de QA que reprova sem explicação em uma execução e passa na seguinte quase sempre esconde a mesma causa: o token chegou ao backend depois de expirar, e nada no relatório mostra isso. A resposta curta é usar o TTL do Redis como relógio observável dos testes. Você grava cada token em uma chave com tempo de vida explícito, mede quanto sobrava dele no momento da verificação e troca o palpite por um número no log.
O fluxo abaixo roda em ambiente de QA próprio, com a CaptchaAI resolvendo o desafio e o Redis registrando o ciclo de vida do token.
Escopo seguro deste guia
Tudo aqui vale apenas para ambientes próprios: QA, staging ou pré-produção com autorização explícita. Os exemplos usam páginas internas, dados fictícios e endpoints de verificação controlados pela sua equipe. Não há orientação para automatizar serviços de terceiros, compras reais ou controles de acesso fora do seu ambiente.
Por que o TTL é o sinal mais útil no QA de CAPTCHA
Um token de reCAPTCHA vive cerca de dois minutos; um de Cloudflare Turnstile, alguns minutos a mais. Em um teste automatizado, esse intervalo é consumido por coisas que não aparecem no relatório: fila do runner, tempo de resolução, latência de rede, retentativa de um passo anterior. Sem medição, o time culpa "o CAPTCHA". Com uma chave de Redis criada quando o token chega e lida na hora da verificação, você sabe se sobravam 90 s ou 4 s.
Na prática, três comandos cobrem a instrumentação: gravar o token com SETEX, ler o tempo restante com TTL e apagar a chave depois do uso. Trabalhe sempre com margem: se o desafio entrega algo em torno de 120 s, registre a chave com valor menor, perto de 80 s, para que a suíte falhe de forma previsível antes do limite do provedor.
Passo 1: monte a página staging e os dados fictícios
Crie uma página interna com sitekey de QA, usuário fictício, payload previsível e endpoint de verificação separado da produção. Use identificadores estáveis como qa_user_001 e qa_case_001 — eles viram parte da chave do Redis e do log, o que facilita correlacionar execuções.
O backend de QA deve aceitar apenas tokens vinculados ao domínio staging e gravar resultados em uma tabela de testes. Assim nenhum caso toca dados reais e a expiração pode ser exercitada à vontade.
Passo 2: envie a tarefa e registre o identificador
Envie a tarefa a partir do runner autorizado e guarde o ID retornado. Esse identificador é a ponte entre o que a CaptchaAI processou e o que a sua suíte observou.
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)})
Assim que a função retorna, grave o token em uma chave do tipo qa:captcha:token:{qa_case_id} com o TTL escolhido e anote o horário da gravação. A partir daí, cada leitura de TTL responde à pergunta que interessa: quanto tempo útil ainda existe?
Passo 3: valide a resposta no backend de QA
Encaminhe o token para um endpoint interno, por exemplo https://staging.example.com/qa-captcha/verify. O backend confere a resposta junto ao provedor do CAPTCHA e devolve apenas um resultado de teste. Antes de enviar, leia o TTL restante e inclua esse valor na requisição ou em um cabeçalho de correlação. Se a verificação falhar com o TTL perto de zero, o diagnóstico já vem pronto.
Passo 4: logging, rastreabilidade e LGPD
Registre sitekey, pageurl, tipo de CAPTCHA, horário de envio, tempo de resolução, TTL restante, status do backend e o identificador do caso de QA. Esses campos explicam regressões sem expor nada sensível.
Vale um cuidado local: mesmo em staging, logs de teste entram no escopo da LGPD no Brasil (e do RGPD em Portugal) se carregarem dados pessoais reais. Mantenha a base de teste com dados fictícios, defina retenção curta para as chaves de diagnóstico e evite copiar registros de produção para o QA.
Cenário prático: runner longe do Redis
Uma equipe com o runner em uma região europeia e o Redis em sa-east-1, em São Paulo, via falhas só no pipeline noturno. O TTL registrado revelou o padrão: de dia sobravam de 60 s a 70 s na verificação; à noite, com mais jobs em paralelo, menos de 10 s. Não era o serviço de resolução — era enfileiramento no runner somado ao RTT entre continentes. A correção foi aproximar o worker do Redis e reduzir a concorrência.
Erros comuns e o que checar primeiro
Se o caso falhar, percorra nesta ordem: sitekey correta, domínio staging autorizado, relógio do runner sincronizado, TTL restante na verificação e diferenças entre o fluxo do navegador e o da API. Chave sem TTL é outro clássico — toda chave de diagnóstico precisa expirar, ou a memória do Redis cresce em silêncio.
Critérios antes de publicar a mudança
Antes de promover o teste, confirme que os exemplos usam dados fictícios, que nenhum endpoint de produção é acionado e que os logs têm correlação para auditoria. A página staging precisa ter domínio autorizado, sitekey esperada, backend separado e política clara de expiração. Trate os números como amostra interna: repita a medição e compare cenários equivalentes.
Perguntas frequentes
Qual TTL devo usar na chave do Redis?
Menos do que a vida útil real do token. Se o desafio entrega algo próximo de 120 s, grave a chave com cerca de 80 s. A diferença é a sua margem: a suíte falha de forma controlada, com log, em vez de receber uma recusa vaga.
O Redis é obrigatório para esse tipo de teste?
Não. Qualquer armazenamento com expiração nativa serve. O Redis é conveniente porque TTL responde em uma chamada e a chave desaparece sozinha, sem acumular tokens de teste.
Posso reaproveitar o mesmo token em vários casos de teste?
Não trate isso como estratégia. O token de verificação é de uso único no fluxo real, e reutilizá-lo mascara justamente o problema que você quer medir. Resolva um desafio por caso de teste.
Posso incluir hCaptcha nesses testes?
Não. O hCaptcha não é suportado pela CaptchaAI. Nos testes descritos aqui, use os tipos disponíveis: reCAPTCHA v2 e v3, Cloudflare Turnstile e Cloudflare Challenge, GeeTest v3 e CAPTCHAs de imagem ou de grade.
Quanto custa manter uma suíte de QA assim rodando?
O custo é por concorrência, não por resolução. O plano BASIC (US$ 15/mês, 5 threads) cobre uma suíte pequena; se o pipeline dispara dezenas de cenários em paralelo, STANDARD (US$ 30/mês, 15 threads) e ADVANCE (US$ 90/mês, 50 threads) são os degraus seguintes.
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
Valide a integração CAPTCHA do seu ambiente próprio com a CaptchaAI.
