1. 项目概述

1.1 为什么要专门聊 E2E 测试

先说说我为什么想写这个主题。前阵子接手了一个中大型前端项目，代码量不大不小，但每次发版前手工回归都要折腾半天——从登录到下单到支付，主流程走一遍就得二十多分钟，遇到改了公共组件，还得把周边功能全点一遍。好几个同事私下抱怨过“改一行代码，提心吊胆一整天”，但大家一直没下定决心搞自动化。

后来我花了两周时间，把端到端测试（E2E，End-to-End）的框架搭了起来，把核心业务链路全部覆盖上，从那以后发版压力一下小了很多。这篇博文就是把这段时间的实践经验整理出来，包括框架选型、用例设计、环境配置、以及我在落地过程中踩过的各种坑。

E2E 测试是什么？说白了，就是用一个自动化工具去模拟真实用户的操作：打开浏览器、输入账号密码、点击按钮、填写表单、提交订单，然后断言页面上出现了预期的结果。它跟单元测试（Unit Test）和集成测试（Integration Test）最大的区别在于，E2E 是从用户视角出发，跑的是完整链路，而不是某个函数、某个模块。

它解决什么问题？最核心的一点：在发版前用机器代替人力完成重复性回归。以前需要人工花半小时点完的流程，现在自动跑一遍只要几分钟，而且每次执行的步骤完全一致，不会漏点、不会手抖、不会因为“今天状态不好”而漏测。

1.2 什么人适合读这篇文章

如果你符合下面任何一条，这篇文章应该对你有用：

• 前端开发或测试工程师，项目已经有一定规模，手工回归开始变得吃力
• 团队正在做自动化测试体系，但不知道 E2E 从哪下手
• 你听说过 Playwright、Cypress 但一直没实际用过，想看看真实项目里怎么落地
• 你已经在写单元测试，但发现单元测试覆盖不到“用户真实操作链路”这类场景

我默认读者有一定的编程基础，至少写过 JavaScript 或 TypeScript，了解基本的测试概念。如果你完全没有写过自动化测试，也没关系，后面涉及的代码我都会解释意图，你照着敲也能跑起来。

2. 框架选型：Playwright、Cypress、Selenium 怎么选

2.1 主流框架对比

我在选型阶段对比了三个主流方案：Selenium、Cypress、Playwright。说实话，Selenium 在自动化测试领域算老前辈了，但它主要强在兼容多种语言和多种浏览器，上手复杂度偏高，而且执行速度偏慢。Cypress 的开发者体验非常好，调试工具很顺手，但它早期不支持多标签页操作，对于某些复杂场景会受限。

我最终选了 Playwright，原因是它契合我项目的实际需求：支持 Chromium、Firefox、WebKit 三大内核，能并行执行测试用例，自动等待机制很聪明，不需要我手动 sleep 到处凑数。当然，这不是说 Playwright 就一定比其他框架好，选型要看自己的项目场景。

我画了一张对比表方便你快速定位：

提示：如果你是刚接触E2E，我建议直接把目光放在 Cypress 和 Playwright 之间。Selenium 不是不好，而是相比之下，前两者在现代前端项目里的体验明显更好。

2.2 为什么最终选择了 Playwright

除了对比表里的优势，还有一个很实际的原因：Playwright 的codegen命令可以录制操作并生成代码。当时我手里有一堆需要覆盖的核心链路，如果用人工写脚本的方式一点一点写，工作量会非常大。通过录制生成初版脚本，我再在生成的代码上做重构和增强，效率提高了不止一倍。

另外，Playwright 的trace功能在我排查问题的时候帮了大忙。测试挂了以后，它会把整个操作过程的页面快照、DOM 快照、网络请求、控制台日志全部保存下来，我打开 trace viewer 就能看到当时的现场，就像看视频回放一样。对于“本地能跑，CI 挂了”这类灵异问题，这个功能真的是救命稻草。

你可以这样理解：Selenium 相当于手动挡汽车，什么都要自己控制，动力强劲但费神；Cypress 像自动挡，好上手，但有些路况（比如多标签页）会限制你；Playwright 则像一个带辅助驾驶的SUV，大部分情况自动搞定，遇到特殊路况也有足够的控制力。

2.3 安装和初始化

安装 Playwright 非常简单，如果你的项目是 Node.js 环境，两行命令就搞定：

npm init -y npm install -D @playwright/test

