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.
Escopo seguro
Use Puppeteer apenas em páginas próprias como https://staging.example.com/qa-form, https://staging.example.com/captcha-demo e https://staging.example.com/checkout-test.
Configuração do Puppeteer para QA
Execute Chrome em modo padrão de teste, com logs, traces e variáveis de ambiente para sitekey de QA. Use usuários fictícios, formulários fictícios e pagamento sandbox.
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/qa-form')
token_qa = aguardar_resultado(task_id)
print({'token_recebido': bool(token_qa)})
Detectar widget CAPTCHA em página staging própria
Aguarde o seletor do widget, leia atributos públicos da página e confirme que a pageurl corresponde ao ambiente esperado.
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/qa-form')
token_qa = aguardar_resultado(task_id)
print({'token_recebido': bool(token_qa)})
Enviar tarefa para CaptchaAI
Envie a tarefa CaptchaAI a partir do runner QA depois de confirmar tipo, sitekey e URL staging.
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/qa-form')
token_qa = aguardar_resultado(task_id)
print({'token_recebido': bool(token_qa)})
Validar resposta contra endpoint QA interno
O backend interno deve validar o token e retornar pass, fail ou retryable_error para a suíte.
Logging e rastreabilidade
Inclua trace id, screenshot de teste, task id, tempo de resposta, status backend e commit da aplicação.
Solução de problemas
Quando testes de navegador falham e API passa, compare timing do widget, renderização do iframe, domínio permitido e action configurada.
Critérios de publicação
Antes de publicar a mudança testada, confirme que a documentação aponta para ambiente próprio, que os exemplos usam dados fictícios, que nenhum endpoint de produção é acionado pelo teste e que os logs contêm correlação suficiente para auditoria. A página staging deve ter domínio autorizado, sitekey esperada, configuração de backend separada e política clara de expiração. Quando o resultado variar, trate os números como amostra interna: repita a medição, anote a janela de execução e compare apenas cenários equivalentes.
Guias relacionados seguros
- 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
Valide a integração CAPTCHA do seu ambiente próprio com a CaptchaAI.
