Playwright + CaptchaAI en QA propia con Python

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

Si automatizas pruebas con Playwright y tu propio formulario protege el envío con un CAPTCHA, no tienes que resolverlo a mano en cada ejecución. Le pasas a CaptchaAI los datos públicos del widget, recibes un token válido por API y tu test lo inyecta como lo haría una persona. Esta guía monta ese flujo en Python, sin técnicas de anti-detección y de forma reproducible entre local, staging y CI.

Qué necesitas antes de empezar

Instala Playwright, el cliente de CaptchaAI y los navegadores que vayas a usar:

pip install playwright captchaai-python && playwright install.

Con eso tienes Chromium, Firefox y WebKit para pruebas multi-navegador.

El flujo de resolución en cinco pasos

El patrón es el mismo sea cual sea el framework que uses: lanzas Chromium, abres tu staging y dejas que el test recorra estos pasos.

1. Tu test detecta el widget de CAPTCHA en una página de tu propia aplicación (formulario de QA, landing de staging o endpoint de preproducción).
2. Envía a CaptchaAI los datos públicos del widget: el sitekey, la URL de la página y el tipo de CAPTCHA.
3. CaptchaAI resuelve el desafío y devuelve un token válido para esa página.
4. Tu test inyecta ese 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.

Este flujo se aplica solo a integraciones que tú controlas, nunca a sitios ajenos.

Mantén una configuración de navegador reproducible

El fallo más frustrante en QA es el test que pasa en local y se cae en CI sin motivo aparente: casi siempre porque el viewport, el idioma o el user-agent cambian entre entornos. Fija esos valores en una función única y reúsala en todos los runners:

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)

Igualar el tamaño de ventana, el idioma y el user-agent reduce la varianza entre ejecuciones. Usa expect(...) para las esperas explícitas en vez de sleep fijos, y registra cada caso_qa con su resultado.

Qué métricas vigilar en tu pipeline

Instrumenta los pasos del CAPTCHA como cualquier dependencia externa, para detectar regresiones antes de producción:

• Tiempo de resolución por intento — desde que envías la tarea a CaptchaAI hasta que recibes el token.
• Tasa de éxito por endpoint propio — cuántas verificaciones de backend pasan respecto al total de intentos.
• Distribución de errores — agrupada 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 además las trazas (logs, capturas, HAR): te permiten reproducir un fallo intermitente.

Buenas prácticas para tu entorno de QA

• Prueba siempre sobre tu propia aplicación o sobre entornos autorizados.
• Mantén una API key de CaptchaAI dedicada a QA, separada de producción, para no mezclar métricas ni saldo. El plan BASIC ($15/mes, 5 threads) basta para arrancar y escalas los threads cuando el volumen lo pida.
• Define timeouts y reintentos con backoff exponencial para no acumular trabajos pendientes si el proveedor se cae.
• Versiona tus snapshots de configuración (sitekey, action, umbrales) junto al código de los tests, y revisa el changelog de tu proveedor de CAPTCHA para anticipar cambios.

Un ejemplo cercano: validar un formulario de cita previa en staging

Imagina el portal de reservas de una clínica o una administración pública —una cita previa en España, un trámite en línea en Latinoamérica— con el formulario protegido por Cloudflare Turnstile. En preproducción, tu suite de Playwright levanta el formulario, deja que CaptchaAI resuelva el Turnstile, inyecta el token y comprueba que el backend acepta la reserva: todo sobre tu propio staging, con datos de prueba y sin tocar producción.

Solución de problemas

Preguntas frecuentes

¿Puedo usar la misma API key de CaptchaAI en QA y en producción?

Mejor no. Con una API key separada para QA, el saldo, las métricas y los límites de concurrencia no se mezclan con el tráfico real.

¿Con qué tipos de CAPTCHA puedo trabajar en mi propio entorno?

Con los que CaptchaAI resuelve de forma general: reCAPTCHA v2 y v3, Cloudflare Turnstile y Challenge, GeeTest v3 e imagen/OCR y grid. CaptchaFox, Friendly Captcha y Lemin están en beta. hCaptcha y FunCaptcha no son compatibles por ahora, así que no cuentes con ellos en tus pruebas.

¿Esta guía sirve para sitios que no controlo?

No. Todo está pensado para tu propia aplicación o para entornos de QA, staging y preproducción autorizados. Resolver el CAPTCHA de un sitio ajeno puede infringir sus términos de servicio.

¿Cómo gestiono los fallos intermitentes en CI?

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

Guías relacionadas seguras

• Inicio rápido de CaptchaAI
• QA de CAPTCHA en pruebas autorizadas
• 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 de CAPTCHA en entornos propios con CaptchaAI.