Node.js Puppeteer + CaptchaAI para QA avançado

Testar um cadastro protegido por Cloudflare Turnstile ou reCAPTCHA no Puppeteer sem usar dados de clientes reais exige três coisas: uma página de staging isolada, uma sitekey só para QA e um jeito de entregar o token exatamente como o formulário espera. Este guia mostra esse padrão passo a passo, com um exemplo de envio de tarefa à API da CaptchaAI que você adapta para Node.js, Python ou qualquer runner de testes que sua equipe já usa.

Por que isolar os testes de CAPTCHA em ambiente staging

Este guia se limita a ambientes próprios, QA, staging ou pré-produção com autorização explícita — sem orientação para automatizar serviços de terceiros, compras reais, filas públicas ou controles de acesso fora do seu ambiente. Os exemplos usam páginas internas, dados fictícios e um endpoint de verificação controlado pela sua equipe.

O motivo do isolamento é simples: um teste do Puppeteer que resolve o CAPTCHA em staging e injeta o token de volta no formulário precisa reproduzir o fluxo técnico real sem gerar efeitos colaterais para usuários, clientes ou parceiros. Se a sua equipe trabalha sob a LGPD, vale considerar isso já no desenho do teste — mesmo com dados fictícios, mantenha os logs de QA separados dos logs de produção e defina por quanto tempo eles ficam retidos.

Arquitetura do ambiente de QA

Crie uma página interna com sitekey de QA, um usuário fictício, um payload previsível e um endpoint de verificação separado de produção. O Puppeteer — ou o executor de testes que a sua equipe usa — abre essa página, identifica o desafio, envia a tarefa para a CaptchaAI e injeta o token de volta antes de submeter o formulário, exatamente como aconteceria em produção, só que contra dados e endpoints que você controla de ponta a ponta.

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 os resultados em uma tabela de testes — nunca na mesma tabela usada por contas reais.

Envie a tarefa CaptchaAI a partir do runner de teste

O runner — seja um teste Puppeteer em Node.js, um script Python ou um step de CI — só precisa de duas chamadas: uma para enviar a tarefa com a sitekey de QA e a URL de staging, outra para consultar o resultado até o token ficar pronto. O exemplo abaixo usa Python para deixar a lógica de envio e polling explícita; a mesma sequência de chamadas ao in.php e ao res.php funciona igual dentro de um hook beforeEach do Puppeteer ou de qualquer setup do seu conjunto de testes end-to-end.

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

Registre o task_id assim que a tarefa é criada: ele é a chave que conecta a execução do Puppeteer ao ciclo de vida da tarefa dentro da CaptchaAI, útil na hora de investigar uma falha mais tarde.

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 do CAPTCHA e devolve só um resultado de teste — sucesso, falha ou motivo do erro — sem acionar nenhum fluxo de produção.

Logging e rastreabilidade entre Puppeteer e CaptchaAI

Registre sitekey, URL da página, tipo de CAPTCHA, tempo de envio, tempo de resposta, status retornado pelo backend e o identificador do caso de QA. Se o teste roda em CI, inclua também o ID da execução do pipeline: isso ajuda a cruzar um teste que falhou no Puppeteer com a tarefa correspondente do lado da CaptchaAI, sem precisar expor nenhum dado sensível nos logs.

Erros comuns e como corrigir

Fora desses casos, confirme o relógio do runner, o domínio de staging permitido e o user-agent do navegador do Puppeteer. Faça retentativas com backoff apenas dentro da suíte de QA.

Checklist antes de publicar a mudança

Antes de publicar a mudança testada, confirme que:

• A documentação aponta para o ambiente próprio, não para produção.
• Os exemplos usam dados fictícios e endpoints de teste.
• Nenhum endpoint de produção é acionado pelo teste.
• Os logs têm correlação suficiente para auditoria, como descrito na seção anterior.
• A página de staging tem domínio autorizado, sitekey esperada, configuração de backend separada e uma política clara de expiração dos dados de teste.

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 usar exatamente o Puppeteer, ou o padrão funciona com outras ferramentas?

O padrão funciona com qualquer executor de teste — Puppeteer, Playwright, Cypress ou um script Python como o do exemplo acima. O que importa é que o runner chame o mesmo par de endpoints (in.php para enviar, res.php para consultar) e injete o token no formulário antes do envio.

Quais tipos de CAPTCHA posso validar nesse ambiente de QA?

A CaptchaAI resolve reCAPTCHA v2/v3, Cloudflare Turnstile, GeeTest v3, CAPTCHAs de imagem e de grade, entre outros tipos com suporte geral. hCaptcha e FunCaptcha ainda não são suportados — se a página de staging usar algum desses, o teste não vai gerar token.

Esse fluxo de teste pode rodar dentro de um pipeline de CI/CD?

Sim. Guarde a chave de API em uma variável de ambiente do runner, mantenha a sitekey de QA fixa e restrinja o pipeline para aceitar apenas o domínio de staging autorizado. Evite apontar esses testes para produção, mesmo por engano.

Esses testes têm algum risco para usuários reais?

Não, desde que fiquem restritos ao escopo descrito aqui: sitekey de QA, dados fictícios, página de staging e endpoint de verificação separado de produção. Nunca aponte esse fluxo para um formulário de produção ou para contas de clientes reais.

Guias relacionados

• Início rápido da CaptchaAI
• Testes de QA autorizados para CAPTCHA
• Como testar endpoints de CAPTCHA em formulários próprios
• Depurar quando o navegador falha mas a API funciona
• Como resolver reCAPTCHA v2 com a API
• Como resolver o Cloudflare Turnstile com a API
• Como resolver o GeeTest v3 com a API

Valide o fluxo de CAPTCHA do seu ambiente de staging com a CaptchaAI.