Se o formulário de cotação de frete que você mantém tem um CAPTCHA na frente, a suíte de testes precisa de um caminho previsível para atravessá-lo — uma página de staging com sitekey de QA, nunca produção. São três peças: a réplica interna do formulário, uma chamada de API que devolve o token e um endpoint de verificação separado que grava o resultado numa tabela de testes.
O cenário é conhecido: o time de logística pede um teste de regressão, o QA roda a suíte e metade dos casos quebra porque o desafio nunca foi tratado. A saída não é desligar o CAPTCHA do staging — é reproduzi-lo com sitekey de teste e resolvê-lo pela API.
Escopo: ambiente próprio, dados fictícios, nada de terceiros
Tudo aqui vale apenas para ambientes que a sua equipe controla: QA, staging ou pré-produção, com autorização explícita. As páginas são internas, as cargas são fictícias e o endpoint de verificação é seu. Não há nada neste guia sobre automatizar portais de transportadoras, rastreamento público ou controles de acesso fora do seu perímetro.
Um lembrete de conformidade: se a base de testes vier de dados reais de clientes, as obrigações da LGPD acompanham a cópia. Gere cargas sintéticas no seed do banco de staging em vez de mascarar um dump de produção.
Passo 1: reproduzir o formulário de cotação em staging
Crie uma página interna que espelhe o formulário real — origem, destino, peso, dimensões e o widget de CAPTCHA. Use uma sitekey de teste emitida para o domínio de staging; a de produção está amarrada ao domínio público e rejeita o token.
O payload precisa ser previsível: CEP de origem fixo, peso fixo e tabela de preços congelada. Assim, uma diferença no resultado só pode ter vindo do código. Se a cotação depende de um serviço externo de tarifas, mocke essa resposta.
Passo 2: nomear os dados fictícios de forma rastreável
Padronize os identificadores para que qualquer log seja legível seis meses depois. Use qa_user_001, qa_session_001 e qa_case_001, com o número do caso ligado ao cenário. O backend de staging deve aceitar apenas tokens vinculados àquela página e gravar tudo numa tabela de testes isolada.
Grave o identificador do caso QA no próprio registro do token, não apenas na linha de log da aplicação: quando a suíte roda 200 cotações em paralelo, correlacionar por horário é inviável.
Passo 3: enviar a tarefa à API da CaptchaAI
O runner envia a sitekey e a URL de staging, recebe um ID de tarefa e consulta o resultado até o token ficar pronto. Registre o ID primeiro — é ele que liga a linha do seu log à tarefa no painel da CaptchaAI.
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)})
O method acima é o de reCAPTCHA v2, que devolve o token em g-recaptcha-response. Se a réplica usa Cloudflare Turnstile, o campo passa a ser cf-turnstile-response — não misture os dois no mesmo caso: o backend recusa em silêncio e o sintoma chega como "cotação em branco".
A cobrança é por thread simultânea, não por resolução: uma suíte com 5 cenários em paralelo cabe no BASIC (US$ 15/mês, 5 threads); um pipeline noturno com dezenas de casos simultâneos pede ADVANCE (US$ 90/mês, 50 threads).
Passo 4: verificar o token no backend de teste
Com o token em mãos, envie-o ao endpoint interno — algo como https://staging.example.com/qa-captcha/verify — junto com o payload da cotação. Ele valida a resposta junto ao provedor do CAPTCHA e devolve apenas um resultado de teste, sem acionar cobrança ou notificação.
Aqui está a fronteira entre um ambiente de QA saudável e um perigoso: o endpoint de staging precisa de outra configuração, outra chave secreta e outro banco. Se compartilha credenciais com produção, uma suíte com bug grava cotações reais.
Passo 5: registrar o suficiente para depurar sem adivinhar
Cada execução deve deixar sitekey, pageurl, tipo de CAPTCHA, horário de envio, horário do token, tempo de resolução, status do backend e identificador do caso QA. Essa combinação responde quase toda pergunta de regressão. Se o tempo de resolução sobe numa branch, o problema raramente está na API: quase sempre é a suíte segurando threads por um timeout mal configurado.
Quando o teste falha: o que checar primeiro
| Sintoma | Causa provável | Verificação |
|---|---|---|
| Cotação em branco | Envio antes do token | Token primeiro, POST depois |
| Token recusado | Sitekey de produção no staging | Emita sitekey do domínio de teste |
| Falha só no CI | Relógio do container dessincronizado | Compare runner e backend |
| Passa no navegador, falha na API | Campo de resposta trocado | g-recaptcha-response ou cf-turnstile-response |
| Erros em rajada | Threads presas por timeout longo | Reduza o timeout, use backoff |
Faça retentativas com backoff apenas dentro da suíte de QA, e sempre com teto: retentativa infinita transforma um teste quebrado em consumo contínuo de threads.
Critérios para liberar a mudança
Antes de promover o que foi testado, confirme quatro pontos: a documentação aponta para o ambiente próprio, os exemplos usam dados fictícios, nenhum endpoint de produção é acionado e os logs têm correlação para auditoria.
Quando os números variarem entre execuções, trate-os como amostra interna: repita a medição, anote a janela e compare apenas cenários equivalentes. Um tempo medido às 3h com o cluster ocioso não se compara ao mesmo teste no pico.
Perguntas frequentes
Preciso mesmo de CAPTCHA no staging, ou posso desligar?
Desligar cria um ponto cego: sem o widget, o código que trata o token nunca é exercitado e a primeira validação real acontece em produção. Mantenha o CAPTCHA com sitekey de teste.
Qual plano da CaptchaAI atende uma suíte de QA?
Dimensione pela concorrência. BASIC (US$ 15/mês, 5 threads) cobre execuções locais; ADVANCE (US$ 90/mês, 50 threads) atende pipelines noturnos. Como as resoluções por thread são ilimitadas, o que importa é quantos testes rodam ao mesmo tempo.
Que tipo de widget posso usar na página de staging?
hCaptcha e FunCaptcha não são suportados, e o GeeTest v4 aparece apenas como "em breve" — evite os três. Os tipos cobertos incluem reCAPTCHA v2 e v3, Cloudflare Turnstile e Challenge, GeeTest v3 e CAPTCHAs de imagem/OCR, além de CaptchaFox (beta), Friendly Captcha (beta) e Lemin (beta).
Posso usar a mesma chave de API em QA e em produção?
Separe. Chaves distintas deixam o consumo de QA visível no painel e evitam que uma suíte em loop ocupe as threads de produção.
Como esse teste entra no pipeline de CI?
Rode a suíte de CAPTCHA como job próprio, depois dos testes unitários e antes do deploy. Ela depende de rede: isolá-la evita que uma instabilidade externa derrube a build inteira.
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
- Resolver reCAPTCHA v2 com API
- Resolver Cloudflare Turnstile com API
- Resolver GeeTest v3 com API
Monte sua suíte de QA de CAPTCHA em staging e resolva o primeiro desafio de teste em minutos com a CaptchaAI.
