Selenium + CaptchaAI en QA propia con Python

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 integración CAPTCHA — no para sitios de terceros ni para flujos que no controlas.

¿Tu suite de Selenium se detiene en seco cuando aparece un CAPTCHA en el formulario de staging? La salida no es desactivar la protección ni parchear el navegador: es delegar ese único paso en CaptchaAI y dejar que el test siga. Selenium conduce el navegador, CaptchaAI devuelve el token, y tu backend lo verifica igual que con una persona real. En esta guía montamos ese patrón en Python para validar tus propios flujos.

Piensa en una agencia de Madrid o Ciudad de México que ejecuta cada noche el alta de una plataforma tipo cita previa, y el reCAPTCHA rompe la ejecución en CI. Con la integración correcta, ese paso deja de ser un punto ciego.

Qué necesitas antes de empezar

Instala la librería de automatización y el cliente de resolución, y descarga el driver del navegador.

pip install selenium captchaai-python

Con eso cubres los dos lados: control del navegador y llamada a la API.

El flujo de un vistazo

Antes del código, ten clara la secuencia, la misma para cualquier tipo de CAPTCHA:

1. Tu test abre tu entorno de staging y detecta el widget en tu propia página (formulario de QA, landing de preproducción o endpoint interno).
2. Tu test envía a CaptchaAI los datos públicos del widget: sitekey, URL de la página y tipo de CAPTCHA.
3. CaptchaAI resuelve el desafío en sus propios workers 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 contra el proveedor de CAPTCHA, igual que con un usuario real.

Este flujo se aplica solo a integraciones que tú controlas, no a protecciones de sitios ajenos.

Mantén el navegador idéntico en todos tus entornos

La causa más común de un test que pasa en local y falla en CI no es el CAPTCHA: es un navegador distinto en cada runner. Fija el mismo viewport, idioma y user-agent por defecto en todas partes:

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)

Reutiliza este make_driver en local, staging y CI. Con un navegador idéntico, un fallo apunta a un cambio real y no al entorno.

Buenas prácticas dentro de tu QA

Un par de decisiones al principio te ahorran ruido después:

• Prueba siempre sobre tu propia aplicación o entornos explícitamente autorizados, nunca sobre producción de un tercero.
• Usa una API key de CaptchaAI separada para QA, distinta de la de producción, para no mezclar métricas ni saldo.
• Apóyate en esperas explícitas (WebDriverWait) en vez de sleep fijos, y limpia la sesión al terminar cada caso.
• Define timeouts y reintentos con backoff exponencial, y versiona tus snapshots de configuración (sitekey, action, umbrales) junto al código.

El modelo de threads ayuda a presupuestar: el plan BASIC ($15/mes, 5 threads) cubre de sobra una suite nocturna de QA, y escalas si tu volumen crece. El coste mensual en USD es predecible, cómodo cuando facturas en monedas volátiles.

Qué medir en tu pipeline de QA

Trata el paso de CAPTCHA como otra métrica del test. Instrumentarlo te deja detectar regresiones 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 — verificaciones backend que pasan sobre el total de intentos.
• Distribución de errores — 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 las trazas (logs, capturas, HAR) para reproducir un incidente cuando un test falle de forma intermitente.

Preguntas frecuentes

¿A qué entornos se aplica esta integración?

Solo a tu propia aplicación o a entornos de QA, staging y preproducción explícitamente autorizados. Resolver CAPTCHA en sitios que no controlas puede infringir sus términos de servicio, así que queda fuera del alcance de esta guía.

¿Qué tipos de CAPTCHA puedo validar con este flujo?

CaptchaAI resuelve reCAPTCHA v2 y v3, Cloudflare Turnstile y Cloudflare Challenge, GeeTest v3, y CAPTCHA de imagen/OCR y grid. hCaptcha y FunCaptcha no son compatibles, y GeeTest v4 figura como próximamente. CaptchaFox, Friendly Captcha y Lemin están en beta. Consulta la documentación oficial para los parámetros de cada tipo.

¿Cómo controlo los errores intermitentes en mi CI?

Aísla el paso de CAPTCHA en una función con reintentos controlados y backoff exponencial, y registra métricas por intento. Así distingues un fallo de red de un timeout del proveedor o de un error de configuración.

¿Cuánto añade Selenium frente a llamar solo a la API?

Selenium suma el arranque del navegador y el render, unos segundos por caso. El tiempo de resolución del CAPTCHA es el mismo, porque ocurre en los workers de CaptchaAI. Si tu test no necesita ejecutar JavaScript, una llamada directa a la API es más ligera.

Solución de problemas rápida

Guías relacionadas

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

Valida tus integraciones CAPTCHA en entornos propios con CaptchaAI.