Um fluxo com várias etapas — login, preenchimento, confirmação — costuma esbarrar em CAPTCHA mais de uma vez antes de chegar ao fim. Testar esse caminho inteiro sem tocar em produção exige uma página de QA própria, dados fictícios e um endpoint de verificação isolado, não um script que reaproveita credenciais reais. Este guia mostra como montar esse ambiente com a CaptchaAI, do envio da tarefa ao checklist de publicação.
Onde este guia se aplica
Este guia vale para ambientes próprios, 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 verificação controlados por vocês — nada aqui orienta automatizar serviços de terceiros, compras reais, filas públicas ou controles de acesso fora do seu ambiente. O foco é reproduzir o fluxo interno etapa por etapa, com dados fictícios e contas de teste do início ao fim.
Monte a página de teste com sitekey própria
Crie uma página interna com uma sitekey de QA, um usuário fictício, um payload previsível e um endpoint de verificação separado do de produção. O objetivo é reproduzir o comportamento técnico — login, ação intermediária, confirmação — sem gerar efeito real para usuários, clientes ou parceiros. Cada etapa que hoje exibe um desafio CAPTCHA em produção precisa de uma versão equivalente na página de teste, sempre com a mesma sitekey de QA.
Padronize identificadores fictícios em cada etapa
Use identificadores como qa_user_001, qa_session_001 e qa_case_001 em toda execução — eles deixam claro, em qualquer log ou painel, que a linha é de teste. O backend deve aceitar apenas tokens vinculados ao domínio de staging autorizado e gravar o resultado em uma tabela de testes, nunca na tabela de produção.
Envie a tarefa CAPTCHA a partir do runner de QA
Dispare a tarefa a partir do runner autorizado e registre o ID retornado para rastrear cada execução depois:
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)})
Para suítes com poucas etapas simultâneas, o plano BASIC (US$ 15/mês, 5 threads) já é suficiente. Suítes maiores, com dezenas de execuções em paralelo cobrindo várias etapas ao mesmo tempo, costumam usar ADVANCE (US$ 90/mês, 50 threads) ou um plano acima — a cobrança é sempre por thread, nunca por CAPTCHA resolvido.
Valide o token no endpoint de teste
Depois de receber o token, envie-o para um endpoint interno como https://staging.example.com/qa-captcha/verify. O backend confirma a resposta junto ao provedor do CAPTCHA e devolve só um resultado de teste — sucesso, falha ou etapa pendente — sem acionar nenhuma rotina de produção.
Registre logs para rastrear regressões
Grave sitekey, pageurl, tipo de CAPTCHA, tempo de envio, tempo de resposta, status do backend e o identificador do caso de QA em cada etapa do fluxo. Com esses campos dá para comparar execuções, encontrar em qual etapa uma regressão começou e depurar sem risco de expor dado sensível — porque não existe dado sensível: é tudo fictício.
Resolva problemas comuns no fluxo
Se uma etapa falhar, confira nesta ordem: a sitekey continua a mesma, o domínio de staging está na lista autorizada, o token não expirou, o relógio do runner está sincronizado e o comportamento no navegador bate com o da API. Faça retentativa com backoff exponencial, mas só dentro da suíte de QA — nunca contra o ambiente de produção.
Exemplo: checkout em várias etapas de um e-commerce
Um cenário comum em equipes de e-commerce no Brasil é replicar o checkout inteiro em staging: login, endereço de entrega, confirmação de pagamento fictício e tela de sucesso, com CAPTCHA em pelo menos duas dessas etapas. Rodar essa suíte a partir de uma região próxima, como sa-east-1 na AWS, reduz a variação de latência que apareceria comparando execuções feitas em outro continente. E como os logs de QA guardam sessão, IP e comportamento do usuário fictício, vale registrar no runbook da equipe que esses dados seguem a política de retenção da LGPD mesmo sendo sintéticos — é mais fácil manter esse hábito desde o primeiro teste do que corrigir depois.
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, 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 precisa ter domínio autorizado, a sitekey esperada, configuração de backend separada e uma política clara de expiração. 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 só cenários equivalentes.
Perguntas frequentes
Preciso replicar login real para testar um fluxo com CAPTCHA em várias etapas?
Não. Use uma página de QA com sitekey própria, usuário fictício e endpoint de verificação isolado — o objetivo é reproduzir o comportamento técnico, não autenticar contas reais.
Quantas threads preciso para paralelizar os testes?
Depende do tamanho da suíte. BASIC (US$ 15/mês, 5 threads) cobre suítes pequenas com poucas etapas simultâneas; suítes maiores costumam usar ADVANCE (US$ 90/mês, 50 threads) ou um plano superior, sempre por thread, não por CAPTCHA resolvido.
Quais tipos de CAPTCHA esse fluxo de QA cobre?
Na prática, reCAPTCHA v2, Cloudflare Turnstile e GeeTest v3 — os tipos mais comuns em fluxos de login e checkout. O hCaptcha ainda não é suportado pela CaptchaAI, então não inclua esse tipo na suíte.
Como evito que dado de teste vaze para o ambiente de produção?
Isole o endpoint de verificação, use identificadores como qa_user_001 em toda execução e grave os resultados em uma tabela de testes separada. O backend deve rejeitar qualquer token que não venha do domínio de staging autorizado.
Preciso mudar código de produção para rodar esses testes?
Não deveria. O runner de QA fala com sua própria página e seu próprio endpoint de verificação; o código de produção só entra em cena depois que o fluxo passa no teste.
Guias relacionados seguros
- Guia de início rápido da CaptchaAI
- Testes de CAPTCHA em QA autorizado
- Testes de endpoint CAPTCHA em formulários próprios
- Depurar quando o navegador falha e a API funciona
- Como resolver reCAPTCHA v2 pela API
- Como resolver Cloudflare Turnstile pela API
- Como resolver GeeTest v3 pela API
Valide o fluxo com CAPTCHA do seu ambiente próprio com a CaptchaAI.
