Alcance seguro: esta guía cubre solo tus entornos autorizados de QA, staging y preproducción, no sitios ajenos.
La respuesta corta: no desactives el CAPTCHA en staging para que la suite pase en verde. Ese atajo deja sin probar justo la mitad del flujo que luego se rompe en producción. Deja el widget puesto, pide un token real por API a CaptchaAI, inyéctalo y comprueba que tu backend lo valida.
El escenario es reconocible: un buscador interno protegido con reCAPTCHA v3 cuyo test lleva meses en skip.
Por qué el CAPTCHA rompe los tests de búsqueda
El widget mete tres dependencias en un test que antes era determinista: un tercero en el camino crítico, tiempos en segundos en vez de milisegundos y un token de un solo uso que no puedes cachear.
Prepara datos ficticios para la página de resultados
Antes de tocar el CAPTCHA, aísla los datos: siembra staging con consultas y resultados sintéticos para que ninguna ejecución toque información de personas reales — copiar datos productivos a entornos de prueba es justo lo que la normativa aplicable (RGPD y LOPDGDD, LFPDPPP en México) te pide evitar. Incluye un caso con cero resultados, uno con paginación y uno con acentos o ñ, donde afloran los fallos de codificación.
Comprueba primero que tu widget esté cubierto
No todos los tipos entran en esta ruta. Confírmalo antes del primer test:
| Tipo del widget | ¿Cubierto? |
|---|---|
| reCAPTCHA v2, v3, Invisible, Enterprise | Sí |
| Turnstile, Cloudflare Challenge, GeeTest v3 | Sí |
| Imagen, OCR, texto, grid-image, BLS CAPTCHA | Sí |
| CaptchaFox, Friendly Captcha, Lemin | Sí, en beta |
| GeeTest v4 | No, próximamente |
| hCaptcha, FunCaptcha (Arkose Labs) | ❌ No compatible (por ahora) |
Si tu formulario usa uno de los dos últimos, planifica ese test por otra vía. Si aún no has llamado a la API, empieza por el inicio rápido y vuelve aquí.
Los cinco pasos de la integración con CaptchaAI
El patrón es el mismo con Pytest, Playwright o el framework que uses:
- Tu test detecta el widget en tu propia página de staging.
- Envía a CaptchaAI los datos públicos del widget:
sitekey, URL y tipo. - CaptchaAI devuelve un token válido para esa página.
- Tu test lo inyecta en el campo correspondiente y envía el formulario.
- Tu backend lo verifica contra el proveedor, igual que con una persona real.
Comprueba la validación en tu backend
El token no es el objetivo: lo es que tu endpoint lo acepte y devuelva la lista correcta de resultados.
- Rechaza una solicitud sin token: el control negativo que casi nadie escribe.
- Acepta el token válido y devuelve los resultados ficticios.
- El
actiony el umbral de score coinciden entre backend y frontend; ese desajuste es el fallo silencioso más frecuente con reCAPTCHA v3.
Homogeneiza la configuración del navegador
La causa número uno de "funciona en mi máquina pero falla en CI" es que el runner levanta otro navegador. Fija viewport, idioma y modo headless en un punto:
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)
Con viewport, idioma y user-agent idénticos en todos los runners, la varianza baja y las ejecuciones se vuelven comparables.
Métricas para no depurar a ciegas
Instrumenta el CAPTCHA como cualquier otra dependencia externa:
- Tiempo de resolución por intento, de la solicitud al token.
- Tasa de éxito por endpoint propio: verificaciones válidas sobre el total.
- Distribución de errores por código (
ERROR_*, timeouts, red). - Latencia extremo a extremo: render, resolución y backend.
Conserva trazas (logs, capturas, HAR) para reproducir intermitencias.
Buenas prácticas que ahorran ciclos
- Prueba solo sobre tu aplicación o entornos autorizados.
- Usa una API key separada para QA: no mezclas métricas ni saldo.
- Define tiempos de espera y reintentos con backoff exponencial en el paso del CAPTCHA.
- Versiona la configuración (sitekey, action, umbrales) junto a los tests.
- Revisa el changelog del proveedor: los cambios de layout rompen selectores.
Un detalle de coste para equipos que facturan en moneda local: CaptchaAI cobra por threads concurrentes, no por resolución, así que la suite no genera factura variable. BASIC ($15/mes, 5 threads) cubre una suite pequeña; con jobs en paralelo, STANDARD ($30/mes, 15 threads) o ADVANCE ($90/mes, 50 threads) dan margen. Precios en USD.
Solución de problemas
| Síntoma | Acción recomendada |
|---|---|
| El test no detecta el widget | Revisa selectores y esperas |
ERROR_NO_SLOT_AVAILABLE |
Reintenta con backoff; revisa tus threads |
| El backend rechaza el token | Compara action y sitekey |
| Falla solo en CI | Iguala viewport, idioma y user-agent |
| Tiempos muy variables | Revisa concurrencia y límites de la API key |
| Resultados vacíos con token válido | Revisa el seed de datos ficticios |
Preguntas frecuentes
¿Puedo desactivar el CAPTCHA en staging y ahorrarme todo esto?
Puedes, pero dejas sin cubrir la verificación del token en el backend, justo donde aparecen los errores de action y de umbral.
¿Cuánto tarda el paso de CAPTCHA dentro de un test?
Se mide en segundos y varía según el widget. Ajusta el tiempo de espera de ese paso por separado, nunca el de toda la suite.
¿Necesito una API key distinta para QA y para producción?
Sí. Separar claves mantiene limpias las métricas y evita que una suite en bucle consuma threads de producción.
¿Sirve esto para páginas de resultados de buscadores públicos?
No. Todo lo descrito aplica a tu aplicación o a entornos con autorización explícita; hacerlo en sitios que no controlas puede infringir sus términos de servicio.
Guías relacionadas
- Empieza con la API en minutos
- QA autorizado de CAPTCHA
- Probar endpoints con CAPTCHA
- Cuando falla el navegador y la API responde
- Resolver reCAPTCHA v2 por API
- Resolver Cloudflare Turnstile por API
Consigue tu API key en CaptchaAI y recupera ese test que llevas meses saltándote.
