1. 从“e2e”说起端到端测试到底在测什么第一次看到“e2e”这个词很多人会以为是某个新框架的缩写或者某个内部项目的代号。其实它就是end-to-end的缩写中文叫“端到端”。在软件研发语境里e2e 测试指的是从用户真实使用路径出发把整个系统当成一个黑盒验证从入口到出口的完整链路是否按预期工作。它不关心某个函数写得漂不漂亮也不关心某个接口的返回字段是不是符合文档它只关心一件事——用户点下去之后最终结果对不对。我做了十多年一线研发和测试见过太多团队在单元测试覆盖率 90% 的情况下上线依然翻车。原因很简单单元测试测的是“零件”e2e 测的是“整车”。零件都好装在一起未必能跑。e2e 的价值就在于它把前端页面、网关、业务服务、缓存、数据库、消息队列、第三方依赖全部串起来用真实或接近真实的操作路径去跑一遍。跑通了你才敢说“这个功能能交付”。那 e2e 适合谁来关注三类人最需要前端/全栈工程师因为你们最接近用户操作路径测试开发工程师因为 e2e 框架选型和稳定性治理是你们的核心战场技术负责人和 DevOps因为 e2e 要不要进 CI、卡不卡发布门禁直接决定团队交付节奏。哪怕你是个刚入行的新人理解 e2e 也能让你明白写代码不是目的让用户顺利完成一件事才是。最近热词里出现了一个“e2e profile1”这其实指向一个很实际的场景用不同的 profile配置档去跑同一套 e2e 用例。比如本地开发用 mock 依赖的 profile预发环境用真实依赖的 profile线上回归用只读账号的 profile。同一套脚本换一份配置就能适配不同环境这是 e2e 工程化里非常关键的一步。下面我就围绕 e2e 的整体设计、核心细节、实操落地和踩坑排查把这件事讲透。2. e2e 测试的整体设计与方案选型2.1 为什么 e2e 不能“随便写写”很多团队一开始做 e2e 的方式很朴素找个人打开浏览器点一遍截图发群里说“没问题”。这种方式在项目早期还能凑合一旦功能上到几十个页面、每天发好几次版就彻底崩了。原因有三个不可重复、不可并行、不可度量。人点一遍要半小时机器跑一遍可能只要两分钟人点会漏脚本不会人点完没有报告脚本跑完有日志和截图。所以 e2e 的第一层设计不是选哪个框架而是想清楚e2e 在交付流程里扮演什么角色。我的经验是把它分成三类定位冒烟级 e2e只覆盖最核心的 3 到 5 条主链路比如登录、下单、支付。每次提交都跑要求 5 分钟内出结果。回归级 e2e覆盖主要业务场景几十到上百条用例。每天夜间跑或者发版前跑。探索级 e2e针对新功能或高风险模块临时补充跑完即弃不纳入长期维护。这三类定位决定了你的框架选型、用例组织方式和 CI 接入策略。如果一上来就把所有场景都写成“必须每次跑”结果就是 CI 越来越慢最后没人看e2e 形同虚设。2.2 框架选型Playwright、Cypress 还是 Selenium这是被问得最多的问题。我不给绝对答案只给判断依据。先看一张对比表维度PlaywrightCypressSelenium多浏览器支持Chromium/Firefox/WebKitChromium/Firefox/WebKit部分受限全浏览器自动等待内置体验好内置体验好需手动封装多标签/多窗口原生支持支持有限支持网络拦截强route 机制强intercept需额外库语言支持JS/TS/Python/Java/.NETJS/TS多语言调试体验Trace Viewer 很香时间旅行调试依赖 IDE上手成本低低中高我个人的选择逻辑是新项目、以 Chromium 为主、团队以 JS/TS 为主优先 Playwright。它的 Trace Viewer 在排查 flaky 用例时几乎是救命工具网络拦截和自动等待也做得足够稳。Cypress 的开发者体验很好但多标签和跨域场景会让人抓狂。Selenium 适合已有大量存量用例、或者必须覆盖老旧浏览器的团队新项目不建议从零开始。至于“e2e profile1”这个热词落到选型上就是框架要支持通过环境变量或配置文件切换运行档位。Playwright 里可以用projects配置多个 profileCypress 里可以用--env或cypress.config区分。这一点在后面的实操里会详细展开。2.3 用例分层别把 e2e 写成“大号单元测试”我见过最糟糕的 e2e 用例是把每个按钮点击、每个字段校验都写成一条独立用例结果几百条用例跑两小时其中一半在测“输入框能不能输入”。这是典型的定位错乱。e2e 应该测跨系统的业务闭环而不是 UI 细节。合理的分层是这样的UI 细节交给组件测试或单元测试比如按钮禁用态、表单校验提示。接口契约交给集成测试比如服务 A 调服务 B 的字段是否匹配。业务闭环交给 e2e比如“用户注册后能成功下单并收到确认”。一条好的 e2e 用例通常对应一个用户故事。比如“新用户首次下单”这条用例会依次经过打开首页、搜索商品、加入购物车、登录/注册、填写地址、选择支付、提交订单、查看订单状态。中间任何一步断了这条用例就失败而且失败信息能直接告诉你是哪一环出了问题。3. 核心细节解析与实操要点3.1 选择器策略别让用例死在“改了个 class”e2e 用例最脆弱的环节就是选择器。前端改个样式、换个组件库div div:nth-child(3)这种选择器立刻失效。我的原则是优先用面向用户的语义选择器其次用测试专用属性最后才用 CSS/XPath。Playwright 推荐顺序getByRole比如page.getByRole(button, { name: 提交订单 })最贴近用户视角。getByLabel/getByPlaceholder表单场景很好用。getByTestId前端加>// 等待接口返回后再断言页面 await page.waitForResponse(resp resp.url().includes(/api/order/create) resp.status() 200 ); await expect(page.getByTestId(order-success)).toBeVisible();Cypress 里则用cy.intercept配合cy.wait(alias)。核心思想一致让脚本跟着系统状态走而不是跟着时钟走。3.3 测试数据管理别让用例互相污染e2e 跑多了最大的坑是数据。用例 A 创建了一个订单用例 B 去查订单列表结果查到 A 的数据断言失败。或者用例 C 删除了某个用户导致用例 D 登录失败。这类问题统称为测试数据耦合。我的做法是三条每条用例自建数据用 API 或 fixture 在用例开始前创建专属数据用例结束后清理。比如下单用例自己创建一个测试商品不依赖线上已有商品。数据带唯一标识用时间戳或 UUID 做后缀比如test_user_1710000000避免重名冲突。只读用例和写入用例分开跑只读用例可以并行写入用例串行或分片减少互相干扰。实操心得如果清理逻辑太复杂可以用“软清理”——给测试数据打标记定期用脚本批量删除。别为了清理把用例写得太重e2e 本身已经够慢了。3.4 profile 配置一套用例跑遍多环境回到热词“e2e profile1”。实际项目中我们通常需要同一套用例在多个环境跑local依赖全部 mock跑得最快用于开发自测。staging依赖真实但数据隔离用于发版前回归。prod-readonly只跑只读用例用于线上巡检。Playwright 的配置方式很直接// playwright.config.ts import { defineConfig } from playwright/test; const profiles { local: { baseURL: http://localhost:3000, useMock: true, }, staging: { baseURL: https://staging.example.com, useMock: false, }, prod-readonly: { baseURL: https://www.example.com, useMock: false, readonly: true, }, }; export default defineConfig({ projects: Object.entries(profiles).map(([name, cfg]) ({ name, use: { baseURL: cfg.baseURL, extraHTTPHeaders: { X-Test-Profile: name, }, }, metadata: cfg, })), });跑的时候用npx playwright test --projectstaging就能切换。用例内部通过test.info().project.metadata读取当前 profile决定是否跳过写入操作。这样一套脚本三种环境复用维护成本大幅降低。4. 实操过程与核心环节实现4.1 环境准备与项目初始化假设我们从零开始搭一个 Playwright e2e 项目。第一步是初始化mkdir e2e-demo cd e2e-demo npm init -y npm install -D playwright/test npx playwright installnpx playwright install会下载 Chromium、Firefox、WebKit 三个浏览器。如果 CI 上只需要 Chromium可以只装一个npx playwright install chromium能省不少时间和磁盘。目录结构我习惯这样组织e2e-demo/ ├── tests/ │ ├── smoke/ │ │ └── login.spec.ts │ ├── regression/ │ │ └── order.spec.ts │ └── fixtures/ │ └── user.fixture.ts ├── pages/ │ ├── login.page.ts │ └── order.page.ts ├── utils/ │ ├── api.ts │ └── data.ts ├── playwright.config.ts └── package.jsonpages放页面对象Page Objectfixtures放测试夹具utils放 API 封装和数据工厂。这个结构不复杂但能让用例保持干净。4.2 页面对象封装让用例读起来像自然语言页面对象模式Page Object Model是老生常谈但很多人用错了。错误用法是把页面所有元素和操作都塞进一个类结果类膨胀到几百行。正确用法是只封装这个页面对外暴露的“业务动作”。// pages/login.page.ts import { Page, expect } from playwright/test; export class LoginPage { constructor(private page: Page) {} async goto() { await this.page.goto(/login); } async login(username: string, password: string) { await this.page.getByLabel(用户名).fill(username); await this.page.getByLabel(密码).fill(password); await this.page.getByRole(button, { name: 登录 }).click(); } async expectLoggedIn() { await expect(this.page.getByTestId(user-avatar)).toBeVisible(); } }用例里就变成const loginPage new LoginPage(page); await loginPage.goto(); await loginPage.login(test_user, password123); await loginPage.expectLoggedIn();读起来是不是像在描述用户行为这就是好的 e2e 用例该有的样子。4.3 核心链路用例以“下单”为例下单是电商类项目最典型的 e2e 场景。我把它拆成几个关键断言点import { test, expect } from playwright/test; import { LoginPage } from ../pages/login.page; import { OrderPage } from ../pages/order.page; import { createTestProduct, cleanupTestProduct } from ../utils/data; test.describe(下单主链路, () { let productId: string; test.beforeEach(async ({ request }) { // 通过 API 创建测试商品避免依赖线上数据 productId await createTestProduct(request, { name: e2e测试商品_${Date.now()}, price: 9.9, stock: 100, }); }); test.afterEach(async ({ request }) { await cleanupTestProduct(request, productId); }); test(用户登录后能成功下单, async ({ page }) { const loginPage new LoginPage(page); const orderPage new OrderPage(page); await loginPage.goto(); await loginPage.login(e2e_user, e2e_password); await loginPage.expectLoggedIn(); await orderPage.gotoProduct(productId); await orderPage.addToCart(); await orderPage.checkout(); // 关键断言订单创建接口返回 200 const response await page.waitForResponse( resp resp.url().includes(/api/order/create) ); expect(response.status()).toBe(200); // 关键断言页面展示订单成功 await expect(page.getByTestId(order-success)).toBeVisible(); await expect(page.getByTestId(order-id)).not.toBeEmpty(); }); });这条用例有几个设计要点值得说beforeEach 建数据afterEach 清数据保证用例独立可重复跑。waitForResponse 抓接口既验证了后端返回又避免了硬等待。断言分两层接口层验证状态码UI 层验证用户可见结果。两层都过才算真正通过。4.4 CI 接入让 e2e 成为发布门禁e2e 不进 CI等于没做。但直接全量跑CI 时间会爆炸。我的策略是分阶段接入阶段触发时机跑哪些超时失败处理提交级每次 pushsmoke 目录5 分钟阻断合并合并级PR 合并前smoke 核心 regression15 分钟阻断合并夜间级每天凌晨全量 regression60 分钟通知不阻断发版级发布前全量 探索用例90 分钟阻断发布GitHub Actions 的配置大概长这样name: e2e on: push: branches: [main] pull_request: jobs: smoke: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm ci - run: npx playwright install chromium --with-deps - run: npx playwright test tests/smoke --projectstaging - uses: actions/upload-artifactv4 if: failure() with: name: playwright-report path: playwright-report/失败时上传报告这是关键。没有报告的 e2e 失败排查成本极高。Playwright 的 HTML 报告和 Trace 文件能让你直接看到失败那一刻的 DOM、网络请求和控制台日志。5. 常见问题与排查技巧实录5.1 flaky 用例e2e 最大的敌人flaky 指的是同一条用例有时过有时不过代码没改环境没变。这是 e2e 最让人头疼的问题。我总结了一张排查速查表现象可能原因排查方法解决思路偶发元素找不到渲染时序问题看 Trace 里失败时刻的 DOM改用条件等待别用 sleep偶发断言失败数据被其他用例污染检查用例是否共用数据数据隔离加唯一标识偶发超时CI 机器负载高对比本地和 CI 耗时提高超时阈值或分片跑偶发登录失败验证码/风控看网络请求和响应测试环境关闭验证码偶发接口 500后端不稳定看服务端日志加重试或标记为已知问题我的经验是flaky 用例必须当天处理不能挂“skip”了事。一旦允许 skip很快就会有第二十条、第三十条最后整个 e2e 套件失去可信度。处理方式无非三种修选择器、修等待、修数据。实在修不了的用test.fixme标记并附上 issue 链接定期回顾。5.2 调试三板斧Trace、截图、控制台Playwright 的 Trace Viewer 是我用过最好的 e2e 调试工具。配置很简单// playwright.config.ts use: { trace: on-first-retry, screenshot: only-on-failure, video: retain-on-failure, },trace: on-first-retry表示第一次失败不录重试时录。这样既省资源又能在 flaky 场景抓到现场。跑完用npx playwright show-trace trace.zip打开能看到每一步的 DOM 快照、网络请求、控制台输出基本上一眼就能定位问题。实操心得CI 上失败时一定要把 trace 和截图作为 artifact 上传。我见过太多团队 CI 红了但没人知道为什么红就是因为没留现场。5.3 登录态复用别每条用例都走一遍登录如果每条用例都从登录开始跑 100 条用例就登录 100 次浪费时间还容易触发风控。正确做法是登录一次保存 storageState后续用例复用。// global-setup.ts import { chromium } from playwright/test; async function globalSetup() { const browser await chromium.launch(); const page await browser.newPage(); await page.goto(/login); await page.getByLabel(用户名).fill(e2e_user); await page.getByLabel(密码).fill(e2e_password); await page.getByRole(button, { name: 登录 }).click(); await page.waitForURL(/dashboard); await page.context().storageState({ path: storageState.json }); await browser.close(); } export default globalSetup;然后在 config 里引用globalSetup: ./global-setup.ts, use: { storageState: storageState.json, },这样每条用例启动时已经处于登录态省掉大量重复操作。注意 storageState 有有效期如果 token 过期需要重新生成。CI 上可以在 job 开始时跑一次 globalSetup。5.4 并行与分片让 e2e 跑得更快e2e 慢是常态但可以通过并行和分片加速。Playwright 默认按文件并行workers控制并发数。CI 上一般设 2 到 4本地可以设 CPU 核数的一半。分片则是把用例拆到多台机器跑# 机器 1 npx playwright test --shard1/3 # 机器 2 npx playwright test --shard2/3 # 机器 3 npx playwright test --shard3/3GitHub Actions 里可以用 matrix 实现strategy: matrix: shard: [1, 2, 3] steps: - run: npx playwright test --shard${{ matrix.shard }}/3分片的关键是用例之间不能有依赖。如果用例 A 依赖用例 B 先跑分片后就会随机失败。所以前面强调的数据隔离和用例独立在这里就是硬性要求。5.5 常见问题速查最后整理一份我实际踩过的坑供你对照元素明明存在却点不到多半是被遮挡或不可交互。用force: true能绕过但那是掩耳盗铃正确做法是等遮挡消失。iframe 里的元素找不到需要先frameLocator切进去别直接page.getByXxx。新标签页操作失败用context.waitForEvent(page)拿到新页面对象再操作。文件上传用setInputFiles别去模拟点击系统弹窗那是不可能的。时间相关断言别断言“当前时间”用相对时间或 mock 系统时间。多语言环境选择器别绑死文案用 testid 或 role。6. 关于 e2e 的一些个人体会做了这么多年 e2e我最大的体会是e2e 不是测试团队一个人的事。它需要前端加 testid、后端提供测试数据接口、运维配好测试环境、CI 留出足够的超时。任何一环不配合e2e 就会变成“写了没人跑跑了没人看”的摆设。另一个体会是e2e 用例要少而精。我见过跑 500 条 e2e 的团队也见过只跑 20 条的团队后者的线上事故率反而更低。因为 20 条核心用例被认真维护每条都稳定可信500 条里有一半 flaky跑完没人敢信结果。与其追求数量不如把最核心的几条链路打磨到 99% 稳定。最后分享一个小技巧给每条 e2e 用例加一个“业务价值”注释。比如// 覆盖新用户首单转化影响 GMV。这样当有人想删用例时能立刻判断它值不值得留。e2e 的维护成本很高每一条都应该有存在的理由。
1. 从“e2e”说起端到端测试到底在测什么第一次看到“e2e”这个词很多人会以为是某个新框架的缩写或者某个内部项目的代号。其实它就是end-to-end的缩写中文叫“端到端”。在软件研发语境里e2e 测试指的是从用户真实使用路径出发把整个系统当成一个黑盒验证从入口到出口的完整链路是否按预期工作。它不关心某个函数写得漂不漂亮也不关心某个接口的返回字段是不是符合文档它只关心一件事——用户点下去之后最终结果对不对。我做了十多年一线研发和测试见过太多团队在单元测试覆盖率 90% 的情况下上线依然翻车。原因很简单单元测试测的是“零件”e2e 测的是“整车”。零件都好装在一起未必能跑。e2e 的价值就在于它把前端页面、网关、业务服务、缓存、数据库、消息队列、第三方依赖全部串起来用真实或接近真实的操作路径去跑一遍。跑通了你才敢说“这个功能能交付”。那 e2e 适合谁来关注三类人最需要前端/全栈工程师因为你们最接近用户操作路径测试开发工程师因为 e2e 框架选型和稳定性治理是你们的核心战场技术负责人和 DevOps因为 e2e 要不要进 CI、卡不卡发布门禁直接决定团队交付节奏。哪怕你是个刚入行的新人理解 e2e 也能让你明白写代码不是目的让用户顺利完成一件事才是。最近热词里出现了一个“e2e profile1”这其实指向一个很实际的场景用不同的 profile配置档去跑同一套 e2e 用例。比如本地开发用 mock 依赖的 profile预发环境用真实依赖的 profile线上回归用只读账号的 profile。同一套脚本换一份配置就能适配不同环境这是 e2e 工程化里非常关键的一步。下面我就围绕 e2e 的整体设计、核心细节、实操落地和踩坑排查把这件事讲透。2. e2e 测试的整体设计与方案选型2.1 为什么 e2e 不能“随便写写”很多团队一开始做 e2e 的方式很朴素找个人打开浏览器点一遍截图发群里说“没问题”。这种方式在项目早期还能凑合一旦功能上到几十个页面、每天发好几次版就彻底崩了。原因有三个不可重复、不可并行、不可度量。人点一遍要半小时机器跑一遍可能只要两分钟人点会漏脚本不会人点完没有报告脚本跑完有日志和截图。所以 e2e 的第一层设计不是选哪个框架而是想清楚e2e 在交付流程里扮演什么角色。我的经验是把它分成三类定位冒烟级 e2e只覆盖最核心的 3 到 5 条主链路比如登录、下单、支付。每次提交都跑要求 5 分钟内出结果。回归级 e2e覆盖主要业务场景几十到上百条用例。每天夜间跑或者发版前跑。探索级 e2e针对新功能或高风险模块临时补充跑完即弃不纳入长期维护。这三类定位决定了你的框架选型、用例组织方式和 CI 接入策略。如果一上来就把所有场景都写成“必须每次跑”结果就是 CI 越来越慢最后没人看e2e 形同虚设。2.2 框架选型Playwright、Cypress 还是 Selenium这是被问得最多的问题。我不给绝对答案只给判断依据。先看一张对比表维度PlaywrightCypressSelenium多浏览器支持Chromium/Firefox/WebKitChromium/Firefox/WebKit部分受限全浏览器自动等待内置体验好内置体验好需手动封装多标签/多窗口原生支持支持有限支持网络拦截强route 机制强intercept需额外库语言支持JS/TS/Python/Java/.NETJS/TS多语言调试体验Trace Viewer 很香时间旅行调试依赖 IDE上手成本低低中高我个人的选择逻辑是新项目、以 Chromium 为主、团队以 JS/TS 为主优先 Playwright。它的 Trace Viewer 在排查 flaky 用例时几乎是救命工具网络拦截和自动等待也做得足够稳。Cypress 的开发者体验很好但多标签和跨域场景会让人抓狂。Selenium 适合已有大量存量用例、或者必须覆盖老旧浏览器的团队新项目不建议从零开始。至于“e2e profile1”这个热词落到选型上就是框架要支持通过环境变量或配置文件切换运行档位。Playwright 里可以用projects配置多个 profileCypress 里可以用--env或cypress.config区分。这一点在后面的实操里会详细展开。2.3 用例分层别把 e2e 写成“大号单元测试”我见过最糟糕的 e2e 用例是把每个按钮点击、每个字段校验都写成一条独立用例结果几百条用例跑两小时其中一半在测“输入框能不能输入”。这是典型的定位错乱。e2e 应该测跨系统的业务闭环而不是 UI 细节。合理的分层是这样的UI 细节交给组件测试或单元测试比如按钮禁用态、表单校验提示。接口契约交给集成测试比如服务 A 调服务 B 的字段是否匹配。业务闭环交给 e2e比如“用户注册后能成功下单并收到确认”。一条好的 e2e 用例通常对应一个用户故事。比如“新用户首次下单”这条用例会依次经过打开首页、搜索商品、加入购物车、登录/注册、填写地址、选择支付、提交订单、查看订单状态。中间任何一步断了这条用例就失败而且失败信息能直接告诉你是哪一环出了问题。3. 核心细节解析与实操要点3.1 选择器策略别让用例死在“改了个 class”e2e 用例最脆弱的环节就是选择器。前端改个样式、换个组件库div div:nth-child(3)这种选择器立刻失效。我的原则是优先用面向用户的语义选择器其次用测试专用属性最后才用 CSS/XPath。Playwright 推荐顺序getByRole比如page.getByRole(button, { name: 提交订单 })最贴近用户视角。getByLabel/getByPlaceholder表单场景很好用。getByTestId前端加>// 等待接口返回后再断言页面 await page.waitForResponse(resp resp.url().includes(/api/order/create) resp.status() 200 ); await expect(page.getByTestId(order-success)).toBeVisible();Cypress 里则用cy.intercept配合cy.wait(alias)。核心思想一致让脚本跟着系统状态走而不是跟着时钟走。3.3 测试数据管理别让用例互相污染e2e 跑多了最大的坑是数据。用例 A 创建了一个订单用例 B 去查订单列表结果查到 A 的数据断言失败。或者用例 C 删除了某个用户导致用例 D 登录失败。这类问题统称为测试数据耦合。我的做法是三条每条用例自建数据用 API 或 fixture 在用例开始前创建专属数据用例结束后清理。比如下单用例自己创建一个测试商品不依赖线上已有商品。数据带唯一标识用时间戳或 UUID 做后缀比如test_user_1710000000避免重名冲突。只读用例和写入用例分开跑只读用例可以并行写入用例串行或分片减少互相干扰。实操心得如果清理逻辑太复杂可以用“软清理”——给测试数据打标记定期用脚本批量删除。别为了清理把用例写得太重e2e 本身已经够慢了。3.4 profile 配置一套用例跑遍多环境回到热词“e2e profile1”。实际项目中我们通常需要同一套用例在多个环境跑local依赖全部 mock跑得最快用于开发自测。staging依赖真实但数据隔离用于发版前回归。prod-readonly只跑只读用例用于线上巡检。Playwright 的配置方式很直接// playwright.config.ts import { defineConfig } from playwright/test; const profiles { local: { baseURL: http://localhost:3000, useMock: true, }, staging: { baseURL: https://staging.example.com, useMock: false, }, prod-readonly: { baseURL: https://www.example.com, useMock: false, readonly: true, }, }; export default defineConfig({ projects: Object.entries(profiles).map(([name, cfg]) ({ name, use: { baseURL: cfg.baseURL, extraHTTPHeaders: { X-Test-Profile: name, }, }, metadata: cfg, })), });跑的时候用npx playwright test --projectstaging就能切换。用例内部通过test.info().project.metadata读取当前 profile决定是否跳过写入操作。这样一套脚本三种环境复用维护成本大幅降低。4. 实操过程与核心环节实现4.1 环境准备与项目初始化假设我们从零开始搭一个 Playwright e2e 项目。第一步是初始化mkdir e2e-demo cd e2e-demo npm init -y npm install -D playwright/test npx playwright installnpx playwright install会下载 Chromium、Firefox、WebKit 三个浏览器。如果 CI 上只需要 Chromium可以只装一个npx playwright install chromium能省不少时间和磁盘。目录结构我习惯这样组织e2e-demo/ ├── tests/ │ ├── smoke/ │ │ └── login.spec.ts │ ├── regression/ │ │ └── order.spec.ts │ └── fixtures/ │ └── user.fixture.ts ├── pages/ │ ├── login.page.ts │ └── order.page.ts ├── utils/ │ ├── api.ts │ └── data.ts ├── playwright.config.ts └── package.jsonpages放页面对象Page Objectfixtures放测试夹具utils放 API 封装和数据工厂。这个结构不复杂但能让用例保持干净。4.2 页面对象封装让用例读起来像自然语言页面对象模式Page Object Model是老生常谈但很多人用错了。错误用法是把页面所有元素和操作都塞进一个类结果类膨胀到几百行。正确用法是只封装这个页面对外暴露的“业务动作”。// pages/login.page.ts import { Page, expect } from playwright/test; export class LoginPage { constructor(private page: Page) {} async goto() { await this.page.goto(/login); } async login(username: string, password: string) { await this.page.getByLabel(用户名).fill(username); await this.page.getByLabel(密码).fill(password); await this.page.getByRole(button, { name: 登录 }).click(); } async expectLoggedIn() { await expect(this.page.getByTestId(user-avatar)).toBeVisible(); } }用例里就变成const loginPage new LoginPage(page); await loginPage.goto(); await loginPage.login(test_user, password123); await loginPage.expectLoggedIn();读起来是不是像在描述用户行为这就是好的 e2e 用例该有的样子。4.3 核心链路用例以“下单”为例下单是电商类项目最典型的 e2e 场景。我把它拆成几个关键断言点import { test, expect } from playwright/test; import { LoginPage } from ../pages/login.page; import { OrderPage } from ../pages/order.page; import { createTestProduct, cleanupTestProduct } from ../utils/data; test.describe(下单主链路, () { let productId: string; test.beforeEach(async ({ request }) { // 通过 API 创建测试商品避免依赖线上数据 productId await createTestProduct(request, { name: e2e测试商品_${Date.now()}, price: 9.9, stock: 100, }); }); test.afterEach(async ({ request }) { await cleanupTestProduct(request, productId); }); test(用户登录后能成功下单, async ({ page }) { const loginPage new LoginPage(page); const orderPage new OrderPage(page); await loginPage.goto(); await loginPage.login(e2e_user, e2e_password); await loginPage.expectLoggedIn(); await orderPage.gotoProduct(productId); await orderPage.addToCart(); await orderPage.checkout(); // 关键断言订单创建接口返回 200 const response await page.waitForResponse( resp resp.url().includes(/api/order/create) ); expect(response.status()).toBe(200); // 关键断言页面展示订单成功 await expect(page.getByTestId(order-success)).toBeVisible(); await expect(page.getByTestId(order-id)).not.toBeEmpty(); }); });这条用例有几个设计要点值得说beforeEach 建数据afterEach 清数据保证用例独立可重复跑。waitForResponse 抓接口既验证了后端返回又避免了硬等待。断言分两层接口层验证状态码UI 层验证用户可见结果。两层都过才算真正通过。4.4 CI 接入让 e2e 成为发布门禁e2e 不进 CI等于没做。但直接全量跑CI 时间会爆炸。我的策略是分阶段接入阶段触发时机跑哪些超时失败处理提交级每次 pushsmoke 目录5 分钟阻断合并合并级PR 合并前smoke 核心 regression15 分钟阻断合并夜间级每天凌晨全量 regression60 分钟通知不阻断发版级发布前全量 探索用例90 分钟阻断发布GitHub Actions 的配置大概长这样name: e2e on: push: branches: [main] pull_request: jobs: smoke: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm ci - run: npx playwright install chromium --with-deps - run: npx playwright test tests/smoke --projectstaging - uses: actions/upload-artifactv4 if: failure() with: name: playwright-report path: playwright-report/失败时上传报告这是关键。没有报告的 e2e 失败排查成本极高。Playwright 的 HTML 报告和 Trace 文件能让你直接看到失败那一刻的 DOM、网络请求和控制台日志。5. 常见问题与排查技巧实录5.1 flaky 用例e2e 最大的敌人flaky 指的是同一条用例有时过有时不过代码没改环境没变。这是 e2e 最让人头疼的问题。我总结了一张排查速查表现象可能原因排查方法解决思路偶发元素找不到渲染时序问题看 Trace 里失败时刻的 DOM改用条件等待别用 sleep偶发断言失败数据被其他用例污染检查用例是否共用数据数据隔离加唯一标识偶发超时CI 机器负载高对比本地和 CI 耗时提高超时阈值或分片跑偶发登录失败验证码/风控看网络请求和响应测试环境关闭验证码偶发接口 500后端不稳定看服务端日志加重试或标记为已知问题我的经验是flaky 用例必须当天处理不能挂“skip”了事。一旦允许 skip很快就会有第二十条、第三十条最后整个 e2e 套件失去可信度。处理方式无非三种修选择器、修等待、修数据。实在修不了的用test.fixme标记并附上 issue 链接定期回顾。5.2 调试三板斧Trace、截图、控制台Playwright 的 Trace Viewer 是我用过最好的 e2e 调试工具。配置很简单// playwright.config.ts use: { trace: on-first-retry, screenshot: only-on-failure, video: retain-on-failure, },trace: on-first-retry表示第一次失败不录重试时录。这样既省资源又能在 flaky 场景抓到现场。跑完用npx playwright show-trace trace.zip打开能看到每一步的 DOM 快照、网络请求、控制台输出基本上一眼就能定位问题。实操心得CI 上失败时一定要把 trace 和截图作为 artifact 上传。我见过太多团队 CI 红了但没人知道为什么红就是因为没留现场。5.3 登录态复用别每条用例都走一遍登录如果每条用例都从登录开始跑 100 条用例就登录 100 次浪费时间还容易触发风控。正确做法是登录一次保存 storageState后续用例复用。// global-setup.ts import { chromium } from playwright/test; async function globalSetup() { const browser await chromium.launch(); const page await browser.newPage(); await page.goto(/login); await page.getByLabel(用户名).fill(e2e_user); await page.getByLabel(密码).fill(e2e_password); await page.getByRole(button, { name: 登录 }).click(); await page.waitForURL(/dashboard); await page.context().storageState({ path: storageState.json }); await browser.close(); } export default globalSetup;然后在 config 里引用globalSetup: ./global-setup.ts, use: { storageState: storageState.json, },这样每条用例启动时已经处于登录态省掉大量重复操作。注意 storageState 有有效期如果 token 过期需要重新生成。CI 上可以在 job 开始时跑一次 globalSetup。5.4 并行与分片让 e2e 跑得更快e2e 慢是常态但可以通过并行和分片加速。Playwright 默认按文件并行workers控制并发数。CI 上一般设 2 到 4本地可以设 CPU 核数的一半。分片则是把用例拆到多台机器跑# 机器 1 npx playwright test --shard1/3 # 机器 2 npx playwright test --shard2/3 # 机器 3 npx playwright test --shard3/3GitHub Actions 里可以用 matrix 实现strategy: matrix: shard: [1, 2, 3] steps: - run: npx playwright test --shard${{ matrix.shard }}/3分片的关键是用例之间不能有依赖。如果用例 A 依赖用例 B 先跑分片后就会随机失败。所以前面强调的数据隔离和用例独立在这里就是硬性要求。5.5 常见问题速查最后整理一份我实际踩过的坑供你对照元素明明存在却点不到多半是被遮挡或不可交互。用force: true能绕过但那是掩耳盗铃正确做法是等遮挡消失。iframe 里的元素找不到需要先frameLocator切进去别直接page.getByXxx。新标签页操作失败用context.waitForEvent(page)拿到新页面对象再操作。文件上传用setInputFiles别去模拟点击系统弹窗那是不可能的。时间相关断言别断言“当前时间”用相对时间或 mock 系统时间。多语言环境选择器别绑死文案用 testid 或 role。6. 关于 e2e 的一些个人体会做了这么多年 e2e我最大的体会是e2e 不是测试团队一个人的事。它需要前端加 testid、后端提供测试数据接口、运维配好测试环境、CI 留出足够的超时。任何一环不配合e2e 就会变成“写了没人跑跑了没人看”的摆设。另一个体会是e2e 用例要少而精。我见过跑 500 条 e2e 的团队也见过只跑 20 条的团队后者的线上事故率反而更低。因为 20 条核心用例被认真维护每条都稳定可信500 条里有一半 flaky跑完没人敢信结果。与其追求数量不如把最核心的几条链路打磨到 99% 稳定。最后分享一个小技巧给每条 e2e 用例加一个“业务价值”注释。比如// 覆盖新用户首单转化影响 GMV。这样当有人想删用例时能立刻判断它值不值得留。e2e 的维护成本很高每一条都应该有存在的理由。
