企业官网建设流程全解析

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 进程里，通过 CDP（Chrome DevTools Protocol）协议去控制浏览器实例，这意味着它可以随意打开新标签页、切换多个页面、操作多个浏览器上下文，架构上更接近 Puppeteer 的强化版。它的自动等待机制也很强，而且代码风格更贴近普通 JavaScript，await满天飞但不会出问题，因为它是真正基于 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-cy="submit-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-cy="submit-order"]').click(); cy.wait('@createOrder');

这里的req.reply()直接代替了真实接口返回，意味着你可以在不依赖后端的情况下，把前端整个下单流程跑通。调试阶段和后端接口还没就绪的时候，这个能力非常管用。

第二个典型场景：页面加载时依赖某个列表接口，你不想真的等接口，或者想构造一些边界数据。那就用 fixture：

cy.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-cy="order-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-cy="countdown-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-cy="username"]').type('admin'); cy.get('[data-cy="password"]').type('123456'); cy.get('[data-cy="login-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-cy="submit-order"]').click(); cy.get('[data-cy="order-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-cy="product-${productId}"]`).click(); cy.get('[data-cy="submit-order"]').click(); cy.wait('@createOrder'); });

用例就变成：

cy.createOrder('p1001'); cy.get('[data-cy="order-success"]').should('be.visible');

不熟悉业务细节的新同学也能一眼看懂用例在验证什么。如果你发现测试代码里重复出现了三遍以上的“把某几个操作串起来”，那就该考虑封装了。别等到一个用例几百行才动手。

5. 常见问题与排查技巧实录

这部分我想用表格加案例的方式，把我实际踩过坑整理出来。每一条背后都是血泪教训。

5.1 flaky 测试的七大典型原因

我把团队里遇到过的“时好时坏”问题归了个类，方便你对照排查。

这里面最隐蔽的是“元素被遮罩层挡住”。页面上的 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-cy="pay-btn"]').click(); cy.get('[data-cy="success-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 "mochaFile=results/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' })这样的方式把外部资源打掉。调试这类“测试挂得不明不白”的问题，十次里有八次是第三方资源在拖后腿。