端到端测试实战：从测试金字塔到Playwright与CI集成

如果你在任何一个做业务系统的团队里待过，大概率经历过这样的场景：联调都通了，单元测试也全绿，结果一上线，用户在页面上点了几下就报错。问题往往不在某个单独的函数，而在一条完整的业务链路。这种问题，单测测不出来，靠人肉回归又累得不行。于是大家开始补 e2e——端到端测试。

e2e 测试模拟真实用户操作，从打开页面、点击按钮、填写表单，到提交请求、等待响应、验证结果，全程走完一条业务链路。它能解决的问题很简单：在发布之前，用机器代替人把最关键的用户路径完整跑一遍。适合所有维护中大型 Web 应用的测试工程师、前端开发、全栈开发，以及那些刚接手一个项目、想快速建立安全网的团队。

这篇文章不讲花架子，我从为什么要做 e2e、框架怎么选、环境 profile 怎么配，到第一个用例怎么写、CI 怎么接，一步一步还原我实际搭建 e2e 测试项目的完整过程。里面所有的坑都是我踩过的，配置也是能直接拿来改的。

1. 端到端测试到底是什么：不是“跑一遍页面”这么简单

1.1 从“测试金字塔”说起：三层测试各自管什么

很多人一听 e2e 就觉得是“用自动化脚本打开浏览器点一点”，这个理解太浅了。要做明白 e2e，先要理解它在整套测试体系里的位置。

经典的测试金字塔分三层：单元测试、集成测试、端到端测试。我用做饭来类比。单元测试相当于检查每一种食材：肉有没有变质、土豆有没有发芽，对应到代码里就是单个函数、单个组件的行为验证，跑得快、定位准。集成测试相当于检查灶台和锅铲配合是否顺畅：火够不够大、锅会不会粘底，对应到代码里就是模块之间的交互、接口之间的调用。端到端测试则是把一整道菜从头到尾做完、端上桌、吃一口，确认它真的能吃。它不关心中间用了哪个锅、撒了多少盐，只关心用户拿到手的结果对不对。

这三层各有各的价值，谁也替代不了谁。单元测试告诉你“哪块代码坏了”，集成测试告诉你“哪两个模块接不上”，e2e 测试告诉你“用户还能不能正常办成事”。如果一个项目只写 e2e，没有底层测试兜底，那每一轮回归都会变成一场灾难——一条主链路挂掉，你只能从头开始排查，完全不知道是前端、后端还是数据配置的问题。反过来，如果只写单测和集成测试，不做 e2e，那就有我开头说的那种情况：每个零件都合格，组装起来却跑不动。

所以我的建议是：e2e 必须做，但不要贪多。它解决的是“最核心的用户旅程是否可用”这个问题，而不是把所有功能都覆盖一遍。后面我会详细说怎么挑用例。

1.2 e2e 测试解决的核心问题与设计思路

e2e 测试最典型的应用场景有三类。第一类是核心交易链路，比如电商的下单支付流程、SaaS 系统的创建项目到邀请成员流程，这类链路一断就是事故。第二类是跨系统交互，比如前端调用第三方登录、支付网关回调，单测里全是 mock，真实环境根本没法覆盖。第三类是高频使用的核心页面，比如工作台首页、报表页，这些页面交互复杂，纯手工回归每次都要点半天，且容易漏。

设计 e2e 用例时，我始终遵循一个原则：只测用户能感知的业务结果，不测实现细节。比如登录流程，我关心的是输入账号密码之后能不能进入首页、能不能看到自己的昵称，而不关心内部调用了哪个接口、用了什么加密算法。这样做的好处是测试更稳——底层重构了，只要用户看到的结果没变，用例就不用改。

还有一个容易被忽略的点：e2e 用例要按用户视角命名，不要按功能模块命名。比如“用户购买成功”比“测试支付接口”好得多。因为 e2e 测的是业务价值，不是技术指标。当你把用例清单列出来，它应该像一份精简版的验收标准，而不是一份接口文档。

2. 技术选型：e2e 框架怎么挑才不踩坑

2.1 主流 e2e 框架横向对比