装完包之后还要装浏览器内核，这一步很多人会忘记：

npx playwright install

这个命令会下载 Chromium、Firefox、WebKit 三个浏览器内核。如果你只想装某一个，可以用npx playwright install chromium只装 Chromium。实际项目中我建议至少留着 Chromium 和 Firefox，跨浏览器跑一遍能发现不少样式和兼容性问题。

初始化测试目录结构可以直接用官方脚手架：

npm init playwright@latest

它会帮你生成tests/目录、playwright.config.ts配置文件，以及一个简单的示例测试。我建议你生成后直接把示例删掉，因为那只是个 hello world，真正跑项目的测试还是得自己写。

3. 测试用例设计思路：哪些场景值得写 E2E

3.1 核心链路优先，别想着全覆盖

很多团队刚开始搞 E2E，最容易犯的毛病是“什么都想测”。结果写了几百条用例，跑一次要一两个小时，维护成本高到爆炸，最后整个测试套件越来越没人敢动。

我个人建议是：E2E 不是用来替代单元测试的，它的职责是守护核心业务链路。一个功能模块内部的逻辑，交给单元测试去保护；E2E 只负责“用户能不能走通这条路”的问题。

以我做过的电商项目为例，当时划定的核心链路包括：

• 用户注册 → 登录 → 退出
• 搜索商品 → 筛选 → 查看详情 → 加入购物车
• 购物车结算 → 填写收货地址 → 选择支付方式 → 支付成功
• 个人中心 → 查看订单列表 → 查看订单详情

这里面每一条都是“假如它挂了，用户会立刻感知并且想骂人”的流程。至于商品详情页里某个按钮的颜色是否正常、某个文案是否多了个空格，这类细节不属于测试重点，交给视觉回归工具或人工抽查就好。

3.2 每条用例保持独立性

E2E 用例的一个隐性要求是：尽量独立，不要相互依赖。比如“添加购物车”这个用例，不应该依赖“登录”用例先跑成功。我见过有团队把整条链路写在一个巨型测试里：登录、搜索、下单、支付全在一个test里，断言也是连在一起的。一旦中间某一步挂了，后面全部失败，排查问题的时候傻傻分不清是哪一环出的问题。

更合理的做法是：通过test.beforeEach或test.beforeAll把前置条件准备好。例如：

