
Lucas Mitchell
Automation Engineer
已发表 Nov 18, 2026
已更新 Nov 18, 2026 · 最小阅读量

Cypress 是一个浏览器测试项目,用于驱动 Web 应用并检查其行为。其官方 FAQ介绍了测试如何与应用交互以及如何等待预期行为。在本场景中,这一点尤其相关,因为受验证码保护的表单同时具有浏览器交互和服务端接受结果这两个测试目标。
当你的授权业务流程本就依赖图像识别时,验证码求解器对于做一个“有边界”的集成检查是有用的。它并不是每套 Cypress 测试都必须具备的组件。常规应用测试可以使用可控的验证返回值;针对你真正计划支持的验证码求解路径,单独保留一套真实调用检查。
在本示例中,CapSolver 通过其文档中的 ImageToTextTask API 接收一张图片。Cypress 将返回的文本输入到自有表单中并验证表单结果。该 API 不会点击页面、不会维持验证码会话、也不会替测试断言成功。
验证码术语表对验证概念进行了说明。本教程使用简单的数字图片,仅用于隔离集成机制。本示例不宣称支持第三方网站,也不宣称支持不同类型的挑战。
执行环境使用 Node.js 24.16.0、Cypress 15.21.0,以及 Cypress 自带的 Electron 138。15.21.0 版本已在本地安装并在运行测试前验证过;这里仅说明这是“已测试版本”,不代表它是最新版本。
创建一个项目,并安装 Cypress 15.21.0 与 Sharp 0.34.5。Sharp 用来为本地测试夹具生成 PNG。可复现实例的项目文件包括:server.cjs、cypress.config.cjs 和 cypress/e2e/captcha.cy.js。在一个终端中保持应用服务器运行,在另一个终端中从项目目录内执行 Cypress。
将求解器的 API 密钥存储在项目外部的本地文本文件中。把 Node 进程环境变量 CAPSOLVER_TEST_KEY_FILE 设为该文件的绝对路径。示例中提供了一个 macOS 本地后备路径 /private/tmp/capsolver-test-key;在 Windows 或其他系统上,请显式设置你自己的路径。限制该文件的访问权限,并将其排除在源码管理与共享制品之外。
密钥仅由 Node 端 task 读取。它不会被返回给浏览器端测试,也不会放入 Cypress.env(),也不会出现在示例源码中。不要把密钥粘贴进浏览器控制台,也不要粘贴进在页面内运行的测试中。
此夹具会生成一个数字图片,在服务端保存预期答案,并通过 HTTP-only challenge Cookie 关联本次挑战。页面接收的是图片,而不是以文本字段或 JavaScript 变量形式接收答案。提交错误答案会返回 Rejected;提交当前挑战的精确答案则返回 Accepted。
将以下内容保存为 server.cjs,并在启动 Cypress 前用 Node 运行它。绑定到 127.0.0.1 可以使夹具只在本机可访问。这个小服务器只是测试脚手架,而不是生产用的验证码实现。
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'));
注意,服务器在提交答案后会“消耗”该挑战。这使得旧答案不能用于后续尝试,并有助于暴露意外复用的情况。真实应用可能采用不同的生命周期规则;请根据该应用的文档化行为调整测试。
Cypress 的 cy.task 文档定义了边界:测试在浏览器中运行,而注册的处理函数在 Node.js 中运行。参数与返回值以序列化数据的形式跨越该边界。
将以下配置保存为 cypress.config.cjs。请求负载使用了 CapSolver 文档中的 clientKey、task.type 和图片 body 字段。围绕请求的自定义代码负责超时和响应校验;它是应用适配层,而不是官方的 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'); }
});
}
}
});
图片 body 是去掉 data-URI 前缀的 Base64。ImageToTextTask 会直接返回识别结果,因此本示例未加入轮询逻辑。如果你切换到不同类型的验证码任务,请遵循该任务自身的返回约定,而不是不加修改地照搬此“同步流程”。
此处理函数仅记录时间戳、任务类型、状态以及来自此合成夹具的识别文本。它不会记录 API 密钥或原始请求。在你的环境中,应自行决定识别文本是否适合写入日志;一旦不再需要该诊断记录,请将其移除。
领取你的 CapSolver 奖励码
立刻提升你的自动化预算!
在为 CapSolver 账号充值时使用奖励码 CAP26,每次充值都可额外获赠 5% 奖励——次数不限。
现在就到你的 CapSolver 控制台 兑换。
将以下内容保存为 cypress/e2e/captcha.cy.js。第一个测试确认错误答案会被拒绝。第二个测试练习 Node task 边界。第三个测试读取当前挑战图片,调用真实的求解器,将返回值输入表单,并检查应用是否接受。
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');
});
});
});
});
在项目目录中运行 node node_modules/cypress/bin/cypress run --browser electron。当密钥文件不存在时,真实调用用例会刻意变为 pending;因此,一个包含 pending 用例的绿灯运行不能用来证明付费 API 集成“已实际生效”。若要在 CI 中把真实集成作为门禁,请要求该用例必须执行,并检查没有相关测试被跳过。
输入命令禁用了特殊字符解析,从而让识别文本按字面输入。该选项详见 Cypress type 参考文档。测试与处理函数都不会悄悄更改字母大小写或剔除字符来“强行通过”。
本示例刻意使用纯数字。CapSolver 的图片验证码集成指南指出,Image To Text 识别不支持区分大小写。对于混合大小写且要求精确大小写匹配的挑战,在复用此工作流前,需要单独做一次能力决策。
2026 年 11 月 18 日的最终运行完成了三个测试,结果为三项通过、零失败、零 pending。真实求解器返回了与夹具服务器中保存的六位数字完全一致的值,应用返回 Accepted。错误答案测试则独立确认了 Rejected。
较早的一次真实调用虽然收到了识别结果,却在应用断言处失败。那次运行没有记录预期值与提交值,因此未能确定其确切原因。后续运行增加了这些证据并确认了结果匹配。在此期间,没有添加任何用于“修正”值的识别结果变换逻辑。
这些观察表明,在这个可控的示例中,请求、Cypress task、浏览器输入、会话及应用断言可以协同工作。但它们并不能证明某种准确率、服务等级保证或在线上站点上的表现。在评估求解器时,应保留失败运行的记录,而不是只汇报成功尝试。
从失败的边界开始排查。缺失的密钥文件会阻止真实请求。HTTP 错误表明请求未正常完成。非零 API 错误意味着处理函数绝不能把响应当作已识别文本来使用。若已返回字符串却得到 Rejected,则需要进行应用层面的调查。
对于最后一种情况,请检查原始图片、返回文本、实际提交值,以及挑战 Cookie 是否仍与当前表单关联。如果页面刷新了验证码挑战,则需要重新获取图片。不要持续提交来自“上一个挑战”的答案,也不要把重复付费调用藏在无限制的重试循环中。
对“API 返回了一个字符串”的断言是有用的,但还不够。务必保留最终表单断言,以便选择器损坏、挑战过期或答案错误都能显式导致测试失败。
在你可控的应用中,使用这种模式做一项小而明确的求解器集成检查。将凭据保留在 Node 端,将图像任务与其文档化能力一一对应,并验证接收表单的实际结果。CapSolver 提供识别步骤,Cypress 则让完整的测试结果一目了然。
问:Cypress 自带内置的验证码求解器吗?
本示例并未依赖任何内置求解器。它使用 Cypress 的通用 Node task 机制去调用独立的识别 API。
问:我可以把这段代码用于 reCAPTCHA 或 Cloudflare 挑战吗?
不能按原样直接用。这段代码是把一张图片提交给 ImageToTextTask 并输入识别出的文本。其他类型的挑战需要它们各自文档中规定的输入、输出以及应用集成方式。
问:为什么没有密钥时,实时测试会一直显示为 pending?
示例在找不到密钥文件时,会显式跳过付费调用。状态为 pending 表示没有进行实时集成测试;它绝不能被视为一次成功的解决记录。
问:只通过一次挑战就足以声称高准确率吗?
不可以。这只能证明该示例的流程是可用的。要在提出任何统计结论前,先评估具有代表性的输入,并保留所有被拒绝的尝试。
问:这是官方的 Cypress 集成包吗?
不是。它是一个经过测试的适配器,使用了官方的 Cypress task API 和已文档化的 CapSolver ImageToTextTask 端点。本地形式是原创的 QA 脚手架。

Lucas Mitchell
Automation Engineer
Helping browser automation recover and continue.
关于作者