1. 为什么我最终把测试主力切到了 Cypress先交代一下背景。我之前在团队里折腾过好几轮前端自动化测试最早用 Selenium后来又试过 Puppeteer再后来是 Playwright 和 Cypress 二选一。说实话每个工具都有各自的甜区但真正让我决定把 Cypress 当作“默认选项”的不是某个花哨功能而是它把“调试体验”这件事做到了足够自然。Cypress 是一个以前端开发者体验为核心导向的端到端测试工具它跑在浏览器里和你的应用共享同一个运行时上下文。这意味着你写测试的时候不再需要像 Selenium 那样在“外部进程”和“浏览器内部”之间来回切换也不需要用一堆繁琐的等待条件去模拟用户行为。Cypress 的命令队列机制会把操作串起来然后自动等待元素出现、动画结束、请求返回这一套下来测试代码读起来几乎就像一份“用户操作说明书”。这篇文章不会去复述 Cypress 的官方文档我只挑几个我在项目里实测过、真正解决过问题的核心技巧和调试策略来写。内容包括选择器和数据交互的稳定写法、拦截网络请求的正确姿势、从“黑盒点按”进化到“白盒诊断”的调试方法以及一组我踩过坑之后总结出来的常见问题排查表。如果你正准备把 Cypress 引入团队或者已经在用但总觉得测试不稳定、跑挂了不知道从哪里查起那这篇文章应该能帮你省下不少时间。我后面还会专门聊一个绕不开的话题Cypress 和 Playwright 怎么选。这不是要分个高下而是把两者的机制差异讲清楚你才知道什么场景该用哪个。2. 先用懂 Cypress 的底层运行逻辑再谈技巧很多初学者学 Cypress 容易陷入一个误区上来就照着网上抄一堆代码然后发现测试时好时坏就开始怀疑工具不行。其实大部分不稳定问题根源都在于没有理解 Cypress 的命令执行方式。2.1 命令队列、自动重试和“看似同步”的异步Cypress 里的cy.get()、cy.click()这些命令并不是像普通 JavaScript 函数那样一行一行立即执行而是被推入一个内置的“命令队列”里。整个队列会严格按照顺序依次执行每一条命令执行之前Cypress 会自己处理“元素是否存在”“是否可见”“是否可点击”“动画是否结束”这一系列前置条件。这一点非常关键它解释了你为什么几乎不需要写sleep或者waitForElement这类逻辑。举个例子你写cy.get(.submit-btn).click(); cy.get(.success-toast).should(be.visible);第一行执行的时候submit-btn如果还没有渲染出来Cypress 不会立刻报错而是会在一段时间内反复尝试直到元素出现并完成点击。第二行同理。这个“重试机制”是 Cypress 稳定性的基石但它也有副作用——如果你滥用一些不受自动重试保护的 API比如cy.wait()加固定毫秒数那测试的稳定性就会瞬间崩塌。后面讲调试和排查时我会细说。还有一个容易误解的点你没法在 Cypress 的测试代码里用async/await去等待一个命令执行完。比如这样写是无效的// 错误示范 await cy.get(.user-name);Cypress 会直接警告。因为它的命令队列本来就是异步调度的你只要始终在队列里组合命令然后配合.then()拿结果就够了。如果你需要在拿到元素文本之后做一些断言正确的写法是把逻辑放到.then()回调里cy.get(.user-name) .then(($el) { const text $el.text(); expect(text).to.contain(管理员); });这段代码里的$el是 jQuery 包装对象能直接用.text()。理解了这个模型以后很多“为什么这里不生效”“为什么那里没等到”的问题都能找到答案。2.2 Cypress 与 Playwright 的运行机制差异选型前必须知道的事既然热词里反复出现“playwright与cypress”我就把选型这个事放在前面讲。这两者表面上看都是现代端到端测试工具但底子很不一样而底子决定了它们的强项和弱点。Cypress 跑在你的浏览器应用进程内部它通过注入一段脚本来驱动页面和页面共享 DOM 和运行时上下文。好处是调试时你能看到真实的页面能直接访问window、document能拿到应用内部的一些状态坏处是它天生被限制在“单页面上下文”里处理多标签页、跨域 iframe 会比较痛苦后来推出的cy.origin()解决了一部分跨域问题但终究没有像 Playwright 那样把“多页面”当成一等公民来设计。Playwright 则走的是“外部控制”路线。测试脚本运行在 Node.js 进程里通过 CDPChrome DevTools Protocol协议去控制浏览器实例这意味着它可以随意打开新标签页、切换多个页面、操作多个浏览器上下文架构上更接近 Puppeteer 的强化版。它的自动等待机制也很强而且代码风格更贴近普通 JavaScriptawait满天飞但不会出问题因为它是真正基于 Promise 的。那我在什么场景下会选 Cypress什么场景下会选 Playwright直接给结论如果你做的是“单页应用内部的完整用户流程测试”而且团队以 JavaScript 技术栈为主Cypress 的上手成本和调试体验是目前最舒服的。如果你的业务重度依赖多标签页、多用户同时在线、iframe 嵌套或者你需要在同一套测试里跑多种浏览器的高级场景Playwright 的架构优势会更明显。如果团队已经对 Cypress 有所积累但又想写多标签页测试不要急着推翻重来先评估一下这类用例在整个测试体系里的占比再决定要不要引入第二套工具。我自己目前的策略是主力回归流程用 Cypress个别涉及多标签页和复杂跨域的场景用 Playwright 单独补几个用例。双工具确实会带来维护成本但总比拿一个工具的短板去硬扛业务需求要稳妥。2.3 为什么“自动等待”既省心也坑人前面说 Cypress 会自动重试、会自动等待这看起来很美好但用久了你会发现自动等待让“通过”变容易了却也让“排查为什么会挂”变难了。当你看到一个失败截图时你往往不知道 Cypress 到底等了多久、中间发生了什么、是哪一次重试失败的。所以我会在项目里做两件事第一严格控制超时时间的设置不要全用默认值。比如一个列表接口在弱网环境下可能需要 3 秒才能返回那cy.get(.list-item, { timeout: 10000 })就比默认的 4 秒要稳得多。第二给关键操作步骤加上清晰的日志和断言点让测试挂掉时能快速定位到是“元素没出来”还是“接口返回了错误数据”。3. 核心技巧从选择器到网络拦截的稳定方案测试代码最怕的就是“今天能跑、明天挂了”“在这台机器能过、在 CI 上过不去”。我总结了一圈绝大多数问题都出在选择器不可靠、等待方式不合理、网络请求没处理好这三个环节。3.1 选择器优先级>button>cy.get([data-cysubmit-order]).click();对比一下用 class 写的场景开发改了个样式把btn-primary换成了btn-brand你辛辛苦苦维护的测试用例直接报废。而>cy.contains(button, 提交订单).click();这种写法适合按钮文字变化不频繁的简单场景。一旦页面上的类似文字变多还是要回到>cy.intercept(POST, /api/order, (req) { expect(req.body.items).to.have.length(2); req.reply({ statusCode: 200, body: { orderId: 12345 } }); }).as(createOrder); cy.get([data-cysubmit-order]).click(); cy.wait(createOrder);这里的req.reply()直接代替了真实接口返回意味着你可以在不依赖后端的情况下把前端整个下单流程跑通。调试阶段和后端接口还没就绪的时候这个能力非常管用。第二个典型场景页面加载时依赖某个列表接口你不想真的等接口或者想构造一些边界数据。那就用 fixturecy.intercept(GET, /api/users, { fixture: users-empty.json }).as(getUsers); cy.visit(/users); cy.wait(getUsers);users-empty.json放在cypress/fixtures/目录里里面可以写{ data: [] }这样就能快速验证“空列表态”的页面表现。比你去数据库里折腾测试数据要高效得多。这里有一个我踩过的坑早期我用的是cy.route()它在旧版 Cypress 里是主力 API但后来官方推荐cy.intercept()因为cy.route()只支持 XHR 和 fetch 的一部分新出的请求方式覆盖不到。如果你在网上看到很老的教程还在用cy.server()加cy.route()建议直接忽略换成cy.intercept()。3.3 别再用cy.wait(2000)这种“死亡倒计时”我刚接手一个老项目时里面充满了这样的代码cy.wait(2000); cy.get(.list).should(be.visible);这 2000 毫秒看起来无害但实际上是个定时炸弹。原因很简单如果你的电脑性能好接口 300 毫秒就返回了你就白等了 1.7 秒如果那天 CI 机器负载高接口 3 秒才返回你的测试在第 2 秒就已经开始找元素了找不到就失败。无论哪种情况测试都不稳定。Cypress 官方提倡的做法是等待“一个你真正依赖的条件”大多数时候是等待某个接口完成。写法就是用cy.wait(alias)cy.intercept(GET, /api/orders).as(getOrders); cy.visit(/orders); cy.wait(getOrders); cy.get([data-cyorder-list]).should(be.visible);这里的核心逻辑是页面渲染依赖于接口返回那么我就等接口而不是等时间。这是我从“测试老挂”到“测试稳定”转变的关键一步。另外cy.clock()和cy.tick()也值得提一下。如果你的页面里有轮询、倒计时、定时器这类逻辑测试时最怕等真实时间。用cy.clock()可以锁定时间然后cy.tick(10000)直接快进 10 秒非常方便。cy.clock(); cy.visit(/countdown); cy.tick(5000); cy.get([data-cycountdown-text]).should(contain, 00:00);不过要注意cy.clock()会覆盖全局的setTimeout和setInterval如果某些业务逻辑依赖真实时间可能会被影响。用之前先确认页面里没有“必须在真实时间内完成”的行为。3.4 登录态复用cy.session()让每个用例不再重复登录端到端测试最烦的一件事就是每个用例都要重新走一遍登录流程。不仅慢而且容易被验证码、二次认证之类的东西打断。Cypress 从 8.2 版本开始推荐使用cy.session()它是目前官方最推荐的登录态缓存方式。基本思路是把登录动作封装成一个函数用cy.session()包起来。同一个测试会话里第二次调用时就不会真的执行登录了而是直接把缓存好的 localStorage、sessionStorage、cookie 状态恢复出来。function login() { cy.session(admin-user, () { cy.visit(/login); cy.get([data-cyusername]).type(admin); cy.get([data-cypassword]).type(123456); cy.get([data-cylogin-btn]).click(); cy.url().should(include, /dashboard); }); }然后在每个用例里beforeEach(() { login(); });第一个用例会真实登录一次后面的用例直接从缓存恢复状态。实测下来整个测试套件的运行时间能缩短一半以上。而且因为登录态是预先设置的用例之间的独立性也更强了不会出现“上一个用例把登录状态搞乱了导致下一个用例失败”这种连锁反应。如果你还在用老式写法在每个用例的beforeEach里都cy.visit(/login)再填一遍表单我建议尽快改成cy.session()。这不只是省时间的问题更是减少 many-to-many 的隐式依赖。4. 调试策略从“黑盒点按”进化到“白盒诊断”测试失败不可怕可怕的是失败了你不知道发生了什么。Cypress 在这方面给了我特别大的安全感因为它只要能运行起来几乎每一秒的操作都有据可查。4.1 命令日志、快照和时间旅行Cypress 跑起来的界面上左边是操作列表右边是页面状态。你每执行一步命令左侧就会记录一条日志鼠标悬停到某一条上右侧就会“回放”出那一刻的页面快照。这个时间旅行能力是我觉得 Cypress 最讨喜的设计。当测试失败时第一步不是去猜而是直接点开失败那一条日志看快照里页面到底是什么状态。很多时候问题一眼就能看出来按钮还没渲染、接口返回了一堆错误、页面跳到了登录页。这种“所见即所得”的调试体验是 Selenium 时代完全不敢想的。我的习惯是每次写完一个新用例先打开 Cypress 的图形化界面跑一遍眼睛盯着每一步的页面快照确认操作路径和真实用户的操作一致。这一步能发现大量“元素定位错了”“点击被遮住了”之类的隐性问题。4.2 断点式调试cy.pause()和debugger有些问题靠看快照还不够你想在某个步骤停下来手动去页面上摸一摸甚至改一改界面元素。Cypress 提供了两个帮手。第一个是cy.pause()把它放在测试中间Cypress 会暂停执行等你在界面上点击“下一步”按钮再继续。第二个是debugger用起来更接近我们在 Chrome DevTools 里的习惯cy.get([data-cysubmit-order]).click(); cy.get([data-cyorder-modal]).then(($modal) { debugger; });只要你的浏览器开发者工具开着执行到debugger的时候就会自动断住。这时候你可以在 Console 里直接访问$modal变量看看它身上的 class、style、data 属性甚至可以执行一段 jQuery 去查找它的子元素。这种调试方式特别适合排查“元素在 DOM 里但是显示不出来”这类诡异问题。4.3 截图、录屏和失败归档CI 环境里没有图形化界面你没法在跑的过程中去点击调试。Cypress 默认会在断言失败时自动截图我们只需要保证所有失败信息能够被归到一起来看。我在团队里做了一套简单的归档方案每次测试跑完不管是通过还是失败都把cypress/screenshots和cypress/videos下的文件打包上传到内部的文件存储服务上并在 CI 的日志里附上下载链接。这样开发人员自己就可以去翻失败时的截图和录屏不用每次都找测试同学拿一手信息。这里有个小技巧截图只会在失败时自动触发但如果你想在“某个关键步骤”主动留一张现场记录可以用cy.screenshot(after-submit-order);然后在 Cypress 的截图目录里就能找到after-submit-order.png。这在调试一些偶发问题时特别有用比如我可以连续跑 10 次每次都在关键步骤截图跑完再统一对比看看是不是某一次出现了异常按钮状态。4.4 自定义命令封装让测试代码变成“业务语言”测试代码也是代码它也讲究可读性和可维护性。我从项目一开始就强烈推荐团队成员用自定义命令把重复度高、业务含义强的操作抽出来。比如“登录”已经用cy.session()封装好了那“创建一个订单”也可以封装Cypress.Commands.add(createOrder, (productId) { cy.intercept(POST, /api/order).as(createOrder); cy.get([data-cyproduct-${productId}]).click(); cy.get([data-cysubmit-order]).click(); cy.wait(createOrder); });用例就变成cy.createOrder(p1001); cy.get([data-cyorder-success]).should(be.visible);不熟悉业务细节的新同学也能一眼看懂用例在验证什么。如果你发现测试代码里重复出现了三遍以上的“把某几个操作串起来”那就该考虑封装了。别等到一个用例几百行才动手。5. 常见问题与排查技巧实录这部分我想用表格加案例的方式把我实际踩过坑整理出来。每一条背后都是血泪教训。5.1 flaky 测试的七大典型原因我把团队里遇到过的“时好时坏”问题归了个类方便你对照排查。症状根本原因解决思路点击按钮偶尔报 element not found页面还在渲染元素没有及时出现给cy.get()加timeout或把断言改成should(exist)缓冲一下明明元素存在却报 not visible / not actionable元素被遮罩层、loading 浮层或弹窗挡住先处理遮罩cy.get(.cover).should(not.exist)再去点击表单输入偶尔丢失字符cy.type()输入速度太快部分事件没触发给type加{ delay: 50 }或改用cy.realType()需要插件跑本地通过CI 上挂CI 机器性能差接口响应慢、动画更久统一提高关键超时时间在 CI 配置里禁用动画或降低帧率断言永远差一点点时间接口未完成就开始检查页面改用cy.intercept()cy.wait(alias)页面跳转后旧元素还在单页应用路由切换时旧 DOM 未立即卸载等待新页面标志出现比如cy.get([data-cydashboard]).should(be.visible)前端组件使用了随机数或时间戳每次渲染 DOM 结构有细微差异断言时只验证核心属性和文本不要和全量快照对比这里面最隐蔽的是“元素被遮罩层挡住”。页面上的 loading 条、弹窗遮罩、全局提示条都可能在你点击目标按钮时横向拦截了鼠标事件。Cypress 的“actionability”规则会在元素被遮挡时直接判失败这其实是保护机制比“明明没点上也通过了”要好得多。5.2 iframe、多标签页和跨域问题怎么绕Cypress 对 iframe 的支持过去一直比较弱后来一路优化现在访问同源 iframe 可以用cy.iframe()插件或者直接用原生的cy.get(iframe).its(0.contentDocument.body)方式。但如果你被测系统里嵌入了跨域第三方页面比如支付平台的收银台在 Cypress 里的处理就麻烦很多。官方推出的cy.origin()在 Cypress 12 之后已经可以承担跨域任务的执行了。我建议把它当成独立上下文来使用结构类似cy.origin(https://payment.example.com, () { cy.get([data-cypay-btn]).click(); cy.get([data-cysuccess-message]).should(be.visible); });只要注意cy.origin()里的回调和外层绝不能共享闭包变量它内部是完全隔离的。这个限制一开始会让人不适应但理解之后反而清晰跨域页面本来就不该和主应用共享状态。至于多标签页我在 Cypress 里目前没有找到优雅的解法因为它确实不是 Cypress 的设计目标。如果业务必须测多标签页交互我倾向用 Playwright 补几个烟囱用例而不是和 Cypress 死磕。5.3 测试数据隔离别让用例之间互相“污染”另一个容易忽略的问题是测试数据隔离。如果你一个用例创建了订单另一个用例又去查订单列表而订单数据是共享的那么用例顺序一变结果就可能不同。我在这方面的做法是每个用例尽量自己构造前置数据要么走接口造数据要么用 fixture 控制接口返回。不要让用例依赖“前一个用例运行后留下的状态”。cy.session()帮我们解决了登录态共享的问题但业务数据还是要靠接口层面去隔离。实际操作中我会在beforeEach里用cy.request()调后端测试接口创建一个带有随机后缀的数据对象然后存到闭包变量里供当前用例使用let orderId; beforeEach(() { cy.request(POST, /api/test/orders, { name: 订单-${Date.now()} }) .then((res) { orderId res.body.id; }); });这样每个用例都基于独立数据天然不会互相打架。代价是测试代码里要多写一点接口调用的准备逻辑但这点成本换来的是稳定性的巨大提升。6. 团队落地经验把 Cypress 用成“工程标配”最后聊一点团队层面的东西。工具再好落地节奏不对也会被大家抵制。我经历过“推测试工具被开发嫌弃”“测试用例没人维护”“CI 跑一次 40 分钟没人愿意看”的各个阶段所以这里给出一套我验证过比较顺的落地路径。6.1 CI 集成与报告可视化Cypress 跑在 CI 上时最怕的就是“全量跑很久然后告诉你哪里挂了但你不想打开日志一行行翻”。我的建议是两条腿走路一是给 CI 配置里加上--record或上传产物到 Cypress Dashboard 之类的服务直接看带截图的关键步骤回放二是自己把 JUnit 格式的 XML 报告接到现有报表体系里让测试结果能并入研发效能大盘。我推荐一个比较实用的命令组合cypress run --headless --browser chrome --reporter junit --reporter-options mochaFileresults/test-output-[hash].xml跑完以后把results/目录和screenshots/、videos/一起作为产物归档。这样每个失败用例都有截图和录屏可查后续定位问题会省很多时间。6.2 用例分层冒烟、回归、全量不是所有用例都适合全量跑。我把测试分成三层冒烟层核心主流程比如登录、下单、支付跑一遍控制在一分钟以内每次代码改动都触发。回归层覆盖主要业务模块的完整路径每天定时跑一次跑完把结果通知到相关开发。全量层包含各种边界条件、异常分支的用例每周跑一次或者发版前跑一次耗时较长但覆盖面更全。这个分层策略极大降低了测试运行成本和噪音。开发不会因为一个边缘用例失败而频繁打断测试同学也能在关键时间节点拿到有价值的回归结果。6.3 维护责任的归属谁写的代码谁维护测试推测试工具最大的阻力往往不是技术而是“维护责任不清”。开发觉得测试是测试同学的事测试觉得用例写的是新功能逻辑自己看不懂。时间一长用例就烂掉了。我后面定下的规矩是新增业务功能时开发必须同步更新对应的 Cypress 用例否则代码合并不通过。这个规矩一开始会有点疼但一旦养成习惯整个测试套件会始终跟着业务演进走不会被丢在角落里落灰。架构上讲Cypress 的前置门槛确实比 Playwright 低不少因为它所有断言语法读起来非常接近自然语言开发同学上手成本低。这也是我当时坚持选它的原因之一——越是大家容易上手的工具团队的执行阻力就越小。个人在实际操作中体会最深的是 Cypress 对“前端开发者”这个角色的友好不是停留在宣传语上而是融到了每一个细节里命令日志、时间旅行快照、debugger无缝衔接、拿页面里的真实状态做断言……这些体验综合下来它让我从“讨厌写测试”变成了“愿意先写测试再写业务代码”。如果你团队里还有人对前端自动化测试持观望态度建议先从一条最简单的核心用户路径开始用 Cypress 跑通让那个开发者自己感受一下“测试跑起来时你就在页面旁边看着每一步发生”的踏实感。这种体验一旦建立起来后面的推广就水到渠成了。最后再分享一个小技巧如果你的项目里有些页面加载了外部资源比如字体、第三方图片会让页面 onload 事件一直处于等待状态影响 Cypress 判断页面是否真正 ready。这种情况可以访问页面之前用cy.intercept(GET, **/fonts/*, { fixture: empty.txt })这样的方式把外部资源打掉。调试这类“测试挂得不明不白”的问题十次里有八次是第三方资源在拖后腿。