做 e2e 绕不开工具选型。目前社区里主流的选择就三个：Selenium、Cypress、Playwright。我直接给出我实测下来的对比结论。

Selenium 是老牌选手，生态成熟，但它的设计思路停留在 WebDriver 时代，自动等待机制不够聪明，测试代码里到处是显式等待和 sleep，维护成本很高。Cypress 胜在开发体验好，资料多，但它的架构决定了它在多标签页、跨域场景上有先天缺陷，如果你要测的东西涉及第三方跳转，会很痛苦。

2.2 为什么我最终选择了 Playwright

我现在的团队最终用的是 Playwright，原因有三个。

第一，自动等待机制做得好。Playwright 在点击、输入、断言之前，会自动检查元素是否可见、是否可编辑、是否被遮挡，不满足条件就一直等，直到超时。写用例的时候基本不用关注页面加载了几毫秒、接口响应快不快，这直接砍掉了大量 flaky 测试的根源。

第二，调试工具实在太香了。Playwright 的 Trace Viewer 可以录制整个测试过程的页面快照、DOM 快照、网络请求、控制台日志，用例挂了之后，点开 trace 像看电影一样回放每一步操作。排查问题的时间从几小时缩短到几分钟。

第三，网络拦截能力原生支持。e2e 测试最怕碰到支付、短信、验证码这种真实环境里没法反复触发的依赖，Playwright 的page.route()可以拦截并 mock 网络请求，灵活度很高。

选型建议：如果是全新的 Web 应用项目，优先 Playwright；如果团队已经深度绑定 Cypress 生态，没必要强行迁移，但新项目别再上了；Selenium 除非有特殊需求（比如必须兼容 IE），我不推荐新项目选择。

3. 环境与 Profile 配置：e2e 测试的第一步，也是最大的坑

3.1 为什么环境配置决定 e2e 成败

很多团队把 e2e 写起来之后才发现，真正让测试跑不稳的不是用例本身，而是环境。e2e 测试要访问真实的页面、真实的接口、真实的数据，那它就需要一个“能跑得通的环境”。

这里的核心概念叫测试环境隔离。如果所有开发者共用一套环境，A 同学改了个数据、B 同学跑了个清理任务，你的用例就会莫名其妙挂掉。所以做 e2e 的第一步，不是写用例，而是确定“在哪跑、用什么数据、依赖哪些外部服务”。

我常用的做法是：准备一套独立的 e2e 测试环境，里面用专用测试账号、专用测试数据、可被反复重建的数据库。所有依赖的外部服务（短信、支付、OSS）在 profile 配置里全部指向 mock 服务，确保测试可控。

3.2 profile1：一套测试环境配置的解剖

“e2e profile1”这个说法，指的就是第一套测试环境配置。不同团队会有多个 profile，比如profile1对应日常开发测试环境、profile2对应预发布环境、profile3对应线上冒烟环境。一套 profile 本质上是把环境和用例解耦：用例代码只读配置，不硬编码任何环境相关的地址。

我给出一个典型的e2e/.env.profile1配置文件：

E2E_BASE_URL=https://profile1.example.com E2E_USERNAME=e2e_user_01 E2E_PASSWORD=Test@12345 E2E_MOCK_PAYMENT=true E2E_MOCK_SMS=true E2E_API_BASE_URL=https://profile1-api.example.com E2E_TRACE=on

对应地，在playwright.config.ts里读取这个文件：

