
Adélia Cruz
MCP Integration Engineer
Publicado Nov 18, 2026
Atualizado Nov 18, 2026 · minutos de leitura

Cypress é um projeto de testes de navegador usado para exercitar aplicações web e verificar seu comportamento. Seu FAQ oficial cobre como os testes interagem com uma aplicação e aguardam o comportamento esperado. Isso é relevante aqui porque formulários protegidos por CAPTCHA têm tanto uma interação no navegador quanto um resultado de aceitação no servidor a serem testados.
Um solver é útil para uma verificação de integração limitada quando o seu fluxo autorizado já depende de reconhecimento de imagem. Ele não é um requisito para toda suíte Cypress. Testes de aplicação de rotina podem usar respostas de verificação controladas; mantenha uma verificação ao vivo separada para o caminho específico de solver que você pretende suportar.
Neste exemplo, o CapSolver recebe uma imagem por meio de sua API ImageToTextTask documentada. O Cypress insere o texto retornado no formulário de propriedade do autor e verifica o resultado do formulário. A API não clica na página, não preserva a sessão do desafio e não faz asserções de sucesso para o teste.
O glossário de CAPTCHA explica o conceito de verificação. Este tutorial usa uma imagem numérica simples para isolar a mecânica da integração. Ele não estabelece suporte para um site de terceiros ou para outro tipo de desafio.
O ambiente executado usou Node.js 24.16.0, Cypress 15.21.0 e o Electron 138 empacotado com o Cypress. A versão 15.21.0 estava disponível localmente e foi verificada antes de rodar os testes; é a versão testada aqui, não uma afirmação sobre o último lançamento.
Crie um projeto com Cypress 15.21.0 e Sharp 0.34.5 instalados. O Sharp gera um PNG para o fixture de teste local. Os arquivos de projeto reprodutíveis são listados abaixo: server.cjs, cypress.config.cjs e cypress/e2e/captcha.cy.js. Mantenha o servidor da aplicação rodando em um terminal e execute o Cypress a partir do diretório do projeto em outro.
Armazene sua chave de API do solver em um arquivo de texto local fora do projeto. Defina a variável de ambiente do processo Node CAPSOLVER_TEST_KEY_FILE para o caminho absoluto desse arquivo. O exemplo também tem um caminho local de fallback para macOS, /private/tmp/capsolver-test-key; em Windows ou outros sistemas, defina explicitamente o seu próprio caminho. Restrinja o acesso ao arquivo e o exclua de controle de versão e artefatos compartilhados.
A chave é lida pela task Node. Ela nunca é retornada ao teste em navegador, colocada em Cypress.env() ou incluída no código-fonte do exemplo. Não cole uma chave em um console de navegador nem em um teste que rode dentro da página.
Este fixture gera uma imagem numérica, retém a resposta esperada no servidor e a associa a um cookie de desafio HTTP-only. A página recebe a imagem, não a resposta como campo de texto ou variável JavaScript. Enviar uma resposta incorreta retorna Rejected; uma resposta exata e atual retorna Accepted.
Salve o seguinte como server.cjs e inicie-o com Node antes de abrir o Cypress. Fazer o bind em 127.0.0.1 mantém o fixture local. Este pequeno servidor é apenas infraestrutura de teste, não uma implementação de CAPTCHA para produção.
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 o servidor consome um desafio quando uma resposta é enviada. Isso torna uma resposta antiga inadequada para uma tentativa posterior e ajuda a revelar reutilização acidental. Uma aplicação real pode usar regras de ciclo de vida diferentes; adapte o teste ao comportamento documentado dessa aplicação.
A documentação de cy.task do Cypress define a fronteira: o teste roda no navegador, enquanto o handler registrado roda em Node.js. Argumentos e valores de retorno atravessam essa fronteira como dados serializados.
Salve esta configuração como cypress.config.cjs. O payload usa os campos clientKey, task.type e body de imagem documentados pelo CapSolver. O código personalizado em torno da requisição lida com timeouts e validação da resposta; ele é um adaptador de aplicação, não um pacote 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'); }
});
}
}
});
O corpo da imagem é Base64 sem o prefixo de data-URI. ImageToTextTask retorna seu resultado de reconhecimento diretamente, então este exemplo não adiciona um loop de polling. Se você mudar para uma task de CAPTCHA diferente, siga o contrato de resposta dessa task em vez de copiar esse fluxo síncrono sem alterações.
O handler registra apenas timestamp, tipo de task, status e texto reconhecido deste fixture sintético. Ele não registra a chave de API nem a requisição bruta. No seu próprio ambiente, decida se o texto reconhecido é adequado para logs e remova esse registro de diagnóstico quando ele não for necessário.
Resgate Seu Código de Bônus do CapSolver
Aumente instantaneamente o seu orçamento de automação!
Use o código de bônus CAP26 ao recarregar sua conta CapSolver para receber 5% de bônus extra em cada recarga — sem limites.
Resgate agora no seu Painel do CapSolver
Salve o seguinte como cypress/e2e/captcha.cy.js. O primeiro teste confirma que uma resposta errada é rejeitada. O segundo exercita a fronteira da task Node. O terceiro lê a imagem de desafio atual, chama o solver real, insere o valor retornado e verifica a aceitação pela aplicação.
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');
});
});
});
});
A partir desse diretório de projeto, execute node node_modules/cypress/bin/cypress run --browser electron. O caso ao vivo deliberadamente fica pendente quando o arquivo de chave está ausente; uma execução verde com um caso pendente não é evidência de que a integração com a API paga funcionou. Para um gate de integração ao vivo em CI, exija que esse caso seja executado e verifique se nenhum teste relevante foi ignorado.
O comando de entrada desabilita o parsing de caracteres especiais para que o texto reconhecido seja inserido literalmente. A referência do comando type do Cypress documenta essa opção. Nem o teste nem o handler alteram silenciosamente caixa de letras ou removem caracteres para forçar uma aprovação.
O exemplo é intencionalmente numérico. O guia de integração de CAPTCHA de imagem do CapSolver afirma que o reconhecimento Image To Text não tem suporte a sensibilidade de caixa. Um desafio com letras maiúsculas e minúsculas com correspondência exata de caixa exige uma decisão de capacidade separada antes que você reutilize esse fluxo.
A execução final em 18 de novembro de 2026 concluiu três testes com três aprovações, nenhuma falha e nenhum teste pendente. O solver ao vivo retornou o mesmo valor de seis dígitos mantido pelo servidor do fixture, e a aplicação retornou Accepted. O teste de resposta errada confirmou separadamente Rejected.
Uma tentativa ao vivo anterior recebeu um resultado de reconhecimento, mas falhou na asserção da aplicação. Essa tentativa não registrou os valores esperado e enviado, então sua causa exata não foi estabelecida. A execução subsequente adicionou essa evidência e confirmou um resultado correspondente. Nenhuma transformação de reconhecimento foi adicionada para fazer os valores coincidirem.
Essas observações estabelecem que a requisição, a task Cypress, a entrada no navegador, a sessão e a asserção da aplicação podem funcionar juntas neste exemplo controlado. Elas não estabelecem uma taxa de acerto, uma garantia de nível de serviço ou comportamento em um site de produção. Mantenha a execução com falha em seu histórico de avaliação; não relate apenas tentativas bem-sucedidas ao medir um solver.
Comece pela fronteira que falhou. Um arquivo de chave ausente impede uma requisição ao vivo. Um erro HTTP indica que a requisição não foi concluída normalmente. Um erro de API diferente de zero significa que o handler não deve tratar a resposta como texto reconhecido. Uma string retornada seguida de Rejected exige uma investigação em nível de aplicação.
Para esse último caso, verifique a imagem original, o texto retornado, o valor realmente enviado e se o cookie de desafio ainda está associado ao formulário atual. Se a página atualizar seu desafio, adquira novamente a imagem. Não continue enviando uma resposta de um desafio anterior nem esconda chamadas pagas repetidas dentro de um loop de repetição sem restrições.
Uma asserção de que a API retornou uma string é útil, mas incompleta. Mantenha a asserção final do formulário para que um seletor quebrado, um desafio expirado ou uma resposta errada produza uma falha de teste visível.
Use este padrão para uma pequena verificação explícita de integração de solver em uma aplicação sob seu controle. Mantenha credenciais em Node, combine a tarefa de imagem com sua capacidade documentada e verifique o resultado no formulário de recebimento. O CapSolver fornece a etapa de reconhecimento; o Cypress torna o resultado completo testado visível.
P: O Cypress inclui um solver de CAPTCHA embutido?
Este exemplo não depende de um. Ele usa o mecanismo de tasks gerais em Node do Cypress para chamar uma API de reconhecimento separada.
P: Posso usar este código para desafios do reCAPTCHA ou Cloudflare?
Não como está escrito. Este código envia uma imagem para ImageToTextTask e insere o texto reconhecido. Outros tipos de desafio exigem seus próprios parâmetros de entrada, saída e integração de aplicação documentados.
P: Por que o teste ao vivo aparece como pendente sem uma chave?
O exemplo explicitamente ignora a chamada paga quando o arquivo de chave está ausente. Pendente significa que a integração ao vivo não foi testada; isso não deve ser contado como uma solução bem-sucedida.
P: Um único desafio aceito é suficiente para alegar alta precisão?
Não. Isso apenas confirma um fluxo funcional para esse exemplo. Avalie entradas representativas e mantenha as tentativas rejeitadas antes de fazer qualquer afirmação estatística.
P: Este é um pacote oficial de integração com o Cypress?
Não. É um adaptador testado que usa a API oficial de tarefas do Cypress e o endpoint documentado CapSolver ImageToTextTask. O formulário local é uma estrutura de QA original.

Adélia Cruz
MCP Integration Engineer
Making CapSolver tools accessible through MCP.
SOBRE O AUTOR
Aprenda a lidar com CAPTCHA na automação de pedidos de compra, preservar os dados de pedidos aprovados, verificar os reconhecimentos de fornecedores e evitar envios duplicados.

Use uma checklist prática de produção de CAPTCHA para verificar o estado do navegador, as tarefas do solucionador, as tentativas de repetição, os erros e os resultados finais da aplicação antes de escalar a automação.
