
Aloísio Vítor
Image Processing Expert
Publicado Nov 18, 2026
Actualizado Nov 18, 2026 · min de lectura

Cypress es un proyecto de pruebas de navegador que se utiliza para ejercitar aplicaciones web y comprobar su comportamiento. Su FAQ oficial explica cómo las pruebas interactúan con una aplicación y esperan el comportamiento previsto. Es relevante aquí porque los formularios protegidos por CAPTCHA tienen tanto una interacción en el navegador como un resultado de aceptación del lado del servidor que deben probarse.
Un solver es útil para una comprobación de integración acotada cuando su flujo de trabajo autorizado ya depende del reconocimiento de imágenes. No es un requisito para cada suite de Cypress. Las pruebas rutinarias de la aplicación pueden usar respuestas de verificación controladas; mantenga una comprobación en vivo separada para la ruta específica del solver que pretende soportar.
En este ejemplo, CapSolver recibe una imagen a través de su API ImageToTextTask documentada. Cypress introduce el texto devuelto en el formulario propio y verifica el resultado del formulario. La API no hace clic en la página, no conserva la sesión del desafío ni afirma el éxito de la prueba.
El glosario de CAPTCHA explica el concepto de verificación. Este tutorial usa una imagen numérica simple para aislar la mecánica de la integración. No establece compatibilidad con un sitio web de terceros ni con otro tipo de desafío.
El entorno ejecutado usó Node.js 24.16.0, Cypress 15.21.0 y Electron 138 incluido con Cypress. La versión 15.21.0 estaba disponible localmente y se verificó antes de ejecutar las pruebas; es la versión probada aquí, no una afirmación sobre la última versión disponible.
Cree un proyecto con Cypress 15.21.0 y Sharp 0.34.5 instalados. Sharp genera un PNG para el fixture de prueba local. Los archivos de proyecto reproducibles se enumeran más abajo: server.cjs, cypress.config.cjs y cypress/e2e/captcha.cy.js. Mantenga el servidor de la aplicación ejecutándose en una terminal y ejecute Cypress desde el directorio del proyecto en otra.
Guarde su clave de API del solver en un archivo de texto local fuera del proyecto. Establezca la variable de entorno del proceso de Node CAPSOLVER_TEST_KEY_FILE con la ruta absoluta de ese archivo. El ejemplo también tiene una ruta local de respaldo para macOS, /private/tmp/capsolver-test-key; en Windows u otros sistemas, establezca explícitamente su propia ruta. Restrinja el acceso al archivo y exclúyalo del control de versiones y de artefactos compartidos.
La clave la lee la tarea de Node. Nunca se devuelve a la prueba del navegador, no se coloca en Cypress.env() ni se incluye en el código fuente del ejemplo. No pegue una clave en una consola del navegador ni en una prueba que se ejecute dentro de la página.
Este fixture genera una imagen numérica, conserva la respuesta esperada en el servidor y la asocia con una cookie de desafío HTTP-only. La página recibe la imagen, no la respuesta como campo de texto o variable JavaScript. Enviar una respuesta incorrecta devuelve Rejected; una respuesta actual exacta devuelve Accepted.
Guarde lo siguiente como server.cjs e inícielo con Node antes de lanzar Cypress. Vincular a 127.0.0.1 mantiene el fixture local. Este pequeño servidor es andamiaje de prueba, no una implementación de CAPTCHA de producción.
const http=require('node:http');const crypto=require('node:crypto');const sharp=require('sharp');
const challenges=new Map();
const server=http.createServer(async(req,res)=>{
if(req.method==='GET' && req.url==='/'){
const token=crypto.randomBytes(16).toString('hex'); const answer=String(crypto.randomInt(100000,999999));
challenges.set(token,answer);
const png=await sharp(Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" width="260" height="90"><rect width="260" height="90" fill="white"/><text x="15" y="62" font-family="Arial" font-size="48" fill="black">${answer}</text></svg>`)).png().toBuffer();
res.writeHead(200,{'Content-Type':'text/html','Set-Cookie':`challenge=${token}; HttpOnly; SameSite=Strict`,'Cache-Control':'no-store'});
res.end(`<html><body><h1>Owned CAPTCHA QA fixture</h1><img id="captcha" alt="Numeric test challenge" src="data:image/png;base64,${png.toString('base64')}"><form><label>Answer<input id="answer" name="answer"></label><button>Submit</button></form><p id="result"></p><script>document.querySelector('form').onsubmit=async e=>{e.preventDefault();const r=await fetch('/verify',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({answer:document.querySelector('#answer').value})});document.querySelector('#result').textContent=await r.text();};</script></body></html>`);return;
}
if(req.method==='POST' && req.url==='/verify'){
let body=''; for await(const chunk of req)body+=chunk;
const token=(req.headers.cookie||'').match(/challenge=([a-f0-9]+)/)?.[1];
let value;try{value=JSON.parse(body).answer;}catch{res.writeHead(400);res.end('Bad request');return;}
const expected=challenges.get(token);const accepted=challenges.has(token) && expected===value;console.log(JSON.stringify({kind:'validation',expected,submitted:value,hasSession:!!token,accepted}));challenges.delete(token);
res.writeHead(accepted?200:422,{'Content-Type':'text/plain'});res.end(accepted?'Accepted':'Rejected');return;
}
res.writeHead(404);res.end('Not found');
});server.listen(18761,'127.0.0.1',()=>console.log('Owned QA fixture listening on 127.0.0.1:18761'));
Observe que el servidor consume un desafío cuando se envía una respuesta. Eso hace que una respuesta antigua no sea adecuada para un intento posterior y ayuda a revelar una reutilización accidental. Una aplicación real puede usar reglas de ciclo de vida diferentes; adapte la prueba al comportamiento documentado de esa aplicación.
La documentación de cy.task de Cypress define el límite: la prueba se ejecuta en el navegador, mientras que el manejador registrado se ejecuta en Node.js. Los argumentos y valores devueltos cruzan ese límite como datos serializados.
Guarde esta configuración como cypress.config.cjs. La carga útil usa los campos clientKey, task.type y body de imagen documentados por CapSolver. El código personalizado alrededor de la solicitud gestiona tiempos de espera y la validación de la respuesta; es un adaptador de aplicación, no un paquete oficial Cypress–CapSolver.
const { defineConfig } = require('cypress');
const fs = require('node:fs');
module.exports = defineConfig({
video: false, screenshotOnRunFailure: false, allowCypressEnv: false,
e2e: { baseUrl: 'http://127.0.0.1:18761', supportFile: false,
setupNodeEvents(on) {
on('task', {
async solveImage(body) {
const keyPath=process.env.CAPSOLVER_TEST_KEY_FILE || '/private/tmp/capsolver-test-key';
if (!fs.existsSync(keyPath)) throw new Error('Missing local solver key file; no live solve was attempted');
const clientKey=fs.readFileSync(keyPath,'utf8').trim();
if (!clientKey) throw new Error('Empty solver key file');
const response=await fetch('https://api.capsolver.com/createTask',{
method:'POST',headers:{'Content-Type':'application/json'},
body:JSON.stringify({clientKey,task:{type:'ImageToTextTask',body}}),
signal:AbortSignal.timeout(30000)
});
if(!response.ok) throw new Error(`Solver HTTP ${response.status}`);
const data=await response.json();
if(data.errorId!==0) throw new Error(`Solver task failed: ${data.errorCode || data.errorId}`);
if(typeof data.solution?.text!=='string' || !data.solution.text) throw new Error('No recognized text returned');
fs.appendFileSync('solve-evidence.jsonl',JSON.stringify({timestamp:new Date().toISOString(),taskType:'ImageToTextTask',status:data.status,solutionText:data.solution.text})+'\n');
return data.solution.text;
},
keyAvailable() { return fs.existsSync(process.env.CAPSOLVER_TEST_KEY_FILE || '/private/tmp/capsolver-test-key'); }
});
}
}
});
El cuerpo de la imagen es Base64 sin el prefijo de data-URI. ImageToTextTask devuelve directamente su resultado de reconocimiento, por lo que este ejemplo no añade un bucle de sondeo. Si cambia a una tarea de CAPTCHA diferente, siga el contrato de respuesta de esa tarea en lugar de copiar este flujo síncrono sin cambios.
El manejador registra solo una marca temporal, tipo de tarea, estado y texto reconocido de este fixture sintético. No registra la clave de la API ni la petición en bruto. En su propio entorno, decida si el texto reconocido es adecuado para los registros y elimine ese registro de diagnóstico cuando ya no sea necesario.
Canjee su código de bonificación de CapSolver
Aumente su presupuesto de automatización al instante.
Use el código de bonificación CAP26 al recargar su cuenta de CapSolver para obtener un 5% extra en cada recarga, sin límites.
Canjéelo ahora en su Panel de CapSolver
Guarde lo siguiente como cypress/e2e/captcha.cy.js. La primera prueba confirma que una respuesta incorrecta es rechazada. La segunda ejercita el límite de la tarea de Node. La tercera lee la imagen actual del desafío, llama al solver real, introduce el valor devuelto y comprueba la aceptación por parte de la aplicación.
describe('Owned image CAPTCHA form', () => {
it('rejects an incorrect answer at the application boundary', () => {
cy.visit('/');
cy.get('#answer').type('incorrect');
cy.get('button').click();
cy.get('#result').should('have.text','Rejected');
});
it('runs the Node task boundary without exposing the solver key', () => {
cy.task('keyAvailable').then(value => expect(value).to.be.a('boolean'));
});
it('submits a live solver result for the current challenge', function () {
cy.task('keyAvailable').then(available => {
if(!available) this.skip();
cy.visit('/');
cy.get('#captcha').should('have.attr','src').then(src => {
const body=src.split(',')[1];
return cy.task('solveImage',body,{timeout:40000,log:false});
}).then(text => {
cy.get('#answer').type(text,{log:false,parseSpecialCharSequences:false});
cy.get('button').click();
cy.get('#result').should('have.text','Accepted');
});
});
});
});
Desde este directorio de proyecto, ejecute node node_modules/cypress/bin/cypress run --browser electron. El caso en vivo se vuelve deliberadamente pendiente cuando falta el archivo de clave; una ejecución en verde con un caso pendiente no es evidencia de que la integración con la API de pago haya funcionado. Para una compuerta de integración en vivo en CI, exija que ese caso se ejecute y compruebe que no se hayan omitido pruebas relevantes.
El comando de entrada desactiva el análisis de caracteres especiales, de modo que el texto reconocido se introduce literalmente. La referencia de type de Cypress documenta esta opción. Ni la prueba ni el manejador cambian silenciosamente el uso de mayúsculas y minúsculas ni eliminan caracteres para forzar un aprobado.
El ejemplo es intencionadamente numérico. La guía de integración de CAPTCHA de imagen de CapSolver indica que el reconocimiento de Image To Text no admite sensibilidad a mayúsculas. Un desafío mixto de mayúsculas y minúsculas con coincidencia exacta de caso necesita una decisión de capacidad separada antes de reutilizar este flujo de trabajo.
La ejecución final del 18 de noviembre de 2026 completó tres pruebas con tres aprobados, sin fallos y sin pruebas pendientes. El solver en vivo devolvió el mismo valor de seis dígitos que mantenía el servidor del fixture, y la aplicación devolvió Accepted. La prueba de respuesta incorrecta confirmó por separado Rejected.
Un intento en vivo anterior recibió un resultado de reconocimiento pero falló en la aserción de la aplicación. Ese intento no registró los valores esperados y enviados, por lo que no se estableció su causa exacta. La ejecución posterior añadió esa evidencia y confirmó un resultado coincidente. No se añadió ninguna transformación de reconocimiento para hacer que los valores coincidieran.
Estas observaciones establecen que la solicitud, la tarea de Cypress, la entrada del navegador, la sesión y la aserción de la aplicación pueden funcionar juntas en este ejemplo controlado. No establecen una tasa de precisión, una garantía de nivel de servicio ni el comportamiento en un sitio de producción. Mantenga la ejecución fallida en su historial de evaluación; no informe solo de intentos exitosos al medir un solver.
Empiece por el límite que falla. Un archivo de clave ausente impide una solicitud en vivo. Un error HTTP indica que la solicitud no se completó normalmente. Un error de API distinto de cero significa que el manejador no debe tratar la respuesta como texto reconocido. Una cadena devuelta seguida de Rejected requiere una investigación a nivel de aplicación.
Para este último caso, compruebe la imagen original, el texto devuelto, el valor realmente enviado y si la cookie de desafío sigue asociada con el formulario actual. Si la página actualiza su desafío, vuelva a obtener la imagen. No siga enviando una respuesta de un desafío anterior ni oculte llamadas de pago repetidas dentro de un bucle de reintento sin restricciones.
Una aserción de que la API devolvió una cadena es útil pero incompleta. Mantenga la aserción final del formulario para que un selector roto, un desafío expirado o una respuesta incorrecta produzcan un fallo visible en la prueba.
Use este patrón para una pequeña y explícita comprobación de integración del solver en una aplicación que controle. Mantenga las credenciales en Node, adapte la tarea de imagen a su capacidad documentada y verifique el resultado en el formulario receptor. CapSolver proporciona el paso de reconocimiento; Cypress hace visible el resultado final probado.
P: ¿Incluye Cypress un solver de CAPTCHA integrado?
Este ejemplo no depende de uno. Usa el mecanismo de tareas de Node de propósito general de Cypress para llamar a una API de reconocimiento separada.
P: ¿Puedo usar este código para desafíos de reCAPTCHA o Cloudflare?
No tal como está escrito. Este código envía una imagen a ImageToTextTask e introduce el texto reconocido. Otros tipos de desafíos requieren sus propias entradas, salidas e integración con la aplicación, según su documentación.
P: ¿Por qué la prueba en vivo aparece como pendiente sin una clave?
El ejemplo omite explícitamente la llamada de pago cuando falta su archivo de clave. Pendiente significa que la integración en vivo no se probó; no debe contarse como una resolución exitosa.
P: ¿Es suficiente un solo desafío aceptado para afirmar alta precisión?
No. Solo confirma una ruta funcional para ese ejemplo. Evalúa entradas representativas y conserva los intentos rechazados antes de hacer cualquier afirmación estadística.
P: ¿Es este un paquete de integración oficial de Cypress?
No. Es un adaptador probado que utiliza la API oficial de tareas de Cypress y el endpoint documentado de CapSolver ImageToTextTask. El formulario local es andamiaje de QA original.

Aloísio Vítor
Image Processing Expert
Interpreting the visual signals behind web workflows.
SOBRE EL AUTOR
Aprende a gestionar CAPTCHA en la automatización de órdenes de compra, preservar los datos de órdenes aprobadas, verificar las confirmaciones de los proveedores y evitar envíos duplicados.

Utiliza una lista de verificación práctica para la producción de CAPTCHA a fin de verificar el estado del navegador, las tareas del solucionador, los reintentos, los errores y los resultados finales de la aplicación antes de escalar la automatización.
