Resolver CAPTCHA en QA propia con Puppeteer y CaptchaAI

Alcance seguro: esta guía cubre únicamente tus propios entornos de QA, staging y preproducción autorizados. Describe patrones de diagnóstico, pruebas y observabilidad para tu propia integración con CAPTCHA, nunca para sitios de terceros ni para flujos que no controlas.

Cuando un CAPTCHA aparece en mitad de una prueba automatizada de tu propia aplicación, el test se detiene y el pipeline se pone en rojo sin que haya un bug real detrás. La forma limpia de resolverlo es delegar ese único paso a una API externa: Puppeteer extrae los datos públicos del widget, CaptchaAI devuelve el token y tu test lo inyecta para continuar. Esta es la versión base del patrón, pensada para pruebas internas.

Qué necesitas antes de empezar

• Instala Puppeteer con npm install puppeteer.
• Guarda tu clave de CaptchaAI en una variable de entorno, nunca escrita a mano en el código.
• Usa una API key separada para QA, distinta de la de producción, para no mezclar las métricas de tus pruebas con el tráfico real.

Cómo encaja CaptchaAI en tu pipeline de QA

El patrón es siempre el mismo, sea cual sea tu framework de pruebas:

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

Este flujo se aplica solo a integraciones que tú controlas; no sirve para sortear protecciones de sitios ajenos.

Un caso concreto: resolver reCAPTCHA en el staging de una agencia

Imagina un equipo en Madrid que mantiene el checkout de una tienda y corre pruebas E2E cada noche contra su propio staging. Un reCAPTCHA v2 protege el login, así que sin resolverlo la suite se bloquea en el primer paso. Con este patrón, el test detecta el sitekey del .g-recaptcha, pide el token a CaptchaAI, lo inyecta y sigue con el recorrido de compra. El coste es predecible en USD —el plan BASIC ($15/mes, 5 threads) cubre de sobra una suite nocturna—, algo fácil de presupuestar para agencias y freelancers que facturan en monedas volátiles.

Métricas de CAPTCHA que conviene instrumentar

Añade métricas específicas para los pasos de CAPTCHA en tus pipelines. Así detectas regresiones en tu integración antes de que lleguen a producción:

• Tiempo de resolución por intento: desde que envías la solicitud a CaptchaAI hasta que recibes el token.
• Tasa de éxito por endpoint propio: verificaciones de backend que pasan respecto al total de intentos.
• Distribución de errores: agrupados por código (ERROR_*, timeouts internos, fallos de red).
• Latencia extremo a extremo: render de la página, resolución del CAPTCHA y respuesta de tu backend.

Conserva trazas (logs, capturas y HAR) un tiempo razonable para reproducir incidentes cuando un test falle de forma intermitente.

Fija la misma configuración de navegador en todos los entornos

Un test que pasa en local y falla en CI casi siempre esconde una diferencia de configuración del navegador, no un fallo del CAPTCHA. Usa el mismo viewport, idioma y user-agent en todos los entornos:

from selenium import webdriver

def make_driver(headless: bool = True) -> webdriver.Chrome:
    options = webdriver.ChromeOptions()
    if headless:
        options.add_argument('--headless=new')
    options.add_argument('--window-size=1280,800')
    options.add_argument('--lang=es-ES')
    return webdriver.Chrome(options=options)

Igualar estos valores reduce la varianza entre ejecuciones. Versiona los snapshots de configuración (sitekey, action, umbrales) junto al código de los tests.

Buenas prácticas para tu entorno QA

• Prueba siempre sobre tu propia aplicación o sobre entornos explícitamente autorizados.
• No reutilices tokens fuera de su TTL y registra cada caso_qa con su resultado.
• Define timeouts y reintentos razonables (backoff exponencial) para no acumular trabajos pendientes durante una caída.
• Limpia las sesiones al final de cada ejecución para no arrastrar estado entre tests.

Preguntas frecuentes

¿Qué tipos de CAPTCHA puedo resolver con CaptchaAI en mis pruebas?

CaptchaAI resuelve reCAPTCHA v2 y v3, Cloudflare Turnstile y Cloudflare Challenge, GeeTest v3 e imágenes tipo OCR y grid. No resuelve hCaptcha ni FunCaptcha (Arkose Labs), y GeeTest v4 figura como próximamente.

¿Necesito el plugin de stealth de Puppeteer para mi propia QA?

No. En un entorno que tú controlas no hace falta ninguna técnica de anti-detección: basta con la configuración estándar del navegador. El CAPTCHA se resuelve del lado del servidor, así que headless o con ventana da igual para la fiabilidad.

¿Cuánto cuesta añadir CaptchaAI a un pipeline de QA?

Los planes se facturan por thread (cada CAPTCHA en curso), no por resolución. El plan BASIC cuesta $15/mes con 5 threads y resoluciones ilimitadas, suficiente para la mayoría de suites. Si tu QA corre con mucha concurrencia, subes de plan.

¿Cómo evito que un test falle de forma intermitente por el paso de CAPTCHA?

Aísla la resolución del CAPTCHA en una función con reintentos controlados y backoff exponencial, y registra métricas por intento. Así distingues entre fallos de red, timeouts del proveedor y errores de configuración en tu aplicación.

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

Valida tus integraciones de CAPTCHA en entornos propios con CaptchaAI.