Quando um formulário com reCAPTCHA ou Cloudflare Turnstile falha em staging, o motivo raramente aparece no log da aplicação — ele está na aba Network do navegador, no ciclo de vida do widget que o seu script nunca chega a ver. O Chrome DevTools Protocol (CDP) expõe exatamente esse nível: eventos de rede, execução de JavaScript e estado da página, pela mesma conexão WebSocket que ferramentas como Puppeteer já usam por baixo dos panos. Para quem faz QA de integrações CAPTCHA com a CaptchaAI, isso costuma reduzir a horas de log parado para minutos de diagnóstico direto.
Escopo seguro: por que isso importa antes da primeira requisição
Diagnóstico com CDP mexe com requisições reais e pode capturar tokens, sitekeys e payloads inteiros durante a inspeção. Por isso, tudo neste guia vale só para ambiente próprio, QA, staging ou pré-produção, com autorização explícita da sua equipe. Os exemplos usam páginas internas, dados fictícios e endpoints de validação controlados por vocês; nada aqui serve para automatizar serviços de terceiros, compras reais, filas públicas ou controles de acesso fora do seu ambiente.
Diagnóstico de rede com o Chrome DevTools Protocol
O CDP conversa com o Chrome por WebSocket e expõe os mesmos eventos que a aba Network do DevTools mostra na tela — só que de forma programável. Ative o domínio Network para capturar o carregamento do script do CAPTCHA, a resposta do widget e a chamada ao seu endpoint interno. O objetivo não é interceptar nem alterar nada: é entender o ciclo de vida da requisição, o status HTTP retornado e os parâmetros que o seu ambiente de QA está realmente enviando.
Como conferir a sitekey na página de teste
Antes de enviar qualquer tarefa à CaptchaAI, confirme que a página de staging está usando a sitekey certa. Abra https://staging.example.com/captcha-demo, leia o atributo do widget (data-sitekey para reCAPTCHA, a classe cf-turnstile para Turnstile) e compare com a configuração esperada do ambiente. Esse passo sozinho já resolve boa parte dos "falsos bugs": token rejeitado porque a sitekey capturada era a de produção, não a de QA.
Enviando a tarefa para a CaptchaAI a partir do QA
Com a sitekey confirmada no smoke test, envie a tarefa para a CaptchaAI usando a pageurl de staging. O exemplo abaixo faz o envio e consulta o resultado até o token ficar pronto:
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)})
Validando a resposta no backend
Encaminhe o token para o endpoint interno de verificação, registre o status retornado e compare com os logs do provedor do CAPTCHA. Esse cruzamento — resposta da CaptchaAI vs. decisão do seu backend — é o que mostra se a falha está na integração ou no CAPTCHA em si.
Erros comuns no diagnóstico com CDP
| Sintoma no CDP | Causa provável | Como resolver |
|---|---|---|
| Nenhum evento de rede aparece | Domínio de staging ausente ou bloqueado | Confirme o carregamento de https://staging.example.com/captcha-demo |
| Sitekey capturada não bate | Página ainda usa a sitekey antiga ou de produção | Compare data-sitekey/cf-turnstile com a config de QA |
| Token chega vazio no backend | action divergente entre o widget e a chamada à CaptchaAI |
Revise action (reCAPTCHA v3) e a pageurl enviada |
| Backend rejeita o token | Token expirado antes da verificação | Reduza o tempo entre aguardar_resultado e o envio ao backend |
| Endpoint interno não responde | Backend apontando para o ambiente errado | Confirme a URL do endpoint no .env de staging |
Checklist antes de publicar a integração
Confirme os itens abaixo antes de levar a mudança testada para produção:
- A documentação aponta para o ambiente próprio (QA/staging), não para produção.
- Os exemplos e os dados enviados nos testes são fictícios.
- Nenhum endpoint de produção é acionado durante o teste.
- Os logs têm correlação suficiente (task ID, timestamp) para auditoria.
- A página de staging tem domínio autorizado, sitekey esperada e configuração de backend separada da produção.
- Existe uma política clara de expiração para tokens e sessões de teste.
Trate qualquer número de sucesso como amostra interna: repita a medição e compare apenas cenários equivalentes — nunca uma corrida isolada.
Exemplo prático: se o worker de QA roda em sa-east-1 (São Paulo) e o site de teste está hospedado nos EUA, o CDP mostra RTT mais alto só pela distância geográfica — não confunda isso com lentidão da CaptchaAI.
Perguntas frequentes
O que o CDP mostra que o DevTools comum não deixa tão claro?
O painel do Chrome já expõe requisições e o DOM, mas via CDP você automatiza a captura: liga os eventos de rede, lê o ciclo de vida do widget e cruza tudo com o log do backend em um único script, sem repetir o processo a cada teste.
Preciso instalar alguma ferramenta além do Chrome para conectar via CDP?
Não. Basta iniciar o Chrome com --remote-debugging-port e conectar por WebSocket, como no exemplo deste guia. O Puppeteer usa CDP por baixo dos panos, mas conectar direto funciona igual para diagnóstico.
Por que a sitekey que aparece no CDP é diferente da que meu script está usando?
Geralmente é ambiente: a página de staging carrega uma sitekey de teste diferente da de produção, ou o script ainda aponta para a config antiga. Confira data-sitekey (ou a classe cf-turnstile) na página real antes de enviar a tarefa à CaptchaAI.
O CaptchaAI resolve qualquer CAPTCHA que eu encontrar durante o diagnóstico?
Não. A CaptchaAI resolve reCAPTCHA v2/v3, Cloudflare Turnstile, GeeTest v3 e os demais tipos suportados oficialmente — hCaptcha e FunCaptcha não são suportados atualmente. Trate a detecção de um desses dois como bloqueio conhecido, não como bug do script.
Preciso me preocupar com a LGPD ao capturar essas requisições no CDP?
Se a captura fica só no ambiente de QA e não armazena dados pessoais reais de usuários finais, o risco é baixo. Ainda assim, use dados fictícios nos testes e trate qualquer log com requisição/resposta reais como dado sensível, seguindo a LGPD.
Guias relacionados
- Guia de início rápido da CaptchaAI
- Como estruturar testes QA autorizados de CAPTCHA
- Testando o endpoint de CAPTCHA em formulários próprios
- O que fazer quando o navegador falha mas a API funciona
- Como resolver reCAPTCHA v2 pela API
- Como resolver Cloudflare Turnstile pela API
- Como resolver GeeTest v3 pela API
Rode esse diagnóstico no seu próprio ambiente de staging e confirme a integração CAPTCHA com a CaptchaAI antes de ir para produção.
