Para descobrir por que um CAPTCHA carrega, trava ou não aparece na sua aplicação, a resposta é reproduzir o fluxo em um ambiente de staging controlado: uma página interna com sitekey de QA, dados fictícios e um endpoint de verificação separado de produção. Com esse cenário isolado, você observa cada etapa — o carregamento do widget, o envio da tarefa e a validação do token — sem afetar usuários reais nem tocar em serviços de terceiros.
Este guia se limita a ambientes próprios: QA, staging ou pré-produção com autorização explícita. Todos os exemplos usam páginas internas, contas de teste e endpoints controlados pela equipe. Não há orientação para automatizar serviços de terceiros, compras reais, filas públicas ou controles de acesso fora do seu ambiente.
Por que o CAPTCHA aparece (ou falha) na sua página de teste
Antes de depurar, vale entender o que faz um widget carregar corretamente no seu próprio staging. Três configurações respondem pela maioria dos problemas:
- sitekey e domínio. A sitekey (chave pública do widget) só renderiza nos domínios cadastrados. Se o staging usa um host que não está na allowlist do painel do provedor, o widget simplesmente não aparece.
- ordem de carregamento do script. Se o script do CAPTCHA é injetado antes do elemento-alvo existir no DOM, o widget fica em branco. É um erro comum em páginas renderizadas por JavaScript.
- endpoint de verificação. O backend precisa validar o token junto ao provedor. Sem essa etapa, o teste "passa" visualmente mas não prova nada — o token nunca foi conferido.
Reproduzir cada uma dessas condições em staging transforma um bug intermitente em algo observável e repetível.
Monte um ambiente de QA isolado
Crie uma página interna com sitekey de QA, usuário fictício, payload previsível e um endpoint de verificação separado de produção. O objetivo é reproduzir o fluxo técnico sem gerar efeitos reais para usuários, clientes ou parceiros. Trate o staging como um laboratório: entradas conhecidas, saídas conhecidas.
Dados fictícios e endpoints internos
Use identificadores previsíveis como qa_user_001, qa_session_001 e qa_case_001. O backend deve aceitar apenas tokens vinculados à página de staging e gravar resultados em uma tabela de testes, nunca na base de produção. Assim, cada execução da suíte fica rastreável por caso e você consegue comparar resultados entre builds.
Envie a tarefa à CaptchaAI a partir do runner de QA
Com a página no ar, dispare a tarefa a partir do runner autorizado e registre o ID retornado para rastreabilidade. A CaptchaAI resolve o desafio e devolve o token, que você encaminha ao seu backend de verificação — exatamente como produção faria, só que em ambiente controlado.
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 consulta de resultado (polling) roda a cada 5 segundos até o status virar 1. Em uma suíte de QA, envolva esse laço em um timeout claro para o teste falhar rápido quando algo estiver errado, em vez de ficar consultando indefinidamente.
Valide o token 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. Essa separação é o que distingue um teste honesto de um falso positivo: renderizar o widget prova pouco; um token verificado no servidor prova que a integração inteira funciona de ponta a ponta.
O que registrar em log para rastreabilidade
Registre sitekey, pageurl, tipo de CAPTCHA, tempo de envio, tempo de resposta, status do backend e identificador do caso de QA. Esses campos ajudam a depurar regressões sem expor dados sensíveis. Ao coletar e armazenar qualquer registro, considere as obrigações da LGPD (ou do RGPD, em Portugal): mantenha apenas dados fictícios de teste e evite guardar informação pessoal real na tabela de QA.
Um bom log responde a três perguntas sem esforço: o widget carregou? o token foi emitido? o backend confirmou? Quando um build quebra, essas colunas apontam a etapa exata da falha.
Diagnóstico: quando o widget não carrega ou o teste falha
Se a execução falhar, isole a causa por camada, do navegador ao backend:
- Widget em branco: confirme a sitekey, o domínio de staging na allowlist e a ordem de carregamento do script.
- Token nunca chega: verifique o timeout do polling, a chave de API e o saldo da conta no painel da CaptchaAI.
- Backend rejeita o token: cheque a expiração do token, o relógio do runner (um clock desalinhado invalida tokens de curta duração) e se o endpoint de verificação está usando o mesmo provedor da página.
- Passa no navegador, falha na API (ou o contrário): compare os dois caminhos com atenção; as diferenças costumam estar em cabeçalhos ou no contexto de sessão.
Faça retentativas com backoff exponencial apenas dentro da suíte de QA, nunca contra endpoints de produção.
Checklist antes de publicar
Antes de promover a mudança testada, 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 de staging deve ter domínio autorizado, sitekey esperada, backend de verificação separado e política clara de expiração do token. Quando o resultado 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
Preciso de um domínio público para testar o carregamento do CAPTCHA?
Não. Basta um domínio de staging cadastrado na allowlist da sua sitekey de QA. O widget renderiza em qualquer host autorizado no painel do provedor, inclusive um subdomínio interno de pré-produção.
O hCaptcha está disponível nos meus testes de QA?
Não. O hCaptcha não é suportado atualmente. Para exercícios de QA, a CaptchaAI resolve reCAPTCHA v2 e v3, Cloudflare Turnstile e Cloudflare Challenge, GeeTest v3 e CAPTCHAs de imagem/OCR — cubra a suíte com os tipos que você realmente usa em produção.
Como diferencio uma falha de carregamento do widget de uma falha de resolução?
Olhe o log por camada. Se o widget nunca renderizou, o problema está na sitekey, no domínio ou no script — a resolução nem chegou a começar. Se o widget carregou mas o backend rejeitou o token, o problema está na verificação ou na expiração.
Qual plano da CaptchaAI faz sentido para uma suíte de QA?
Para testes de integração, o volume é baixo e o BASIC (US$ 15/mês, 5 threads) costuma bastar. A cobrança é por thread concorrente, com resoluções ilimitadas por thread, então você dimensiona pelo paralelismo da suíte, não pela quantidade de execuções.
Guias relacionados seguros
- Início rápido da CaptchaAI
- Testes de QA autorizados de CAPTCHA
- Testes de endpoint de CAPTCHA em formulários próprios
- Depuração quando o navegador falha e a API funciona
- Resolver reCAPTCHA v2 com a API
- Resolver Cloudflare Turnstile com a API
- Resolver GeeTest v3 com a API
Valide a integração CAPTCHA do seu ambiente próprio com a CaptchaAI.
