Como testar o fluxo de CAPTCHA de um formulário sem tocar em produção nem em contas reais? Monte uma página de staging com sitekey de teste, use o Beautiful Soup para conferir se o widget realmente renderizou no HTML e valide o token da CaptchaAI em um endpoint interno, isolado do ambiente real. Este guia percorre esse modelo de QA do início ao fim, sempre com dados fictícios.
Por que isolar o teste de CAPTCHA em staging
Este guia se limita a 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 validação 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.
A vantagem é simples: você valida o comportamento técnico do widget — carregamento, envio do token, resposta do backend — sem gerar efeitos em usuários ou parceiros reais. O Beautiful Soup entra como inspeção: em vez de confiar só na renderização visual, um teste de smoke usa algo como BeautifulSoup(html, "lxml").find(attrs={"data-sitekey": True}) para confirmar, no HTML de staging, que o widget carregou antes do restante do fluxo.
Montando a página de QA com sitekey de teste
Crie uma página interna com sitekey de QA, usuário fictício, payload previsível e endpoint de verificação separado de produção. O objetivo é reproduzir o fluxo técnico — do carregamento do widget ao envio do token — sem depender de dados reais em nenhuma etapa. Se o time mantém uma suíte de regressão visual, registre também um snapshot do HTML: comparar essa marcação ao longo do tempo ajuda a pegar mudanças de layout que quebram a extração de data-sitekey.
Dados fictícios e endpoints isolados de produção
Use identificadores previsíveis como qa_user_001, qa_session_001 e qa_case_001. O backend deve aceitar apenas tokens vinculados ao domínio de staging e gravar os resultados em uma tabela de testes, nunca na de produção. Isso também simplifica a conformidade com a LGPD: como nenhum dado real de usuário passa pelo fluxo, não há informação pessoal a proteger nos logs de QA — basta manter essa separação entre staging e produção em todas as chamadas.
Enviando a tarefa CAPTCHA a partir do runner de QA
Envie a tarefa a partir do runner autorizado e registre o ID retornado para rastreabilidade. O trecho abaixo cria a tarefa na CaptchaAI e aguarda o token antes de seguir para a etapa de validação:
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)})
Note que SITEKEY vem de uma variável de ambiente própria de QA (QA_CAPTCHA_SITEKEY), separada de qualquer chave usada em produção — assim um erro de configuração no runner não arrisca disparar tarefas reais.
Validando 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 de CAPTCHA e retorna apenas um resultado de teste — sucesso, falha ou erro de validação — sem acionar nenhuma rotina de produção. Se a validação falhar de forma consistente, confira primeiro se a sitekey de teste está mesmo vinculada ao domínio de staging configurado no backend; essa é a causa mais comum de falso negativo nesse tipo de suíte.
Registrando logs para rastreabilidade
Registre sitekey, pageurl, tipo de CAPTCHA, tempo de envio, tempo de resposta, status do backend e o identificador do caso QA (qa_case_001) em cada execução. Esses campos ajudam a depurar regressões sem expor dados sensíveis, já que tudo no log é fictício. Rodando a partir de infraestrutura no Brasil, meça o tempo de resposta a partir de uma região próxima, como sa-east-1 da AWS, para não confundir latência de rede com regressão real no fluxo.
Solução de problemas comuns
| Sintoma | Causa provável | Como corrigir |
|---|---|---|
| Token rejeitado no backend de QA | Sitekey de teste não corresponde à configurada no backend | Confirme que a sitekey de staging está vinculada exclusivamente ao domínio de teste |
Beautiful Soup não encontra data-sitekey |
Widget carrega de forma assíncrona, após o HTML inicial | Aumente o tempo de espera antes da inspeção ou consulte o HTML pós-renderização |
| Log não mostra o caso QA correspondente | qa_case_001 não foi propagado até o endpoint de verificação |
Garanta que o identificador do caso percorra toda a cadeia de chamadas |
| Token expira antes da validação | Delay entre aguardar_resultado() e o envio ao backend |
Reduza o intervalo entre a resolução do token e a chamada ao endpoint |
| Resultado diverge entre execução manual e automatizada | Relógio do runner dessincronizado | Sincronize o NTP do runner e repita o teste antes de investigar o backend |
Retentativas com backoff só dentro da própria suíte de QA — nunca contra produção.
Checklist antes de publicar a mudança testada
- A documentação do teste aponta para o ambiente de staging, não para produção.
- Todos os exemplos usam dados fictícios (
qa_user_001e afins), nunca contas reais. - Nenhum endpoint de produção é acionado durante a execução do teste.
- Os logs contêm correlação suficiente (sitekey, caso QA, tempo de resposta) para auditoria posterior.
- A página de staging tem domínio autorizado, sitekey esperada e configuração de backend separada da produção.
- A política de expiração do token está clara e é a mesma testada em produção.
Quando o resultado variar 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 de produção para rodar esse teste?
Não. Use uma sitekey de teste vinculada exclusivamente ao domínio de staging, configurada no backend para aceitar somente tokens desse ambiente.
O Beautiful Soup substitui o navegador nesse fluxo de QA?
Não totalmente. Ele inspeciona o HTML estático da página de staging, cobrindo boa parte da suíte. Se o widget for renderizado via JavaScript dinâmico, complemente com um teste em navegador real.
Como evito misturar dados de teste com dados reais nos logs?
Padronize identificadores previsíveis (qa_user_001, qa_session_001, qa_case_001), grave tudo em uma tabela de testes separada e configure o backend para rejeitar qualquer token que não venha do domínio de staging.
Com que frequência devo repetir esse teste?
A cada deploy que toque no formulário, no domínio de staging ou na integração com a CaptchaAI — e periodicamente mesmo sem mudanças, para detectar regressões silenciosas antes que cheguem à produção.
Esse modelo de QA funciona para Cloudflare Turnstile também, ou só para reCAPTCHA?
Funciona para os dois. O mesmo modelo — sitekey de teste, endpoint isolado, log correlacionado — vale para Turnstile e para os demais tipos suportados pela CaptchaAI; muda apenas o method enviado na chamada à API.
Guias relacionados
- 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
- Como resolver reCAPTCHA v2 com a API
- Como resolver Cloudflare Turnstile com a API
- Como resolver GeeTest v3 com a API
Crie sua conta na CaptchaAI e valide esse fluxo de QA no seu próprio ambiente de staging.
