Alcance seguro: todo lo que sigue aplica a tus propios entornos de QA, staging y preproducción autorizados. Son patrones de prueba, diagnóstico y observabilidad para tu propia integración de CAPTCHA, nunca para sitios de terceros.
Un test de un solo paso se arregla con un reintento. Uno de tres — alta, verificación y checkout de prueba — no: si falla el segundo y el test reinicia desde cero, pierdes el token que ya tenías y acabas depurando tu arnés de pruebas en lugar de tu aplicación.
La respuesta corta es darle identidad a cada etapa: un caso_qa que agrupe la ejecución y un paso_id estable por etapa, de modo que reintentar un paso sea idempotente y CaptchaAI se invoque solo cuando el widget aparece.
El contrato de cada paso: caso_qa, paso_id e idempotencia
En un flujo encadenado el CAPTCHA acumula estado: cookies de sesión, token CSRF, un registro a medias y un token válido solo para una página y por un tiempo limitado.
Trata cada etapa como una función con entrada y salida explícitas: entra el par caso_qa + paso_id, sale un estado persistido que la siguiente etapa pueda leer. Así, reintentar el paso_id 2 no vuelve a ejecutar el 1: si el token de esa página sigue vigente se reutiliza dentro de su TTL, y si caducó se pide otro sin tocar el resto. Ahí está la diferencia entre un reintento barato y una ejecución desde cero.
Cómo encaja CaptchaAI en cada paso
El patrón es idéntico sea cual sea el lenguaje o el framework de pruebas:
- Tu test detecta el widget en una página de tu aplicación (formulario de alta, landing de staging, endpoint de preproducción).
- Envía a CaptchaAI los datos públicos del widget:
sitekey, URL y tipo de CAPTCHA. - CaptchaAI devuelve un token válido para esa página.
- Tu test inyecta el token en el campo correspondiente y envía el formulario.
- Tu backend verifica el token con el proveedor, igual que haría con una persona.
Solo el punto 1 depende de tu aplicación: encapsula los otros cuatro en una función que reutilicen todos los pasos.
Misma configuración de navegador en local, CI y staging
La causa número uno de "en mi máquina sí pasa" es un runner con otro viewport, otro idioma u otro user-agent. Fija esa configuración en un único sitio:
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)
Qué medir en cada paso
Instrumenta el CAPTCHA como cualquier dependencia externa, desglosado por paso_id:
- Tiempo de resolución por intento — desde la solicitud a CaptchaAI hasta la entrega del token.
- Tasa de éxito por endpoint propio — verificaciones correctas sobre el total de intentos.
- Distribución de errores — por código (
ERROR_*, tiempos de espera internos, fallos de red). - Latencia extremo a extremo — render, resolución y respuesta de tu backend.
Conserva logs, capturas y archivos HAR: sin traza, un fallo intermitente en staging es irreproducible.
Un ejemplo cercano: tres pasos, tres pantallas distintas
Un equipo en Madrid o en Bogotá que mantiene un portal de trámites suele tener justo esta forma: un formulario público con reCAPTCHA v2, una pantalla intermedia de verificación y una confirmación final detrás de Cloudflare Turnstile. En el QA de un marketplace regional pasa lo mismo entre el alta de vendedor y el checkout de prueba.
La ventaja práctica es de coste: CaptchaAI factura por thread concurrente, no por resolución, así que una suite nocturna de cien casos tiene un gasto mensual predecible en USD. BASIC ($15/mes, 5 threads) cubre una suite pequeña y STANDARD ($30/mes, 15 threads) permite varias en paralelo. Respeta los términos de servicio y la normativa de protección de datos aplicable (GDPR y LOPDGDD en España, o su equivalente local) cuando tus datos de prueba se parezcan a datos reales.
Diagnóstico rápido
| Síntoma | Acción recomendada |
|---|---|
| El test no detecta el widget | Revisa selectores y esperas en staging |
CaptchaAI devuelve ERROR_NO_SLOT_AVAILABLE |
Reintenta con backoff exponencial |
| El backend rechaza el token | Compara action y sitekey con tu configuración real |
| Pasa en local y falla en CI | Iguala viewport, idioma y user-agent |
| Tiempos muy variables | Revisa la concurrencia y los threads de tu plan |
Preguntas frecuentes
¿Puedo reutilizar el mismo token en dos pasos distintos?
No. Cada token vale para la página y el widget que lo generaron. Dentro de un mismo paso_id sí puedes reutilizarlo mientras siga dentro de su TTL, y eso es justo lo que abarata los reintentos.
¿Qué tipos de CAPTCHA puedo encadenar en mis pruebas?
CaptchaAI resuelve reCAPTCHA v2 y v3 (incluidas invisible y Enterprise), Cloudflare Turnstile y Challenge, GeeTest v3, BLS y los CAPTCHA de imagen, OCR y grid. CaptchaFox, Friendly Captcha y Lemin están en beta. hCaptcha y FunCaptcha (Arkose Labs) no son compatibles; GeeTest v4 figura como próximamente.
¿Cómo evito que un paso intermitente bloquee toda la suite?
Aísla el CAPTCHA en una función con reintentos acotados y backoff exponencial, reintentable a nivel de paso_id. Las métricas por intento dirán si el problema es red, proveedor o configuración.
¿Necesito una API key distinta para QA y para producción?
Sí: separar claves te permite atribuir consumo, comparar entornos y cortar el tráfico de pruebas sin tocar producción.
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 sí funciona
- Resolver reCAPTCHA v2 con la API
- Resolver Cloudflare Turnstile con la API
Valida tus integraciones de CAPTCHA en entornos propios con CaptchaAI.
