QA de CAPTCHA para catálogos e varejo próprios

Quando a suíte de regressão do catálogo passa a esbarrar em um desafio de verificação, a saída que se sustenta não é desligar o widget no staging: é reproduzir o fluxo em ambiente próprio. Uma sitekey de QA restrita ao staging, um runner autorizado que envia o desafio à API da CaptchaAI e um endpoint interno que valida o token bastam para o teste voltar a exercitar o mesmo caminho da produção, só que sobre produtos fictícios.

Abaixo, os quatro passos do fluxo, o dimensionamento de threads e o checklist antes de promover a mudança.

As três saídas quando a busca do catálogo passa a exigir verificação

• Desligar o widget no staging. O relatório fica verde, mas o caminho de verificação deixa de ser exercitado e a falha reaparece em produção.
• Fixar um token de teste no código. O backend aceita um valor que nunca veio do provedor, e a asserção perde relação com o comportamento real.
• Recriar o desafio com uma sitekey de QA. O runner obtém um token legítimo e o backend o valida como validaria em produção.

Só a terceira opção mantém a paridade entre staging e produção.

Escopo: ambiente próprio, dados fictícios e autorização registrada

O roteiro vale para ambientes que o seu time controla — QA, staging ou pré-produção, com autorização registrada, endpoints internos e contas de teste.

Passo 1: monte a página de staging que espelha o catálogo

A página de QA precisa ser previsível: o formulário de busca, produtos fictícios e nada além disso.

• Domínio: staging.example.com, autorizado na sitekey.
• Sitekey de QA: separada da produção e restrita ao ambiente de teste.
• Backend: endpoint próprio, sem efeito sobre pedidos ou cobrança.
• Catálogo: SKUs fictícios (sku_qa_0001) com estoque fixo.

Se algum desses itens apontar para produção, o teste vira tráfego real com etiqueta de teste.

Passo 2: padronize os identificadores de cada caso

Identificadores previsíveis transformam uma falha em diagnóstico.

• qa_user_001 — a conta fictícia da execução.
• qa_session_001 — a sessão do cliente HTTP ou do navegador.
• qa_case_001 — o caso da suíte que disparou o desafio.

O backend aceita apenas tokens do staging e grava o resultado em uma tabela de testes, nunca na base de pedidos.

Passo 3: envie o desafio à API a partir do runner autorizado

O runner envia a sitekey e a URL do staging para in.php, guarda o ID da tarefa e consulta res.php até o token voltar. Registre esse ID: é ele que liga o log do runner ao do backend quando algo falha.

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

A chave de API vem de variável de ambiente, nunca do repositório, e o polling roda a cada 5 s. Em suítes grandes, acrescente um limite de tentativas.

Passo 4: valide o token no endpoint de verificação de QA

Com o token em mãos, envie-o ao endpoint interno https://staging.example.com/qa-captcha/verify, que confere a resposta junto ao provedor e devolve só o veredito — aprovado, rejeitado ou expirado — sem tocar em pedidos nem cobrança. Se o caso passa no navegador mas falha pela API, olhe primeiro o widget e o domínio: o roteiro está em quando o navegador falha e a API funciona.

Cenário: catálogo de e-commerce em São Paulo antes da alta temporada

Um time de e-commerce em São Paulo liga a verificação na busca interna semanas antes do pico de tráfego do ano. A suíte roda toda madrugada em um runner na região sa-east-1, com trinta casos sobre SKUs fictícios. Ao apontar os testes para a sitekey de QA em vez de desligar o widget, o time volta a medir o comportamento do catálogo e ganha um caso que ninguém cobria: o do token inválido.

Quantas threads a suíte de QA consome

A cobrança da CaptchaAI é por thread simultânea, com resoluções ilimitadas por thread no mês: uma thread é um desafio em andamento e, ao terminar, aceita o próximo. Cinco casos em paralelo cabem no BASIC (US$ 15/mês, 5 threads); se a suíte dispara a cada pull request, o STANDARD (US$ 30/mês, 15 threads) evita fila entre os jobs.

Logs de QA que ajudam a depurar sem guardar dado pessoal

Nenhum desses campos exige dado de cliente: como os registros nascem de dados fictícios, você evita trazer as obrigações da LGPD para os logs de depuração.

Quando o teste falha: sintomas e onde olhar primeiro

Retentativas com backoff exponencial pertencem à suíte, não ao produto: repetir sem limite mascara a causa.

Checklist antes de promover a mudança

1. O caso aponta para um ambiente próprio e autorizado.
2. Os dados são fictícios e as contas, de teste.
3. Nenhum endpoint de produção é acionado pela execução.
4. O staging usa o domínio autorizado e a sitekey esperada.
5. A chave de API vem do cofre de segredos do CI e não aparece em log.

Perguntas frequentes

Dá para reaproveitar a sitekey de produção nos testes?

Não vale a pena. Use uma sitekey de QA restrita ao domínio de staging: reaproveitar a de produção é a causa mais comum de token rejeitado por domínio inválido.

Quais tipos de CAPTCHA entram nesse fluxo de QA?

reCAPTCHA v2 e v3, Cloudflare Turnstile e Cloudflare Challenge, GeeTest v3, CAPTCHAs de imagem/OCR e desafios de grade, além de CaptchaFox (beta), Friendly Captcha (beta) e Lemin (beta). hCaptcha e FunCaptcha não são suportados, e o GeeTest v4 está anunciado como "em breve".

O token expirou entre a resolução e o POST. Isso é bug do teste?

Normalmente não: é a validade curta do token encontrando uma suíte lenta. Em vez de aumentar o tempo limite às cegas, transforme o cenário em um caso explícito, com asserção sobre a mensagem de expiração.

Como impedir que a chave de API apareça nos logs do CI?

Guarde-a no cofre de segredos do runner e injete-a como variável de ambiente, como no exemplo em Python. Em log, registre apenas o ID da tarefa e o qa_case_id.

Guias relacionados

• Primeira integração com a API da CaptchaAI
• CAPTCHA em testes de QA autorizados
• Como testar endpoints de formulário com CAPTCHA
• 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

Teste o CAPTCHA do catálogo em staging com a CaptchaAI.