test.beforeEach(async ({ page }) => { // 打开登录页 await page.goto('/login'); // 执行登录操作 await login(page, 'test_user', 'test_password'); });

这样每条测试用例执行前都会先登录，用例之间互不干扰，挂了也能快速定位是哪条独立用例的问题。

3.3 数据准备和清理策略

E2E 测试跑完以后，如果数据不清理，下次再跑可能就会遇到“用户已存在”“订单号重复”这类问题。这是设计测试数据时最需要留意的地方。

我的做法是，在环境层面保证测试数据的可控性：

• 固定一套测试专用账号（比如e2e_user_01），密码写死在环境变量里，不暴露真实用户数据
• 数据库或后端 API 提供清理接口，测试结束后通过接口把产生的脏数据重置
• 或者，测试数据直接用 API 预置，不走 UI 一步步创建（走 UI 太慢了，而且会引入不必要的依赖）

如果你还没有专门的测试环境，也可以采用“每次测试生成随机后缀”的策略。比如用户名用e2e_${Date.now()}，测试跑完虽然会留下垃圾数据，但至少不会因为数据重复而撞车。

3.4 断言的取舍

写 E2E 断言时，我常用的原则是：断言用户能看到的东西，不要断言实现细节。比如：

• 应该断言页面上出现了“订单提交成功”这个文案，而不是断言某个内部函数返回值是true
• 应该断言 URL 跳转到了/order/success，而不是断言某个 Vuex/Redux 状态变化了

这能保证你的测试聚焦在用户价值上，而不是绑定死内部实现。内部实现一改，测试也跟着改，那维护成本会直线上升。

4. 实操：从录制到断言的完整实现

4.1 用 codegen 录制初版脚本

Playwright 提供了一条非常实用的命令，可以直接打开浏览器录制操作，并生成对应的测试代码：

npx playwright codegen

运行后会弹出一个窗口和一个 Inspector 面板。你可以一边在浏览器窗口里操作，一边看到代码实时生成。比如你在页面上点击了“搜索框”，代码就会生成类似await page.getByPlaceholder('搜索商品').click();这样的语句。

说一下我当时录制过程中总结的经验：

• 录制前先把浏览器窗口调整到合适尺寸，避免后面选择器因为视图尺寸变化而失效
• 一些动态加载的内容（比如下拉菜单、弹窗），录制完要多跑几遍确认稳定性
• 录制的代码只是个起点，不要期望它能直接用，因为很多地方会缺少断言、缺少等待条件

4.2 一个完整的登录测试示例

录完初版脚本之后，我会把代码整理改造，并补充必要的断言。这里给出一个登录用例的完整示例：

import { test, expect } from '@playwright/test'; test('用户可以使用正确的账号密码登录', async ({ page }) => { // 打开登录页 await page.goto('https://example.com/login'); // 输入账号 const usernameInput = page.getByLabel('用户名'); await usernameInput.fill('e2e_user_01'); // 输入密码 const passwordInput = page.getByLabel('密码'); await passwordInput.fill('Test@123456'); // 点击登录按钮 await page.getByRole('button', { name: '立即登录' }).click(); // 断言跳转到了首页 await expect(page).toHaveURL(/\/home/); // 断言页面上出现了用户名或欢迎信息 await expect(page.getByText('欢迎回来，e2e_user_01')).toBeVisible(); });

这里最关键的是page.getByLabel('用户名')和page.getByRole('button', { name: '立即登录' })这种查询方式。Playwright 官方推荐基于 ARIA 角色和可访问性标签定位元素，这样写出来的选择器对有障碍用户友好，同时也不会因为 CSS 类名改变而挂掉。

我以前用过很长一段时间的page.fill('#username')，后来发现维护起来很痛苦——前端重构一下类名，测试全挂了。换成getByLabel和getByRole之后，大部分选择器不再依赖具体的样式类名。

4.3 配置 baseURL 和项目的 config 文件

为了让测试代码更简洁，playwright.config.ts里可以配置baseURL，这样page.goto('/login')就会自动拼上域名前缀：

import { defineConfig, devices } from '@playwright/test'; export default defineConfig({ testDir: './tests', timeout: 30000, retries: 2, use: { baseURL: 'https://example.com', headless: true, screenshot: 'only-on-failure', trace: 'on-first-retry', }, projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'] }, }, { name: 'firefox', use: { ...devices['Desktop Firefox'] }, }, ], });

几个关键配置我解释一下：

• testDir：测试文件存放的目录
• timeout：单个测试的最大执行时间，默认是 30 秒，如果你有大量耗时操作可以调大
• retries：失败重试次数。我设置为 2，因为有些偶发性的网络抖动或动画时序问题，重试一次就能过
• trace：设置成on-first-retry，表示第一次失败后记录 trace，方便排查
• headless：无头模式执行，适合 CI 环境；本地调试时我通常改成false，可以看到浏览器操作

4.4 处理弹窗和多标签页

电商项目里很常见的一个场景是支付页面跳到第三方收银台，这就涉及多标签页操作。这是 Cypress 过去比较头疼的场景，但 Playwright 处理起来很轻松：

const [popup] = await Promise.all([ page.waitForEvent('popup'), page.click('text="去支付"'), ]); await popup.waitForLoadState(); await popup.getByRole('button', { name: '确认支付' }).click();

这里用了Promise.all来同时等待点击动作和新页面打开事件，避免竞态条件。如果你直接page.click然后再page.waitForEvent('popup')，很容易错过事件，这是新手最常踩的坑。

5. 难点突破：与接口 Mock 和网络请求打交道

5.1 拦截真实请求，返回预设数据

E2E 测试最让人头疼的问题之一，是它依赖的外部环境不确定。比如你测的是一个订单列表页，但后端接口偶尔超时、偶尔返回报错，你的测试就会间歇性失败。这时候就需要 API Mock。

Playwright 提供了page.route()接口来拦截网络请求：

await page.route('**/api/orders', route => { route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ code: 0, data: [ { id: 1, title: '测试订单A', status: 'pending' }, { id: 2, title: '测试订单B', status: 'paid' }, ], }), }); }); await page.goto('/orders'); // 断言页面渲染出了两条订单数据 await expect(page.getByText('测试订单A')).toBeVisible(); await expect(page.getByText('测试订单B')).toBeVisible();

用这种方式，你完全控制接口返回的数据，不依赖后端环境是否稳定。这也是为什么我建议E2E 用例中，外部接口尽量 Mock，关键还是验证前端页面的交互逻辑。

5.2 真实请求与 Mock 的取舍

不过，如果一个 E2E 用例从头到尾全是 Mock 数据，那它也就退化成“前端组件测试”了，失去了验证全链路的意义。我会根据自己的验证目的做取舍：

• 如果核心目的是验证页面交互（点击 → 渲染 → 跳转），Mock 接口数据，效率高、稳定
• 如果核心目的是验证核心业务链路（比如用户注册后确实能创建订单），则走真实接口，但这需要确保测试环境后端是可用的

还有一个折中的做法：只在特定场景 Mock 掉不可控的第三方服务，比如支付回调、短信验证码，而内部业务接口保持真实调用。这样既保证了链路完整性，又避免了外部依赖造成的不稳定。

5.3 处理 Loading 和异步请求的等待

自动化测试里最烦人的问题，就是元素还没加载出来，测试就开始点击了。Playwright 的自动等待机制能解决大部分问题，但我还是会在关键时刻用显式等待：

// 等待某个接口响应返回 const responsePromise = page.waitForResponse('**/api/user/info'); await page.click('text="刷新"'); await responsePromise;

或者等某个元素出现：

await expect(page.getByText('加载完成')).toBeVisible({ timeout: 10000 });

注意：不要在代码里到处塞page.waitForTimeout(3000)，这种固定等待会让测试变慢，而且并不稳定。网络快的时候不需要等那么久，慢的时候又可能不够用。正确做法是等待某个具体的条件达成。

6. 项目落地经验：从 0 到 1 的完整流程

6.1 分阶段推进，不要想一步到位

如果你的团队也是第一次搞 E2E，我强烈建议分阶段推进。我当时的时间安排大约是：

第一阶段（前 3 天）：搭框架、定规范、配置 CI。这一步的目标是让一条最简单的测试用例能在本地和 CI 上自动跑通。

第二阶段（第 4-7 天）：覆盖业务的核心链路，数量控制在 10 条左右。不求多，但求每一条都是真正有价值的。

第三阶段（第 8-14 天）：补充边界场景和异常路径，比如“输入错误密码登录失败”“未登录直接访问订单页被拦截”。同时把外部接口 Mock 的策略稳定下来。

6.2 CI 集成的要点

E2E 测试如果不接入 CI，价值会打折扣。我用的 CI 环境是 GitHub Actions，配置流水线时有几个关键点：

• 缓存依赖和浏览器内核：npx playwright install每次全量下载浏览器会很慢，建议把浏览器缓存到 CI 的缓存目录，第二次跑就快很多
• 并行执行：多个测试文件默认就是并行跑的，CI 机器如果是多核，可以增加workers数量
• 上传测试报告：失败时把playwright-report目录作为 CI 的 artifact 上传，方便团队其他成员下载查看

这是 GitHub Actions 的一段核心配置：

name: e2e-tests on: push: branches: [main] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npm ci - run: npx playwright install --with-deps chromium - run: npx playwright test - uses: actions/upload-artifact@v4 if: failure() with: name: playwright-report path: playwright-report/ retention-days: 7

6.3 报告和通知：让失败第一时间暴露

E2E 跑完以后，如果没人看报告，那等于没跑。我在 CI 里加了 Slack 通知，失败的时候直接推到团队频道。Playwright 的 HTML 报告本身非常直观，包含执行时间、失败截图、每个步骤的操作记录，团队里非技术的角色也能看明白是哪里出了问题。

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

7.1 Element 定位失败

场景：测试跑着跑着突然报element not found，手动去页面上看元素明明存在。

排查思路：

• 先看是否发生了元素懒加载或异步渲染。用await expect(...).toBeVisible({ timeout: 10000 })替代立即断言
• 检查是否有 iframe 嵌套。Playwright 里需要切换到frameLocator才能操作 iframe 内部元素
• 检查是否是弹窗遮罩挡住了点击。可以用page.bringToFront()或先关闭弹窗再操作

7.2 本地能过，CI 上挂

这是最让人脑壳疼的问题，我也遇到过好几次。常见原因有三类：

• 环境变量不同。本地.env配置了测试账号，但 CI 上没有配置或配置了另一个环境。解决办法是：统一从 CI secrets 或环境变量中读取，不要在代码里硬编码
• headless 模式差异。无头浏览器和有头浏览器的渲染在某些细节上有差异，比如字体加载、CSS 动画、窗口尺寸。建议 CI 和本地都统一用 headless 跑，并固定 viewport 大小
• 网络权限或 cookie 问题。某些域名在 CI 环境无法访问，或者跨域 cookie 没有设置上。在配置里设置storageState提前预置登录态

7.3 测试执行时间太长

如果套件跑起来要几个小时，肯定不正常，应该检查以下方面：

• 是否有大量不必要的waitForTimeout
• 是否很多用例都在做重复的前置操作（比如每条用例都走一遍注册流程）
• 是否没有充分利用并行执行。Playwright 默认按测试文件级别并行，如果所有用例都写在一个文件里，就退化成串行执行了
• 改用test.beforeEach缓存登录状态，或者用storageState跳过重复登录步骤

7.4 稳定性问题：什么是 Flaky Test

Flaky Test 指的是那些“有时候过，有时候挂，没有任何代码改动”的测试。这是 E2E 测试最大的敌人，必须认真对待。

我的实践经验是：一旦发现 flaky test，立刻修，不要拖。原因很简单，如果一个经常闪红的测试没有被及时处理，团队很快就会对这套测试失去信任，最后没人再关心红灯绿灯，这套自动化体系就名存实亡了。

常见的修复方向：

• 检查是否有复杂动画或异步请求未等待。用expect的自动重试机制代替手动sleep
• 检查是否有外部依赖（比如天气组件、广告位接口）导致稳定结果变化，考虑 Mock
• 检查测试之间是否存在共享状态。如果两个测试往同一个账号下写了不同数据，后一个测试可能读到前一个的残留数据

8. 几个值得尝试的高级技巧

8.1 把登录固化到 storageState

如果一条用例需要在登录状态下操作，每次都走 UI 登录流程很浪费时间。Playwright 支持提前登录一次，然后保存浏览器的存储状态：

npx playwright codegen --save-storage=auth.json

手动登录一次后，把auth.json拿到测试配置里：

test.use({ storageState: 'auth.json' });

这样每条用例启动的时候，浏览器直接带着登录态的 cookie 打开，省掉了登录步骤。跑 20 条用例，能省下至少五六分钟。

8.2 用 Trace Viewer 定位失败现场

当测试失败时，Playwright 会自动生成 trace 文件。你可以跑：

npx playwright show-trace trace.zip

打开 Trace Viewer 后，你能看到测试每一个动作对应的页面截图、DOM 快照、网络请求、控制台日志、甚至时间线上的性能数据。我排查“CI 上偶发失败”这类问题，几乎全靠它。

8.3 视觉回归：把 E2E 和截图对比结合

如果你的产品对 UI 还原度要求很高（比如 C 端营销页、设计走查严格的项目），可以在 E2E 的基础上引入toHaveScreenshot()：

await expect(page).toHaveScreenshot('home-page.png');

Playwright 会维护一个基准图片，后面每次跑的时候做像素级对比。第一次跑会生成基准图，之后如果 UI 有变化，测试会失败并展示对比结果，方便判断是有意修改还是意外回归。

提示：截图对像素级差异很敏感，字体渲染在不同操作系统上可能有差异。如果要团队多人协作维护，记得统一跑测试的环境（至少统一操作系统和浏览器版本），否则会产生大量噪音。

9. 写在最后的一点体验

E2E 测试这个东西，很多时候给人第一感觉是“难”“不稳定”“维护成本高”。这几种印象我都体会过，但一路实操下来，我最大的感受是：E2E 测试难的不是写脚本，而是设计哪些场景值得测、怎么保证稳定、怎么让团队愿意持续维护它。

你如果刚开始尝试，不要一上来就追求庞大的用例数量。先挑一条最核心、最能代表项目价值的业务链路，用 Playwright 把它跑通，然后看看效果——那种“机器帮你众享流程，你只需要等结果”的感觉，会给你继续往下推进的信心。

最后分享一个我在时间管理上的心得：E2E 用例不是写完就好了，它需要持续维护。前端交互变了、文案改了、接口返回结构调整了，测试都可能失效。我给自己的节奏是，每 1-2 周抽半天处理一下最近的失败用例，更新选择器和断言。这样维护成本保持在可控范围内，测试套件也不会慢慢腐烂掉。

如果你在落地过程中遇到了什么有意思的问题，或者发现某个场景很难稳定处理，欢迎一起交流。这类经验往往是项目现场最值钱的东西。