Puppeteer + CaptchaAI para pruebas QA en navegadores propios

Alcance seguro: Esta guía aplica únicamente a sus propios entornos de QA, staging y preproducción autorizados. Describe patrones de diagnóstico, pruebas y observabilidad para su propia integración CAPTCHA — no para sitios de terceros ni para flujos no autorizados.

Esta guía explica cómo usar Puppeteer junto con CaptchaAI para validar los widgets CAPTCHA de sus propios formularios en entornos de QA y staging. No cubre automatización de servicios de terceros, evasión ni técnicas de anti-detección.

Alcance seguro

• Solo entornos propios o explícitamente autorizados.
• Pruebas de integración basadas en navegador.
• Validación de widgets CAPTCHA en formularios propios.
• Diagnóstico cuando los tests de navegador fallan pero los tests de API funcionan.
• Smoke tests para reCAPTCHA, Turnstile y GeeTest.
• Usuarios, formularios, checkout y tokens de pago ficticios.
• Endpoints de QA propios y trazabilidad.
• Sin servicios de terceros, sin scraping, sin lenguaje de bypass.

Configuración de Puppeteer para QA

npm install puppeteer

const puppeteer = require('puppeteer');

async function launchQaBrowser() {
  return puppeteer.launch({
    headless: 'new',
    args: ['--no-sandbox'],
  });
}

No utilice indicadores de anti-detección ni parches de sigilo. El objetivo es ejecutar Chrome de forma estándar contra su propio formulario de staging.

Detectar un widget CAPTCHA en una página staging propia

const page = await (await launchQaBrowser()).newPage();
await page.goto('https://staging.example.com/qa-form');

const sitekey = await page.$eval('.g-recaptcha', el => el.dataset.sitekey);
console.log('Sitekey detectado en formulario propio:', sitekey);

Enviar una tarea a CaptchaAI

const fetch = require('node-fetch');

async function solveRecaptcha(sitekey, pageUrl) {
  const submit = await fetch('https://ocr.captchaai.com/in.php', {
    method: 'POST',
    body: new URLSearchParams({
      key: process.env.CAPTCHAAI_KEY,
      method: 'userrecaptcha',
      googlekey: sitekey,
      pageurl: pageUrl,
      json: '1',
    }),
  }).then(r => r.json());
  // luego haga consulta (polling) a res.php hasta obtener el token
  return submit.request;
}

Validar la respuesta contra un endpoint QA propio

El token nunca se inyecta en sitios de terceros. Se envía a su propio endpoint de QA, que verifica el token con la integración real:

await page.evaluate(token => {
  document.getElementById('g-recaptcha-response').value = token;
}, token);

await page.click('#qa-submit');
// El backend de staging valida el token y registra el resultado.

Logging y trazabilidad

Registre caso_qa, sitekey, tiempo_solve, tiempo_validacion y resultado_backend en su pipeline interna. Esto permite reproducir fallos sin necesidad de reejecutar la prueba completa.

Solución de problemas

Guías relacionadas seguras

• Inicio rápido de CaptchaAI
• QA autorizado de CAPTCHA
• Pruebas de endpoints CAPTCHA en formularios propios
• Depurar tests de navegador cuando la API funciona
• Resolver reCAPTCHA v2 con la API
• Resolver Cloudflare Turnstile con la API

Cómo se integra CaptchaAI en su pipeline propio

El patrón de integración con CaptchaAI siempre es el mismo, independientemente del lenguaje o framework de pruebas que use:

1. Su test detecta el widget de CAPTCHA en la página de su propia aplicación (formulario de QA, landing de staging, endpoint de preproducción).
2. Su test envía a CaptchaAI los datos públicos del widget (sitekey, URL de la página, tipo de CAPTCHA).
3. CaptchaAI devuelve un token válido para esa página.
4. Su test inyecta ese token en el campo correspondiente y envía el formulario.
5. Su backend verifica el token con el proveedor de CAPTCHA, exactamente igual que con un usuario real.

Este flujo se aplica únicamente a integraciones que usted controla. No se utiliza para sortear protecciones de sitios de terceros.

Métricas y observabilidad

Incluya métricas específicas para los pasos relacionados con CAPTCHA en sus pipelines de QA. Esto le permite detectar regresiones en su propia integración antes de que lleguen a producción:

• Tiempo de resolución por intento — desde la solicitud a CaptchaAI hasta la entrega del token.
• Tasa de éxito por endpoint propio — cuántas verificaciones backend pasan respecto al total de intentos.
• Distribución de errores — agrupados por código (ERROR_*, timeouts internos, fallos de red).
• Latencia extremo a extremo — incluyendo render de la página, resolución de CAPTCHA y respuesta de su backend.

Conserve trazas (logs, capturas, HAR) durante un período razonable para poder reproducir incidentes en su entorno QA cuando un test falle de forma intermitente.

Buenas prácticas en su entorno QA

• Pruebe siempre sobre su propia aplicación o sobre entornos explícitamente autorizados.
• Mantenga una API key de CaptchaAI separada para QA, distinta de la de producción, para no mezclar métricas.
• Defina timeouts y reintentos razonables (backoff exponencial) para no acumular trabajos pendientes en CaptchaAI durante caídas.
• Versione sus snapshots de configuración (sitekey, action, umbrales) junto al código de los tests.
• Revise periódicamente el changelog de su proveedor de CAPTCHA para anticipar cambios que afecten a su propia integración.

Preguntas frecuentes

¿Esta guía aplica a sitios de terceros?

No. Todo el contenido está pensado para su propia aplicación o para entornos explícitamente autorizados de QA, staging y preproducción. Resolver CAPTCHA en sitios que no controla puede infringir sus términos de servicio.

¿Funciona con todos los tipos de CAPTCHA?

CaptchaAI soporta los principales tipos de CAPTCHA en su pipeline propio: reCAPTCHA v2 / v3, Cloudflare Turnstile, hCaptcha, GeeTest, FunCaptcha, entre otros. Consulte la documentación oficial para la lista completa y los parámetros que necesita cada tipo.

¿Cómo manejo errores intermitentes en mi propio CI?

Aísle el paso de CAPTCHA en una función con reintentos controlados y backoff exponencial. Registre métricas por intento para poder diferenciar entre fallos de red, timeouts del proveedor y errores de configuración en su propia aplicación.

Prueba tus flujos CAPTCHA en navegadores controlados y entornos propios con CaptchaAI.