Use Cases

Como reduzir falhas CAPTCHA em testes internos autorizados

reCAPTCHA v2
Por Equipe CaptchaAI Brasil
Publicado em Jul 09, 2026
Como reduzir falhas CAPTCHA em testes internos autorizados
Imagem em destaque indisponível

Quando um teste de QA falha no CAPTCHA, o problema quase nunca é o solucionador: é o ambiente. Sitekey de produção reutilizada em staging, token expirado entre a resolução e o envio, backend de verificação compartilhado com o ambiente real — esses três detalhes respondem pela maior parte dos vermelhos intermitentes do pipeline.

A saída não é tirar o CAPTCHA do caminho do teste, e sim montar um ambiente próprio em que o desafio seja reproduzível: página interna, dados fictícios, endpoint de verificação separado e logs que reconstruam cada execução. Com essa base, a API da CaptchaAI resolve o desafio de forma previsível e a suíte para de oscilar.

Escopo: apenas ambiente próprio e autorizado

Este guia se aplica a ambientes próprios — QA, staging ou pré-produção — com autorização explícita da equipe responsável. Os exemplos usam páginas internas, contas de teste e endpoints de validação sob seu controle, nunca serviços de terceiros, compras reais, filas públicas ou controles de acesso fora do seu ambiente.

No Brasil e em Portugal, registrar payloads de teste com dados reais de clientes aciona obrigações de LGPD (RGPD em Portugal). Usar dados fictícios desde o primeiro caso de teste evita esse problema por construção e mantém os logs livres de informação sensível.

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

O ambiente de teste precisa reproduzir o fluxo técnico sem efeito real para usuários, clientes ou parceiros. São quatro peças:

  • Sitekey de QA própria, registrada para o domínio de staging e nunca compartilhada com produção.
  • Página interna com o widget no mesmo ponto do formulário em que ele aparece no ambiente real.
  • Payload previsível, com campos fixos, para que a única diferença entre duas execuções seja o CAPTCHA.
  • Endpoint de verificação separado, que grava o resultado em uma tabela de testes e não toca em produção.

Use identificadores fáceis de filtrar nos logs: qa_user_001, qa_session_001, qa_case_001. O backend de staging deve aceitar apenas tokens vinculados àquela página — assim, um token antigo falha em vez de gerar um falso positivo.

Resolva o desafio a partir do runner de QA

Com o ambiente pronto, o runner autorizado envia a tarefa para a API e guarda o ID retornado — é ele que liga a execução ao caso de teste quando alguém precisar entender por que a suíte ficou vermelha.

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)})

A chave de API fica em variável de ambiente, nunca no repositório da suíte. O intervalo de 5 s entre consultas basta: o reCAPTCHA v2 é resolvido em menos de 60 s, e consultar com mais frequência só aumenta as requisições sem antecipar a resposta.

Envie o token ao endpoint interno de verificação

Recebido o token, encaminhe-o para um endpoint interno como https://staging.example.com/qa-captcha/verify, que valida a resposta junto ao provedor do CAPTCHA e devolve apenas um resultado de teste, sem gravar nada em produção.

Envie imediatamente após a resolução. O token do reCAPTCHA v2 tem validade curta, e a falha mais comum aqui é a suíte parar entre resolver e enviar — um sleep esquecido, um setup lento, uma fixture no meio do caminho. Passando de dois minutos, resolva de novo em vez de reaproveitar o token.

Registre o suficiente para depurar, sem virar auditoria

Cada execução deve gravar sitekey, pageurl, tipo de CAPTCHA, horário de envio, tempo de resolução, status do backend e o identificador do caso de QA. Com esses campos você responde à pergunta que sempre aparece depois de uma regressão: o CAPTCHA demorou, o token expirou ou o backend rejeitou?

Mantenha os logs sem dados pessoais e com retenção curta: o objetivo é correlacionar execuções, não guardar sessões.

Quando o teste falha: o que verificar, nesta ordem

Sintoma Verifique primeiro
O token nunca chega Chave de API, saldo da conta, googlekey correta
O token chega e o backend rejeita Domínio de staging autorizado para aquela sitekey
Falha intermitente Tempo entre resolução e envio; relógio do runner
Funciona na API e falha no navegador Campo g-recaptcha-response preenchido no elemento certo

Retentativas com backoff exponencial resolvem instabilidade de rede, mas só dentro da suíte de QA e sempre com teto, para que um erro de configuração não vire laço infinito consumindo threads.

Dimensione as threads pela concorrência da suíte

Os planos da CaptchaAI são cobrados por thread simultânea, com resoluções ilimitadas no mês. Em QA, o custo depende de quantos testes rodam em paralelo, não de quantas vezes a suíte executa.

Uma suíte de regressão com poucos cenários de CAPTCHA cabe no BASIC (US$ 15/mês, 5 threads). Um pipeline noturno que dispara dezenas de casos em paralelo tende a pedir o STANDARD (US$ 30/mês, 15 threads) ou o ADVANCE (US$ 90/mês, 50 threads). Meça a concorrência real do seu CI antes de escolher — ela costuma ser menor do que a estimativa inicial.

Critérios antes de publicar a mudança

Antes de promover o teste para o pipeline principal, confirme que os exemplos usam dados fictícios, que nenhum endpoint de produção é acionado e que os logs trazem correlação suficiente. 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 tempos variarem entre execuções, trate os números como amostra interna: repita a medição e compare apenas cenários equivalentes.

Perguntas frequentes

Preciso de uma sitekey diferente para o ambiente de teste?

Sim. Reutilizar a sitekey de produção em staging é a origem mais comum de falha silenciosa, porque o domínio não corresponde ao registro. Registre uma sitekey própria para staging e mantenha as duas separadas.

Por quanto tempo o token continua válido depois de resolvido?

Pouco — trate a validade como algo em torno de dois minutos. Envie o token ao endpoint de verificação logo após recebê-lo, sem passos lentos entre resolução e envio.

Quais tipos de CAPTCHA posso usar nos meus testes?

reCAPTCHA v2 e v3, Cloudflare Turnstile e Cloudflare Challenge, GeeTest v3 e CAPTCHAs de imagem, grade e BLS, além de CaptchaFox (beta), Friendly Captcha (beta) e Lemin (beta). O hCaptcha e o FunCaptcha não têm suporte; o GeeTest v4 está anunciado como em breve.

Quantas threads a suíte de QA consome?

Uma thread por CAPTCHA em resolução simultânea. Se o CI roda cinco cenários com CAPTCHA em paralelo, cinco threads bastam; as execuções seguintes reutilizam as threads liberadas.

Dá para testar o backend sem abrir um navegador?

Dá, e é mais rápido. Resolva o desafio pela API e envie a requisição direto ao endpoint interno, com token válido, inválido e ausente, para ver como o backend trata cada caso.

Guias relacionados

Evite que o CAPTCHA derrube sua suíte: crie sua chave de API na CaptchaAI e valide o fluxo no seu ambiente de staging.

Os comentários estão desativados para este artigo.