Alcance seguro: esta guía cubre únicamente tus propios entornos de QA, staging y preproducción autorizados. Describe diagnóstico, pruebas y observabilidad de tu propia integración CAPTCHA — nunca sitios de terceros ni flujos que no controlas.
Si tu suite pasa en modo gráfico y falla en modo headless, empieza por descartar lo obvio: casi nunca es "detección de bots", sino renderizado, viewport o tiempos. Esta guía te da un orden de diagnóstico para tu QA y muestra dónde encaja CaptchaAI al resolver el CAPTCHA real.
Por qué el modo headless dispara más CAPTCHA
Un navegador headless expone señales distintas a las de un Chrome con ventana: viewport por defecto más pequeño, sin renderizado real y variaciones en el user-agent. Los anti-bot que protegen tu formulario (reCAPTCHA, Turnstile) pueden bajar la puntuación y mostrar el desafío en CI aunque en local nunca aparezca. El objetivo no es esconder el navegador, sino resolver el CAPTCHA y verificar el resultado como un usuario real.
Reproduce el fallo: headless vs modo gráfico
Reproduce el mismo caso caso_qa en los dos modos contra tu staging propio y registra tiempos y resultados. Si el CAPTCHA solo aparece en headless, el problema está en las diferencias entre entornos, no en tu lógica. Es el paso que más tiempo ahorra: convierte un "falla a veces" en una hipótesis concreta.
Causas frecuentes y cómo verificarlas
La mayoría de las diferencias se reducen a tres factores; compruébalos en este orden:
| Causa | Cómo verificarla |
|---|---|
| Viewport pequeño | Forzar 1280x800 en config |
| Falta de fuentes | Instalar fuentes en la imagen CI |
| Esperas insuficientes | Esperar a networkidle |
Un viewport de 800x600 heredado del arranque, fuentes ausentes o una espera corta bastan para que un widget no cargue a tiempo. Si el fallo persiste, esta tabla mapea cada síntoma a una acción:
| Síntoma | Acción recomendada |
|---|---|
| El test no detecta el widget | Revisa selectores y tiempos en tu entorno staging |
CaptchaAI devuelve ERROR_NO_SLOT_AVAILABLE |
Reintenta con backoff en tu pipeline interna |
| La validación backend rechaza el token | Compara action/sitekey con tu configuración real |
| El test funciona en local pero falla en CI | Iguala viewport, idioma y user-agent en ambos entornos |
| Tiempos de resolución muy variables | Revisa concurrencia y límites de tu API key de CaptchaAI |
Unifica la configuración del navegador
Usa la misma configuración de navegador en local, CI y staging para evitar el clásico "en mi máquina funciona" que solo se reproduce en el runner. Mantén viewport, idioma y user-agent idénticos:
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)
Un equipo de QA en Madrid o Ciudad de México que corre su suite en GitHub Actions con --lang=es-ES reduce la varianza: el mismo caso arroja siempre el mismo desafío.
Cómo encaja CaptchaAI en tu pipeline
Cuando el flujo de QA depende de superar un CAPTCHA legítimo de tu aplicación, el patrón es el mismo en cualquier lenguaje o framework:
- Tu test detecta el widget de CAPTCHA en tu propia página (formulario de QA, landing de staging, endpoint de preproducción).
- Tu test envía a CaptchaAI los datos públicos del widget (
sitekey, URL de la página, tipo de CAPTCHA). - CaptchaAI devuelve un token válido para esa página.
- Tu test inyecta ese token en el campo correspondiente y envía el formulario.
- Tu backend verifica el token con el proveedor, exactamente igual que con un usuario real.
Este flujo se aplica solo a integraciones que controlas tú, no a sitios ajenos.
Métricas que conviene registrar
Instrumenta los pasos de CAPTCHA como cualquier otra dependencia externa. Con estas métricas detectas regresiones antes de que lleguen a producción:
| Métrica | Qué mide |
|---|---|
| Tiempo de resolución por intento | Desde la solicitud a CaptchaAI hasta la entrega del token |
| Tasa de éxito por endpoint propio | Verificaciones de tu backend que pasan sobre el total |
| Distribución de errores | Agrupada por código (ERROR_*, timeouts, fallos de red) |
| Latencia de extremo a extremo | Render, resolución del CAPTCHA y respuesta de tu backend |
Conserva trazas (logs, capturas, HAR) para reproducir incidentes intermitentes.
Buenas prácticas en tu entorno de QA
| Práctica | Por qué |
|---|---|
| Prueba solo sobre tu app o entornos autorizados | Mantiene el QA dentro de los términos de servicio |
| API key de CaptchaAI separada para QA | No mezcla métricas ni saldo con producción |
Timeouts y reintentos con backoff exponencial |
Evita acumular trabajos pendientes en caídas |
| Versiona tus snapshots de config (sitekey, action) | Reproduces el estado exacto de cada test |
| Revisa el changelog de tu proveedor | Anticipas cambios que rompan tu integración |
Preguntas frecuentes
¿Por qué mi test headless pasa en local pero falla en CI?
Casi siempre por diferencias de entorno, no por tu código. El runner arranca con otro viewport, sin las fuentes instaladas o con esperas más cortas, y el widget no carga igual. Iguala viewport, idioma y user-agent con la misma función de arranque y el fallo suele desaparecer.
¿Qué tipos de CAPTCHA puedo validar con CaptchaAI en mi QA?
CaptchaAI resuelve reCAPTCHA v2 y v3, Cloudflare Turnstile y Cloudflare Challenge, GeeTest v3, CAPTCHA de imagen/OCR, grid y BLS, además de CaptchaFox (beta), Friendly Captcha (beta) y Lemin (beta). No cubre hCaptcha ni FunCaptcha. Consulta la documentación oficial para los parámetros de cada tipo.
¿Debo cambiar a modo gráfico si el CAPTCHA sigue apareciendo?
No necesariamente. El modo gráfico obliga a levantar un servidor de display (Xvfb en Linux) y complica el pipeline. Resolver el CAPTCHA por API funciona igual en headless que en modo gráfico, así que suele ser más estable.
¿Cómo controlo los errores intermitentes en mi pipeline?
Aísla el paso de 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.
Guías relacionadas seguras
- Inicio rápido de CaptchaAI
- QA autorizado de CAPTCHA
- Probar endpoints de CAPTCHA en formularios propios
- Depurar tests de navegador cuando la API sí funciona
- Resolver reCAPTCHA v2 con la API
- Resolver Cloudflare Turnstile con la API
Valida tus integraciones CAPTCHA en entornos propios con CaptchaAI.
