Gestión de user-agent en QA propia con CaptchaAI

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

Si un test pasa en tu máquina pero falla en CI, el user-agent suele ser el sospechoso silencioso. Los sistemas de detección de reCAPTCHA y Cloudflare Turnstile leen esa cadena: si es antigua o cambia dentro de una sesión, el CAPTCHA se endurece o la sesión se invalida y tu test falla de forma intermitente. Mantenerla coherente entre tus entornos hace reproducibles tus pruebas. No es una técnica de evasión: el objetivo es que staging, CI y local vean el mismo navegador.

Por qué el user-agent condiciona tus pruebas de CAPTCHA

Mantén una lista corta de user-agents reales

• Usa solo cadenas de Chrome y Firefox recientes en Windows, macOS y Linux.
• No inventes cadenas: un user-agent con una versión de Chrome inexistente es más fácil de detectar que el propio por defecto.
• Revisa la lista cada uno o dos meses, cuando salgan nuevas versiones de navegador.

Asocia cada caso de prueba a un user-agent

Mapea cada caso de QA a un user-agent concreto para saber qué navegador simulabas cuando un test falle:

• "Solicitante de escritorio": Chrome reciente en Windows.
• "Usuario de macOS": Firefox reciente en macOS.
• Cada caso fija su cadena en lugar de dejarla al azar.

Usa la misma configuración de navegador en todos tus 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)

Aplica esta configuración en local, staging y CI. Mantener viewport, idioma y user-agent idénticos en los runners reduce la varianza y evita que un test funcione en local y falle en el runner.

Cómo encaja CaptchaAI en tu pipeline

1. Tu test detecta el widget de CAPTCHA en tu propia aplicación (formulario de QA, landing de staging).
2. 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. 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.

Un ejemplo cercano

Envía a CaptchaAI el mismo user-agent que usa tu navegador de pruebas; una cadena distinta introduce una incoherencia que no existe en producción. Por ejemplo, si tu equipo mantiene el portal de reserva de citas de tu propia institución, fijas un user-agent de Chrome en Windows y dejas que CaptchaAI resuelva su CAPTCHA con esa misma cadena en staging. Si el test falla, la configuración versionada te dice si cambió el navegador simulado, el sitekey o el umbral. Este flujo se aplica solo a integraciones que tú controlas.

Métricas y observabilidad

• 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 de intentos.
• Distribución de errores — agrupados por código (ERROR_*, timeouts internos, fallos de red).
• Latencia extremo a extremo — render, resolución del CAPTCHA y respuesta de tu backend.
• Trazas conservadas (logs, capturas, HAR) — para reproducir incidentes intermitentes.

Buenas prácticas en tu entorno de QA

• Prueba siempre sobre tu propia aplicación o entornos explícitamente autorizados.
• Mantén una API key de CaptchaAI separada para QA, aparte de la de producción.
• Define timeouts y reintentos con backoff exponencial para no acumular trabajos pendientes.
• Versiona tus snapshots de configuración (sitekey, action, umbrales) junto al código de los tests.
• Revisa el changelog de tu proveedor para anticipar cambios en tu integración.

Preguntas frecuentes

¿Qué tipos de CAPTCHA cubre CaptchaAI en mi QA?

CaptchaAI resuelve reCAPTCHA v2 y v3, Cloudflare Turnstile y Cloudflare Challenge, GeeTest v3, imágenes con OCR, grid-image y BLS. CaptchaFox (beta), Friendly Captcha (beta) y Lemin (beta) están en fase beta. No resuelve hCaptcha ni FunCaptcha (Arkose Labs), y GeeTest v4 figura como próximamente en la documentación oficial.

¿Necesito una API key distinta para mi QA?

Sí, es lo recomendable. Una clave separada mantiene tus métricas de prueba aisladas de las de producción y te deja ajustar timeouts y concurrencia sin afectar a usuarios reales.

¿Cambiar el user-agent es una forma de evadir protecciones?

No, en este contexto no. Se usa para reproducir navegadores reales dentro de tu propia QA y validar la UX que verá un usuario legítimo, no para actuar sobre sitios que no controlas.

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 CAPTCHA en entornos propios con CaptchaAI.