import { defineConfig, devices } from '@playwright/test'; import dotenv from 'dotenv'; dotenv.config({ path: `e2e/.env.${process.env.E2E_PROFILE || 'profile1'}` }); export default defineConfig({ testDir: './e2e/tests', timeout: 30_000, retries: 2, use: { baseURL: process.env.E2E_BASE_URL, trace: process.env.E2E_TRACE === 'on' ? 'on' : 'off', screenshot: 'only-on-failure', }, projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'] } }, { name: 'firefox', use: { ...devices['Desktop Firefox'] } }, ], });

这样做的核心价值在于：测试用例本身不感知环境差异。同样的代码，切换E2E_PROFILE=profile2就能指向预发布环境。这套思路如果你之前没实践过，强烈建议直接抄。

3.3 配置管理实战：不把密钥写进仓库

带上配置就绕不开安全问题。E2E_PASSWORD=Test@12345这种测试环境密码还好，但如果 profile 里涉及真实环境的凭据、Token，绝对不能明文提交到 Git 仓库。

我推荐的做法是分层管理。基础配置放.env.profile1并提交到仓库；敏感信息通过 CI 的 Secret 或运行时的环境变量注入；所有配置里只允许放“测试环境专用”的弱凭据，绝不复用生产凭据。CI 里运行 e2e 时，用export注入：

export E2E_PROFILE=profile1 export E2E_ADMIN_TOKEN=${{ secrets.E2E_ADMIN_TOKEN }} npm run e2e

还有一个细节：多个 profile 配置之间的差异要尽量小。我见过有的团队为每个环境复制一整份配置，结果改了一个默认超时时间，几个环境的配置全要跟着改。正确的做法是把公共项收敛到默认值，profile 文件里只保留真正有环境差异的项。

4. 实操：从零搭建一个可直接复用的 e2e 测试项目

4.1 项目初始化与依赖安装

现在进入实际操作。假设你有一个前端项目，无论 React、Vue 还是 Nuxt，都适用。第一步，在项目根目录初始化 e2e 目录：

mkdir e2e cd e2e npm init -y npm install -D @playwright/test dotenv npx playwright install

npx playwright install会下载 Chromium、Firefox、WebKit 浏览器内核，首次执行时时间较长。这里有个经验：在 CI 环境里安装的时候，加上--with-deps参数，它会自动安装浏览器运行依赖的系统库，省得你在干净环境里一个个排查缺库的问题。

4.2 编写第一个端到端测试用例

我以一个最典型的“登录 + 下单”流程为例，展示完整用例。先建文件e2e/tests/order.spec.ts：

import { test, expect } from '@playwright/test'; test('用户能够完成登录并成功下单', async ({ page }) => { // 打开登录页 await page.goto('/login'); // 填写账号密码 await page.getByLabel('用户名').fill(process.env.E2E_USERNAME!); await page.getByLabel('密码').fill(process.env.E2E_PASSWORD!); // 提交登录 await page.getByRole('button', { name: '登 录' }).click(); // 断言：登录成功后能看到用户昵称 await expect(page.getByText('欢迎回来，e2e_user_01')).toBeVisible(); // 进入商品详情页 await page.goto('/product/10001'); await page.getByRole('button', { name: '加入购物车' }).click(); // 去购物车结算 await page.goto('/cart'); await page.getByRole('button', { name: '去结算' }).click(); // 提交订单 await page.getByRole('button', { name: '提交订单' }).click(); // 断言：订单提交成功，出现在订单列表中 await expect(page).toHaveURL(/\/order-success/); await expect(page.getByText('订单提交成功')).toBeVisible(); });

这一段代码里有几个关键细节值得展开说明。

第一，优先使用getByRole和getByLabel，不要用page.locator('.btn-submit')。前者模拟的是真实用户感知的方式：按钮在无障碍树里的角色、表单控件的标签文字。这样写的好处是，当开发把 CSS 类名改掉的时候，测试不会跟着崩。我见过太多项目因为重构了样式类名，e2e 用例集体飘红，其实功能完全没变，纯粹是选择器太脆弱。

第二，断言一定要落在用户可见的业务结果上。比如登录后检查“欢迎回来，e2e_user_01”可见，而不是去等某个网络请求返回成功。用户关心的是界面状态，不是网络状态。断言界面状态能让用例更稳定、更有业务意义。

第三，用环境变量注入测试账号，不要硬编码。process.env.E2E_USERNAME保证了同一份代码在不同 profile 下可以用不同账号执行。

4.3 运行测试与结果解读

写好用例之后，通过命令行运行。我在package.json里预置了几个脚本：

{ "scripts": { "e2e": "playwright test", "e2e:profile1": "E2E_PROFILE=profile1 playwright test", "e2e:profile2": "E2E_PROFILE=profile2 playwright test", "e2e:report": "playwright show-report" } }

运行方式：

npm run e2e:profile1

首次运行建议加--headed参数，带界面执行，这样你能亲眼看到浏览器做了什么。调试单个用例用--grep配合关键字：

npx playwright test --grep "下单"

跑完之后，Playwright 会在playwright-report/目录生成 HTML 报告。打开报告能看到每个用例的执行耗时、每一步操作的截图、DOM 快照和网络请求记录。如果用例失败，报告里会明确标记失败步骤和断言差异。这个报告一定要在 CI 里作为 artifact 留存，排查线上问题靠它非常高效。

4.4 并行执行与分片：不浪费每一台机器

e2e 测试天生适合并行。Playwright 默认在多个 worker 进程里并发跑用例。但并发会带来一个隐患：多个用例同时操作同一批测试数据，可能互相干扰。我在项目里踩过这个坑，两个用例同时在购物车里加同一个商品，结果数量翻倍，断言失败。

解决方案有两个。一是用例之间做好数据隔离，每个用例创建自己的测试数据；二是用test.describe.configure({ mode: 'serial' })把有共享状态的用例组串行执行。更精细的做法是利用 Playwright 的 shard 机制，在 CI 里把用例分片到多台机器并行跑，每台机器只跑一部分，整体耗时大幅缩短。我在 CI 里见过一个 400 条用例的 e2e 套件，分片到 8 台机器后，从 40 分钟压缩到 6 分钟，非常值。

5. 常见问题与排查技巧实录：那些让测试“飘红”的坑

5.1 不稳定测试（flaky test）怎么处理

e2e 测试最大的痛点就是不稳定。今天跑绿，明天跑红，重新跑一遍又绿了，这种用例比没有用例还可怕，因为大家会逐渐不再信任测试结果。

不稳定最常见的根源有三个：等待不足、数据污染、外部服务抖动。

等待不足的解决思路不是无脑加sleep(5000)，而是用 Playwright 的自动等待机制。toHaveURL、toBeVisible这些断言自带重试等待，你要做的是把断言写在正确的时机。我看到很多人习惯在点击之后立刻waitForTimeout(2000)，这完全没必要，正确做法是直接写断言，Playwright 会一直等到元素出现或超时。

数据污染的问题我会单独讲。外部服务抖动，比如测试环境依赖的短信服务挂了，我的建议是：所有不可控的外部依赖在 profile 里一律 mock。短信验证码、第三方登录、支付回调，都不该在 e2e 环境里真实触发。你可以在测试里用page.route()拦截请求并返回假数据，让被测系统的前后端链路照常走，但外部世界一点都感知不到。

注意：mock 外部服务之前，一定要先确认被测系统的代码能接受 mock 数据。有的系统在业务代码里写死了第三方返回的加密签名字段，mock 得不完整反而会让流程走不下去。这种就需要在 profile 配置里给被测后端也开一个 mock 模式，两边对齐。

5.2 元素定位的坑与经验

元素定位是 e2e 新手遇到的第一个大坑。常见的错误有三类：依赖 class 名、依赖文本内容匹配太弱、依赖父子层级结构的脆弱链式选择器。

我现在给自己团队定的规矩是：前端代码里为 e2e 单独埋><button>import { request } from '@playwright/test'; export async function createTestUser() { const ctx = await request.newContext({ baseURL: process.env.E2E_API_BASE_URL, extraHTTPHeaders: { 'X-E2E-TOKEN': 'test-token' }, }); const res = await ctx.post('/e2e/users', { data: { username: `user_${Date.now()}` }, }); return res.json(); }

第二步，用唯一前缀隔离数据。每个用例创建的数据都带上时间戳或随机数，比如user_1723456789。断言的时候就断言这个唯一标识，不会和其他用例的数据撞车。

第三步，用例结束做清理。在test.afterEach中删除测试中创建的订单、用户或购物车记录。有些团队因为清理逻辑复杂就省略这一步，导致测试环境的垃圾数据越积越多，最终拖垮整个环境。我的经验是：哪怕清理不彻底，也一定要做，环境里积压的数据通常比冷启动更让人头疼。

5.4 调试实战：Trace 回放怎么用

Playwright 的 Trace 是排查挂掉用例的神器。配置里开启trace: 'on-first-retry'，第一次跑挂后，第二次重试时会自动录制完整 trace。

用法很简单：测试跑完，执行npx playwright show-trace test-results/xxx.trace.zip，会打开一个可视化页面。左侧是时间线，中间是页面截图，右侧是控制台日志和网络请求列表。你可以逐帧回放每一步操作，看到页面在哪个时刻发生了什么。有一次我排查一个只在线上偶发的 bug，本地死活复现不了，靠 trace 发现是某个接口在 900ms 之后才返回，导致页面渲染时序错乱，而测试环境一直比较慢所以掩盖了问题。

排查 flaky 用例的流程我建议固化下来：挂掉之后先看 trace，确认是页面渲染问题还是断言时机问题；再看网络请求 tab，确认接口有没有异常返回值；最后看控制台日志，确认有没有前端报错。八成的问题在这三步之内能找到根因。

6. 团队落地 e2e 测试：CI 集成与用例治理

6.1 CI 集成：让 e2e 每天自动跑一遍

e2e 测试只有跑在 CI 里才有价值。本地跑得再勤，也保不住合并代码时引入的回归。我给出一个可直接复用的 GitHub Actions 配置：

name: e2e on: push: branches: [main] pull_request: branches: [main] schedule: - cron: '0 2 * * *' jobs: e2e: runs-on: ubuntu-latest strategy: fail-fast: false matrix: shard: [1, 2, 3] steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - name: Install dependencies run: npm ci - name: Install Playwright browsers run: npx playwright install --with-deps - name: Run e2e tests with profile1 run: npm run e2e:profile1 env: E2E_PROFILE: profile1 E2E_ADMIN_TOKEN: ${{ secrets.E2E_ADMIN_TOKEN }} - name: Upload HTML report if: always() uses: actions/upload-artifact@v4 with: name: playwright-report-${{ matrix.shard }} path: playwright-report/ retention-days: 14

这里有几个关键设计。matrix.shard把测试分成三份并行跑；fail-fast: false保证一个分片挂了不影响其他分片继续跑；if: always()确保即使测试失败也会上传报告。我把 PR 触发放在这里，但不建议在每次 PR 都跑全量 e2e，因为很有可能会成为团队的负担。更实际的策略是：PR 阶段只跑受影响的冒烟用例，每天凌晨定时跑全量用例，早上来的时候查报告。

6.2 用例治理与避坑清单

随着时间推移，e2e 用例会越来越多，如果没有治理机制，整个套件会变成一个谁也不敢动的黑盒子。我总结了几条实测有效的治理原则。

• 用例必须可追溯：每条用例都要能对应到一条具体的用户故事或需求。写用例的时候在标题里标明需求编号，比如[REQ-208] 用户修改收货地址后能正常结算。
• 超标即治理：单条用例执行时间超过 60 秒就要约谈。e2e 用例应该是快路径验证，不是全流程压测。如果一条用例要跑两分钟，多半是里面混了太多不稳定因素。
• 不能有跳过逻辑：用例里不要写“如果 A 条件不满足就跳过”的逻辑，这会掩盖真实的问题。跳过越多，保护网越薄。
• 定期清理重复用例：两个用例覆盖同一核心路径，只留一个。e2e 是慢的、贵的测试，不是做得越多越好。

最后再补一个经验：e2e 用例量级控制在 50 条以下比较健康。超过这个量级，维护成本会显著上升。你不需要让 e2e 覆盖所有功能，它只需要守护住最关键的那几条业务生命线。剩下的覆盖，靠单元测试和集成测试去补。

我个人在实际操作中的体会是：e2e 测试的建设更像是在给团队买保险，前期投入肉眼可见地大，收益又不像上线新功能那样立竿见影。但它真正发挥作用的时候，往往是发布前拦住了一个线上事故、或者线上出了问题时十几分钟就定位了根因。那个瞬间你会觉得，前面所有折腾配置、治理数据的功夫都值了。如果你们团队还在犹豫要不要上 e2e，我的建议很简单：先把登录、下单、创建项目这三条核心路径跑起来，配好 profile1 环境和 CI，剩下的，边用边补。