Alcance seguro: esta guía se aplica solo a tus propios entornos de QA, staging y preproducción autorizados. Describe patrones de diagnóstico, prueba y observabilidad para tu propia integración CAPTCHA — nunca para sitios de terceros ni flujos que no controlas.
¿Tu suite de tests de navegador se cae en cuanto aparece un widget CAPTCHA en el formulario de staging? La respuesta práctica es automatizar ese paso: Puppeteer conduce Chrome sobre tu propia página, CaptchaAI resuelve el widget y devuelve un token, y tu backend lo verifica igual que con un usuario real. Así ese reCAPTCHA o ese Turnstile deja de ser el punto donde el pipeline se detiene a mano. Todo ocurre sobre formularios que tú controlas, con Chrome en modo estándar contra tu staging.
Qué cubre (y qué no) esta guía de QA
- Solo entornos propios o explícitamente autorizados.
- Validación de widgets CAPTCHA en formularios propios, basada en navegador.
- Diagnóstico cuando los tests de navegador fallan pero los de API funcionan.
- Smoke tests para reCAPTCHA, Turnstile y GeeTest v3.
- Usuarios, formularios, checkout y tokens de pago ficticios.
- Endpoints de QA propios y trazabilidad, sin servicios de terceros ni scraping.
Cómo encaja CaptchaAI en tu pipeline de QA
El patrón de integración con CaptchaAI es siempre el mismo, sin importar el lenguaje o el framework de pruebas que uses:
- Tu test detecta el widget de CAPTCHA en tu propia página (formulario de QA, landing de staging, endpoint de preproducción).
- Envía a CaptchaAI los datos públicos del widget (
sitekey, URL de la página, tipo de CAPTCHA). - CaptchaAI devuelve un token válido para esa página.
- Tu test inyecta ese token en el campo correspondiente y envía el formulario.
- Tu backend verifica el token con el proveedor, igual que con un usuario real.
Este flujo solo aplica a integraciones que tú controlas; no sirve para sortear protecciones de terceros. Piensa en un equipo de QA en Madrid o Ciudad de México que valida el checkout de su propia tienda antes de cada release: el reCAPTCHA v2 que antes alguien resolvía a mano ahora lo cubre el smoke test, con un costo mensual predecible en USD.
Configuración de Puppeteer para QA
npm install puppeteer
const puppeteer = require('puppeteer');
async function launchQaBrowser() {
return puppeteer.launch({
headless: 'new',
args: ['--no-sandbox'],
});
}
No añadas indicadores de anti-detección ni parches de sigilo: ejecuta Chrome de forma estándar contra tu propio formulario de staging.
Detectar el widget CAPTCHA en tu página de staging
El primer paso es leer el sitekey público del widget, el mismo dato que cualquier navegador ve en el HTML:
const page = await (await launchQaBrowser()).newPage();
await page.goto('https://staging.example.com/qa-form');
const sitekey = await page.$eval('.g-recaptcha', el => el.dataset.sitekey);
console.log('Sitekey detectado en formulario propio:', sitekey);
Enviar la tarea a CaptchaAI
Con el sitekey y la URL de tu página, envía la tarea al endpoint in.php. La respuesta trae un identificador que consultas en res.php hasta recibir el token:
const fetch = require('node-fetch');
async function solveRecaptcha(sitekey, pageUrl) {
const submit = await fetch('https://ocr.captchaai.com/in.php', {
method: 'POST',
body: new URLSearchParams({
key: process.env.CAPTCHAAI_KEY,
method: 'userrecaptcha',
googlekey: sitekey,
pageurl: pageUrl,
json: '1',
}),
}).then(r => r.json());
// luego haga consulta (polling) a res.php hasta obtener el token
return submit.request;
}
Validar la respuesta contra tu propio endpoint de QA
El token nunca se inyecta en sitios de terceros: va a tu propio endpoint de QA, que lo verifica con la integración real:
await page.evaluate(token => {
document.getElementById('g-recaptcha-response').value = token;
}, token);
await page.click('#qa-submit');
// El backend de staging valida el token y registra el resultado.
Logging y trazabilidad
Registra caso_qa, sitekey, tiempo_solve, tiempo_validacion y resultado_backend en tu pipeline interna. Con eso reproduces un fallo sin reejecutar la prueba completa y ves de un vistazo si el problema estuvo en la resolución, en la inyección o en tu backend.
Métricas y observabilidad
Instrumenta métricas específicas para los pasos de CAPTCHA dentro de tus pipelines de QA. Así detectas regresiones en tu propia integración 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 — cuántas verificaciones de backend pasan respecto al total de intentos.
- Distribución de errores — agrupados 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 incidentes cuando un test falle de forma intermitente.
Solución de problemas
| Síntoma | Acción recomendada |
|---|---|
| El test ve el widget pero no el sitekey | Revisa el HTML real de tu staging |
CaptchaAI devuelve ERROR_NO_SLOT_AVAILABLE |
Reintenta con backoff exponencial |
| El backend marca el token como inválido | Compara action y sitekey con la configuración real |
| El test pasa en API pero falla en navegador | Reproduce con datos ficticios y revisa los selectores |
Buenas prácticas en tu entorno de QA
- Prueba siempre sobre tu propia aplicación o sobre entornos explícitamente autorizados.
- Mantén una API key de CaptchaAI separada para QA, distinta de la de producción, para no mezclar métricas.
- Define timeouts y reintentos razonables (backoff exponencial) para no acumular trabajos pendientes durante caídas.
- Versiona tus snapshots de configuración (
sitekey,action, umbrales) junto al código de los tests. - Revisa el changelog de tu proveedor de CAPTCHA para anticipar cambios que afecten a tu integración.
Guías relacionadas seguras
- Inicio rápido de CaptchaAI
- QA autorizado de CAPTCHA
- 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
Preguntas frecuentes
¿Puedo apuntar estos tests a un sitio que no sea mío?
No. Todo el patrón está pensado para tu propia aplicación o para entornos de QA, staging y preproducción explícitamente autorizados. Resolver el CAPTCHA de un sitio que no controlas puede infringir sus términos de servicio.
¿Qué tipos de CAPTCHA cubre CaptchaAI en mi pipeline de QA?
Los principales de la familia GA: reCAPTCHA v2 y v3, Cloudflare Turnstile y Cloudflare Challenge, GeeTest v3, más CAPTCHA de imagen/OCR, grid y BLS. CaptchaFox, Friendly Captcha y Lemin están en beta. hCaptcha y FunCaptcha (Arkose Labs) no son compatibles hoy, y GeeTest v4 figura como próximamente. Consulta la documentación oficial para la lista completa.
¿Cómo evito fallos 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í separas los fallos de red de los timeouts del proveedor y de los errores de configuración de tu propia aplicación.
¿Necesito parches de sigilo en Chrome para estas pruebas?
No, y no deberías. En un entorno propio no hay a quién engañar: ejecuta Chrome en modo estándar. Si un test se comporta distinto con anti-detección, eso es un síntoma que conviene investigar.
Crea tu API key de QA en CaptchaAI y valida el CAPTCHA de tu propio staging en navegadores controlados.
