1. 项目概述1.1 什么是 E2E 测试它解决了什么问题E2E全称 End-to-End即端到端测试。这几年测试领域的热词一个接一个但要说真正触及软件质量核心的E2E 测试绝对算一个。说得直白一点E2E 测试就是模拟真实用户的操作路径从打开页面、点击按钮、填写表单到验证数据是否正确落库、接口是否返回预期结果完整走通一条业务链路。它和单元测试、接口测试最大的区别就在于完整二字不是测某个函数、某个接口而是测整条业务流是否真的能跑通。举个生活化的例子你去银行办业务柜员单独检查身份证、单独核对签字、单独验证摄像头每个环节都正常但整个流程走下来发现证件信息和系统里的对不上业务照样办不成。单元测试和接口测试就是分别检查每个环节而 E2E 测试就是从进银行门到业务办完的全程演练。这就是 E2E 测试的核心价值它不关心某个内部函数是否返回正确也不关心某个接口的响应码是否为 200它关心的是用户在那个页面上的每一次点击究竟能不能得到他想要的结果。这次项目实践的背景是我们团队接手了一个从零搭建的电商管理系统后端接口全部通过单元测试前端的组件测试也覆盖了主干逻辑但联调上线后频繁出现接口能通但页面流程断掉的问题。根源在于前后端各自为政接口测试和前端测试互相独立没人站在用户视角把整条链路串起来验证。引入 E2E 测试之后用自动化脚本代替人工回归原来需要三个小时的手工冒烟测试压缩到十几分钟而且每次发版前都能快速发现跨端问题。对于中大型项目、微服务架构、前后端分离架构E2E 测试几乎是一个绕不开的基础设施。1.2 这个项目的目标和方案选型我们的目标很明确搭一套稳定、可维护、能嵌入 CI 流水线的 E2E 测试体系覆盖核心业务链路并且让普通开发人员也能快速编写和运行测试用例而不是只有测试专家能维护的花架子。方案选型上我们对比了当前主流的几套 E2E 测试工具包括 Cypress、Selenium WebDriver、Puppeteer最终采用了 Playwright JavaScript或 TypeScript的组合配合多个 profile 配置文件来区分不同环境、不同场景的测试配置。为什么选 Playwright我在后面工具选型章节会详细展开这里先给个结论测试稳定性、跨浏览器支持、网络拦截能力、执行速度几个维度上Playwright 的综合表现最均衡尤其是它对 E2E 测试中大量异步场景的原生支持能把很多以前只能靠 sleep 硬等的情况变成自动等待省掉大量排查 flaky 测试的时间。profile 这个概念在 E2E 测试里值得单独拎出来讲。我们日常会遇到至少两套环境本地开发环境localhost、测试环境test server、预发布环境staging server有时候还有生产环境的只读验证。如果每个环境都在代码里硬编码那维护成本简直灾难。用 profile 配置文件的方式把每个环境的基础 URL、账号密码通过环境变量注入、超时时间、视频录制开关、截图行为、并发数等参数全部抽离通过命令行参数或环境变量激活对应的 profile测试代码本身完全不感知环境差异。这就是本项目的核心设计思路之一。2. 工具选型与配置设计2.1 为什么选择 Playwright先说说 Selenium。Selenium WebDriver 是老牌工具生态成熟、资料多但它的短板这几年越来越明显一是驱动管理麻烦每个浏览器版本要对应下载 driver二是等待机制不够智能大量依赖显式等待和 sleep导致测试脚本动不动就跑挂三是 API 设计偏底层写起来啰嗦维护成本高。Cypress 是另一大热门底层架构决定了它只能支持 Chromium 系浏览器Edge、Chrome、Electron对 Firefox 和 WebKit 的支持是后来才逐步完善的且 Cypress 跑在浏览器内对于多标签页、跨域场景的操作非常别扭。它的网络控制能力也受限想拦截和修改请求响应没有 Playwright 那么直接。Playwright 的优势在于微软开发并持续维护由浏览器开发者直接实现自动化协议三大浏览器引擎Chromium、Firefox、WebKit全面支持。最关键的一点是它的自动等待机制比如点击一个按钮之前Playwright 会自动等待元素处于可交互状态不需要你手动写一大堆等待元素可见的代码。这一点直接解决了我前面提到的 flaky test 问题。实测下来同样规模的测试套件用 Playwright 跑比之前用 Selenium 跑稳定性提升了一大截。2.2 profile 配置的心智模型在 E2E 测试项目里配置和代码分离是一条基本准则。profile 就是我们定义的一个配置集合每个 profile 描述了一个特定的测试运行环境。用一个e2e.config.ts或playwright.config.ts作为主配置入口然后用环境变量或者命令行参数激活不同的 profile。大致的结构是这样的// e2e.config.ts import { defineConfig } from playwright/test; export default defineConfig({ // 主配置全局默认值 testDir: ./tests, timeout: 30000, fullyParallel: true, reporter: [[html, { outputFolder: playwright-report }]], use: { baseURL: process.env[E2E_BASE_URL] || http://localhost:3000, screenshot: only-on-failure, video: off, trace: on-first-retry }, projects: [ { name: profile1-chromium, use: { browserName: chromium, viewport: { width: 1280, height: 720 }, baseURL: https://test.example.com } }, { name: profile2-firefox, use: { browserName: firefox, viewport: { width: 1366, height: 768 }, baseURL: https://staging.example.com } } ] });profile1 这里我们让它对应 Chromium 测试环境profile2 对应 Firefox 预发布环境每个 profile 可以设置完全独立的浏览器参数和 baseURL。更重要的是profile 还能包含业务参数比如使用不同的测试数据集、启用 or 关闭某些功能开关feature flag、模拟不同的用户权限。这些在配置层面解决比在测试代码里写 if else 干净太多。2.3 环境变量与账号管理的坑很多初学者容易把测试账号和密码直接写死在代码里这是很危险的做法。代码仓库一旦泄露测试环境账号直接被暴露。我们的做法是使用.env文件管理环境变量并通过 CI 系统的密钥库注入敏感信息。# .env.local本地环境 E2E_BASE_URLhttp://localhost:3000 E2E_ADMIN_USERadmin E2E_ADMIN_PASSlocal-test-password # .env.test测试环境 E2E_BASE_URLhttps://test.example.com E2E_ADMIN_USERtest-admin E2E_ADMIN_PASSxxx-xxx-xxx在测试代码里通过process.env读取这些变量注意不要将.env.test这样的真实文件提交到 git。CI 上则通过平台的环境变量面板配置同名变量。这里还要注意一点不同环境下的测试账号权限可能不同比如测试环境的 admin 可以删除数据预发布环境可能禁用了删除操作所以 profile 里的业务用例也要做区分。我的做法是给每个 profile 绑定一个独立的 spec 目录或者添加 tag 标签跑 CI 时按 tag 过滤。3. 核心实现与实操过程3.1 从零搭建一个可运行的 E2E 项目下面我把整个搭建过程走一遍你跟着做就能跑起来。这个项目我用的 Node.js 版本是 18包管理器用的 pnpm你也可以用 npm 或 yarn。第一步初始化项目并安装 Playwright 测试库mkdir e2e-project cd e2e-project npm init -y npm install playwright/test npx playwright install chromium这个npx playwright install会下载对应浏览器的二进制文件Chromium 大概一百多 MB网速不好时要有耐心。建议装完 chromium 后再装 firefox 和 webkit本地开发时可以覆盖到三大引擎CI 里只需要装目标浏览器。第二步创建上面说的 Playwright 配置文件我把刚才的e2e.config.ts保存为playwright.config.ts。注意项目根目录下这个文件名是固定约定Playwright 会自动加载它。第三步创建测试目录和第一个测试文件。我用一个登录加商品搜索的链路来演示核心写法// tests/basic-flow.spec.js import { test, expect } from playwright/test; test.describe(核心业务链路, () { test(用户登录后可搜索商品并加入购物车, async ({ page }) { // 跳转登录页 await page.goto(/login); // 填写表单并提交 await page.getByPlaceholder(请输入用户名).fill(process.env.E2E_ADMIN_USER); await page.getByPlaceholder(请输入密码).fill(process.env.E2E_ADMIN_PASS); await page.getByRole(button, { name: 登 录 }).click(); // 断言跳转到首页 await expect(page).toHaveURL(/\/home/); // 搜索商品 await page.getByPlaceholder(搜索商品名称).fill(无线鼠标); await page.getByRole(button, { name: 搜 索 }).click(); // 验证搜索结果中至少包含一个目标商品 await expect(page.getByText(无线鼠标 Pro 版)).toBeVisible(); // 加入购物车 await page.getByRole(button, { name: 加入购物车 }).first().click(); await expect(page.getByText(已成功加入购物车)).toBeVisible(); }); });这段代码看起来简单但里面有不少关键点。比如getByRole、getByPlaceholder这些是 Playwright 推荐用的定位方式比 CSS selector 更贴近用户视角也更稳定因为页面结构调整时角色和语义一般不会轻易变动。注意我没有用page.waitForTimeout()这种硬等待全部依赖自动等待和断言重试机制。3.2 profile1 的完整配置与使用场景刚才只展示了主配置文件的骨架现在单独看看 profile1 的完整配置应该包含什么。profile1 我们定位为基于 Chromium 的测试环境冒烟回归对应的配置项拆解如下配置项值说明browserNamechromium主测浏览器baseURLhttps://test.example.com指向测试服务器viewport1280x720标准桌面视口screenshotonly-on-failure失败时自动截图videoretain-on-failure失败时保存视频traceon全程录制 trace方便排错timeout30000ms单步操作超时retries2失败自动重试两次workers4并发 worker 数httpCredentials从环境变量读取部分环境需要基础认证实际配置片段{ name: profile1-chromium, use: { browserName: chromium, baseURL: https://test.example.com, viewport: { width: 1280, height: 720 }, screenshot: only-on-failure, video: retain-on-failure, trace: on, httpCredentials: { username: process.env.E2E_AUTH_USER || , password: process.env.E2E_AUTH_PASS || } }, retries: 2, timeout: 30000 }这里有个细节trace: on会产生大量文件会拖慢执行速度。在线下调试时可以开CI 里我通常改成on-first-retry只在第一次重试时记录 trace这样既不影响性能又能拿到失败现场。视频录制同理retain-on-failure会比on节省大量磁盘空间。profile1 主要用于每日冒烟测试和 PR 校验。PR 场景下我们只跑smoketag 的用例保证合并代码之前快速反馈核心链路是否被破坏。每日凌晨则跑全量用例覆盖更深入的业务场景。3.3 测试用例设计的最佳实践写 E2E 测试用例最忌讳的就是把每个用例写得又长又密一个用例里塞了几十个步骤失败之后根本不知道是哪个环节出了问题。我总结出来的经验是两条线横向按业务模块拆文件纵向按用户故事拆用例。横向拆文件比如登录认证、商品管理、订单流程、支付流程各自建单独的 spec 文件互不干扰也方便多人同时开发。纵向拆用例每个用例尽量保持一条完整但短小的业务路径。比如登录这个主题可以拆成多个用例正常登录、密码错误提示、用户名不存在提示、登录后跳转、退出登录。每个用例 3 到 6 步操作就好不要超过 10 步。用例长了失败定位的成本成倍增加。值得特别关注的是测试数据的问题。E2E 测试跑起来会真实地操作数据库产生脏数据是常有的事。我的做法是在测试前置中通过 API 创建测试专用的数据测试结束通过 API 清理数据保证用例之间的数据隔离。尽量不依赖界面上手输造数据那样又慢又容易点错。test.beforeAll(async ({ request }) { // 通过 API 创建测试商品 const resp await request.post(/api/products, { data: { name: 端到端测试专用商品, price: 199 } }); expect(resp.ok()).toBeTruthy(); }); test.afterAll(async ({ request }) { // 清理测试数据 await request.delete(/api/products/端到端测试专用商品); });这种 API 打底结合 UI 操作的方式在业界也被称为UI API 混合测试它能规避大量由造数过程引入的不稳定因素而且执行速度更快。毕竟打开一个页面去填写几十个表单字段远远慢于一次接口 POST。4. 踩坑记录与排查技巧4.1 经典问题元素定位稳定性和 force click 的滥用前面提到 getByRole 好在哪这里说说我们踩过的坑。最初团队成员习惯了一堆page.locator(css)从 Selenium 带来的老思路结果前端同学把 CSS 类名一重构几十条用例集体变红。后来我去查失败的用例发现大量定位器写着.item-list .item:first-child这种从 DOM 结构反推的写法。换成了语义化定位之后类似的问题大幅减少。另一个坑是force: true这个选项。Playwright 的 click 默认会校验元素是否可见、是否可点击、是否被遮挡但有时候你太想快点让脚本跑通遇到明明在页面上却点不到的情况就直接click({ force: true })。这可能让测试检查不到真实的用户交互可行性生产环境用户根本点不了而你的测试却成功了。我们的经验是force click 只用于两个场景一是隐藏 input 元素比如原生文件上传框二是确认某个元素在页面上存在但不关心它的交互性。除此之外尽量找到元素不可点击的根因并修复产品而不是绕过它。4.2 网络请求相关的 flaky 问题E2E 测试里最头疼的就是网络波动导致的随机失败。我们的接口偶尔在弱网环境下响应慢Playwright 虽然会自动等待但如果后端超过 30 秒没返回超时照样触发。这背后要分清楚是页面加载慢还是接口真的挂了。排查真实原因时trace 文件和 API 日志缺一不可。打开 trace 记录后你会看到每一步操作对应的网络请求时间线以及控制台报错。我们遇到过一个经典问题测试脚本里点击按钮后立即断言一个提示文案出现但这个提示文案是由后端异步返回后渲染的偶尔接口在 3 秒后才返回断言就赶在渲染之前执行导致测试不稳定。解决方案有两个一是把断言改为await expect(locator).toBeVisible()这种自带重试的断言Playwright 默认在超时时间内反复检查二是针对特定接口用page.waitForResponse()精确等待某个请求完成。我推荐把这两者结合核心场景用waitForResponse确保数据返回之后再用自动等待断言验证 UI 状态。// 等待搜索接口返回后再验证页面结果 const respPromise page.waitForResponse( response response.url().includes(/api/search) response.status() 200 ); await page.getByRole(button, { name: 搜 索 }).click(); await respPromise; await expect(page.getByText(无线鼠标 Pro 版)).toBeVisible();这一段代码就是很典型的高稳定性写法保证断言时数据确实已返回而不是碰运气。4.3 跨环境跑 profile1 时的常见踩坑汇总我把这次实践里最容易踩的坑整理成一个速查表你在自己搭建时参考价值很高现象可能原因解决方案同一个用例本地跑通过CI 上失败环境变量未注入或 baseURL 错误CI 中显式配置 profile 的环境变量日志中打印 baseURL 前置校验登录用例第一次跑挂重试成功测试账号被别的用例登出每个 worker 分配独立测试账号或用 API 注册临时账号截图一片空白断言失败后页面已跳转开启 trace在 trace 里回顾完整时间线不要只依赖失败截图元素定位到了但点击没反应页面有弹层遮挡CSS 动画未结束用 locator 对应的click前加scrollIntoViewIfNeeded检查是否有 iframe考虑动画结束后再交互登录后 cookie 丢失浏览器上下文隔离导致使用 Playwright 内置的 storageState 持久化登录态或在一个 context 内连续执行相关用例浏览器启动慢导致超时并行 worker 数开太多调低 workers或在 CI 配置中为浏览器启动预留充足超时页面有中文getByText 找不到文本节点被拆分使用正则表达式getByText(/无线鼠标/)避免空格和换行干扰本地数据库数据污染测试数据未清理所有测试数据创建时打 tag 标记通过全局 teardown 统一清理这些坑每个单拎出来都能写一篇文章但关键是你要理解背后的共性E2E 测试的不稳定性主要来自环境、数据、时序三个维度解决思路就是让每个维度都可控。环境维度用 profile 隔离数据维度用 API 清理时序维度用自动等待替代 sleep。把这三个维度管好了E2E 测试的稳定性会大幅提升。4.4 让 E2E 测试嵌入 CI 的最佳姿势一个不能自动跑的 E2E 测试体系就是个摆设。我们把 E2E 测试接入了 GitLab CI核心配置是一个 pipeline stage。这里要注意一点E2E 测试必须在应用部署完成之后执行否则页面都起不来全是 404。# .gitlab-ci.yml 片段 e2e:test: stage: test image: mcr.microsoft.com/playwright:v1.40.0-focal script: - npm ci - npx playwright install --with-deps - npx playwright test --projectprofile1-chromium --grep smoke artifacts: when: always paths: - playwright-report/ - test-results/ expire_in: 7 days这段配置有几点值得说明。第一使用了 Playwright 官方 Docker 镜像它已经预装了浏览器和所有系统依赖不用再手动安装各种底层库。第二--grep smoke实现按 tag 过滤用例。第三artifacts 配置会保留所有 HTML 报告和测试结果即使失败也能下载到现场资料。这个 Docker 镜像体积比较大拖下来大概几百 MB但胜在一劳永逸不需要处理一堆 Linux 系统库的兼容问题。5. 进阶技巧与效率提升5.1 自动化测试的代码规范与项目结构当测试用例规模增长到几百条时没有规范的代码结构就是一场灾难。我们最终沉淀下来的目录结构长这样e2e-project/ ├── playwright.config.ts ├── .env.local ├── .env.test ├── fixtures/ │ ├── auth.ts # 登录态 fixture │ └── product.ts # 商品数据 fixture ├── helpers/ │ ├── api-client.ts # API 封装 │ └──>
1. 项目概述1.1 什么是 E2E 测试它解决了什么问题E2E全称 End-to-End即端到端测试。这几年测试领域的热词一个接一个但要说真正触及软件质量核心的E2E 测试绝对算一个。说得直白一点E2E 测试就是模拟真实用户的操作路径从打开页面、点击按钮、填写表单到验证数据是否正确落库、接口是否返回预期结果完整走通一条业务链路。它和单元测试、接口测试最大的区别就在于完整二字不是测某个函数、某个接口而是测整条业务流是否真的能跑通。举个生活化的例子你去银行办业务柜员单独检查身份证、单独核对签字、单独验证摄像头每个环节都正常但整个流程走下来发现证件信息和系统里的对不上业务照样办不成。单元测试和接口测试就是分别检查每个环节而 E2E 测试就是从进银行门到业务办完的全程演练。这就是 E2E 测试的核心价值它不关心某个内部函数是否返回正确也不关心某个接口的响应码是否为 200它关心的是用户在那个页面上的每一次点击究竟能不能得到他想要的结果。这次项目实践的背景是我们团队接手了一个从零搭建的电商管理系统后端接口全部通过单元测试前端的组件测试也覆盖了主干逻辑但联调上线后频繁出现接口能通但页面流程断掉的问题。根源在于前后端各自为政接口测试和前端测试互相独立没人站在用户视角把整条链路串起来验证。引入 E2E 测试之后用自动化脚本代替人工回归原来需要三个小时的手工冒烟测试压缩到十几分钟而且每次发版前都能快速发现跨端问题。对于中大型项目、微服务架构、前后端分离架构E2E 测试几乎是一个绕不开的基础设施。1.2 这个项目的目标和方案选型我们的目标很明确搭一套稳定、可维护、能嵌入 CI 流水线的 E2E 测试体系覆盖核心业务链路并且让普通开发人员也能快速编写和运行测试用例而不是只有测试专家能维护的花架子。方案选型上我们对比了当前主流的几套 E2E 测试工具包括 Cypress、Selenium WebDriver、Puppeteer最终采用了 Playwright JavaScript或 TypeScript的组合配合多个 profile 配置文件来区分不同环境、不同场景的测试配置。为什么选 Playwright我在后面工具选型章节会详细展开这里先给个结论测试稳定性、跨浏览器支持、网络拦截能力、执行速度几个维度上Playwright 的综合表现最均衡尤其是它对 E2E 测试中大量异步场景的原生支持能把很多以前只能靠 sleep 硬等的情况变成自动等待省掉大量排查 flaky 测试的时间。profile 这个概念在 E2E 测试里值得单独拎出来讲。我们日常会遇到至少两套环境本地开发环境localhost、测试环境test server、预发布环境staging server有时候还有生产环境的只读验证。如果每个环境都在代码里硬编码那维护成本简直灾难。用 profile 配置文件的方式把每个环境的基础 URL、账号密码通过环境变量注入、超时时间、视频录制开关、截图行为、并发数等参数全部抽离通过命令行参数或环境变量激活对应的 profile测试代码本身完全不感知环境差异。这就是本项目的核心设计思路之一。2. 工具选型与配置设计2.1 为什么选择 Playwright先说说 Selenium。Selenium WebDriver 是老牌工具生态成熟、资料多但它的短板这几年越来越明显一是驱动管理麻烦每个浏览器版本要对应下载 driver二是等待机制不够智能大量依赖显式等待和 sleep导致测试脚本动不动就跑挂三是 API 设计偏底层写起来啰嗦维护成本高。Cypress 是另一大热门底层架构决定了它只能支持 Chromium 系浏览器Edge、Chrome、Electron对 Firefox 和 WebKit 的支持是后来才逐步完善的且 Cypress 跑在浏览器内对于多标签页、跨域场景的操作非常别扭。它的网络控制能力也受限想拦截和修改请求响应没有 Playwright 那么直接。Playwright 的优势在于微软开发并持续维护由浏览器开发者直接实现自动化协议三大浏览器引擎Chromium、Firefox、WebKit全面支持。最关键的一点是它的自动等待机制比如点击一个按钮之前Playwright 会自动等待元素处于可交互状态不需要你手动写一大堆等待元素可见的代码。这一点直接解决了我前面提到的 flaky test 问题。实测下来同样规模的测试套件用 Playwright 跑比之前用 Selenium 跑稳定性提升了一大截。2.2 profile 配置的心智模型在 E2E 测试项目里配置和代码分离是一条基本准则。profile 就是我们定义的一个配置集合每个 profile 描述了一个特定的测试运行环境。用一个e2e.config.ts或playwright.config.ts作为主配置入口然后用环境变量或者命令行参数激活不同的 profile。大致的结构是这样的// e2e.config.ts import { defineConfig } from playwright/test; export default defineConfig({ // 主配置全局默认值 testDir: ./tests, timeout: 30000, fullyParallel: true, reporter: [[html, { outputFolder: playwright-report }]], use: { baseURL: process.env[E2E_BASE_URL] || http://localhost:3000, screenshot: only-on-failure, video: off, trace: on-first-retry }, projects: [ { name: profile1-chromium, use: { browserName: chromium, viewport: { width: 1280, height: 720 }, baseURL: https://test.example.com } }, { name: profile2-firefox, use: { browserName: firefox, viewport: { width: 1366, height: 768 }, baseURL: https://staging.example.com } } ] });profile1 这里我们让它对应 Chromium 测试环境profile2 对应 Firefox 预发布环境每个 profile 可以设置完全独立的浏览器参数和 baseURL。更重要的是profile 还能包含业务参数比如使用不同的测试数据集、启用 or 关闭某些功能开关feature flag、模拟不同的用户权限。这些在配置层面解决比在测试代码里写 if else 干净太多。2.3 环境变量与账号管理的坑很多初学者容易把测试账号和密码直接写死在代码里这是很危险的做法。代码仓库一旦泄露测试环境账号直接被暴露。我们的做法是使用.env文件管理环境变量并通过 CI 系统的密钥库注入敏感信息。# .env.local本地环境 E2E_BASE_URLhttp://localhost:3000 E2E_ADMIN_USERadmin E2E_ADMIN_PASSlocal-test-password # .env.test测试环境 E2E_BASE_URLhttps://test.example.com E2E_ADMIN_USERtest-admin E2E_ADMIN_PASSxxx-xxx-xxx在测试代码里通过process.env读取这些变量注意不要将.env.test这样的真实文件提交到 git。CI 上则通过平台的环境变量面板配置同名变量。这里还要注意一点不同环境下的测试账号权限可能不同比如测试环境的 admin 可以删除数据预发布环境可能禁用了删除操作所以 profile 里的业务用例也要做区分。我的做法是给每个 profile 绑定一个独立的 spec 目录或者添加 tag 标签跑 CI 时按 tag 过滤。3. 核心实现与实操过程3.1 从零搭建一个可运行的 E2E 项目下面我把整个搭建过程走一遍你跟着做就能跑起来。这个项目我用的 Node.js 版本是 18包管理器用的 pnpm你也可以用 npm 或 yarn。第一步初始化项目并安装 Playwright 测试库mkdir e2e-project cd e2e-project npm init -y npm install playwright/test npx playwright install chromium这个npx playwright install会下载对应浏览器的二进制文件Chromium 大概一百多 MB网速不好时要有耐心。建议装完 chromium 后再装 firefox 和 webkit本地开发时可以覆盖到三大引擎CI 里只需要装目标浏览器。第二步创建上面说的 Playwright 配置文件我把刚才的e2e.config.ts保存为playwright.config.ts。注意项目根目录下这个文件名是固定约定Playwright 会自动加载它。第三步创建测试目录和第一个测试文件。我用一个登录加商品搜索的链路来演示核心写法// tests/basic-flow.spec.js import { test, expect } from playwright/test; test.describe(核心业务链路, () { test(用户登录后可搜索商品并加入购物车, async ({ page }) { // 跳转登录页 await page.goto(/login); // 填写表单并提交 await page.getByPlaceholder(请输入用户名).fill(process.env.E2E_ADMIN_USER); await page.getByPlaceholder(请输入密码).fill(process.env.E2E_ADMIN_PASS); await page.getByRole(button, { name: 登 录 }).click(); // 断言跳转到首页 await expect(page).toHaveURL(/\/home/); // 搜索商品 await page.getByPlaceholder(搜索商品名称).fill(无线鼠标); await page.getByRole(button, { name: 搜 索 }).click(); // 验证搜索结果中至少包含一个目标商品 await expect(page.getByText(无线鼠标 Pro 版)).toBeVisible(); // 加入购物车 await page.getByRole(button, { name: 加入购物车 }).first().click(); await expect(page.getByText(已成功加入购物车)).toBeVisible(); }); });这段代码看起来简单但里面有不少关键点。比如getByRole、getByPlaceholder这些是 Playwright 推荐用的定位方式比 CSS selector 更贴近用户视角也更稳定因为页面结构调整时角色和语义一般不会轻易变动。注意我没有用page.waitForTimeout()这种硬等待全部依赖自动等待和断言重试机制。3.2 profile1 的完整配置与使用场景刚才只展示了主配置文件的骨架现在单独看看 profile1 的完整配置应该包含什么。profile1 我们定位为基于 Chromium 的测试环境冒烟回归对应的配置项拆解如下配置项值说明browserNamechromium主测浏览器baseURLhttps://test.example.com指向测试服务器viewport1280x720标准桌面视口screenshotonly-on-failure失败时自动截图videoretain-on-failure失败时保存视频traceon全程录制 trace方便排错timeout30000ms单步操作超时retries2失败自动重试两次workers4并发 worker 数httpCredentials从环境变量读取部分环境需要基础认证实际配置片段{ name: profile1-chromium, use: { browserName: chromium, baseURL: https://test.example.com, viewport: { width: 1280, height: 720 }, screenshot: only-on-failure, video: retain-on-failure, trace: on, httpCredentials: { username: process.env.E2E_AUTH_USER || , password: process.env.E2E_AUTH_PASS || } }, retries: 2, timeout: 30000 }这里有个细节trace: on会产生大量文件会拖慢执行速度。在线下调试时可以开CI 里我通常改成on-first-retry只在第一次重试时记录 trace这样既不影响性能又能拿到失败现场。视频录制同理retain-on-failure会比on节省大量磁盘空间。profile1 主要用于每日冒烟测试和 PR 校验。PR 场景下我们只跑smoketag 的用例保证合并代码之前快速反馈核心链路是否被破坏。每日凌晨则跑全量用例覆盖更深入的业务场景。3.3 测试用例设计的最佳实践写 E2E 测试用例最忌讳的就是把每个用例写得又长又密一个用例里塞了几十个步骤失败之后根本不知道是哪个环节出了问题。我总结出来的经验是两条线横向按业务模块拆文件纵向按用户故事拆用例。横向拆文件比如登录认证、商品管理、订单流程、支付流程各自建单独的 spec 文件互不干扰也方便多人同时开发。纵向拆用例每个用例尽量保持一条完整但短小的业务路径。比如登录这个主题可以拆成多个用例正常登录、密码错误提示、用户名不存在提示、登录后跳转、退出登录。每个用例 3 到 6 步操作就好不要超过 10 步。用例长了失败定位的成本成倍增加。值得特别关注的是测试数据的问题。E2E 测试跑起来会真实地操作数据库产生脏数据是常有的事。我的做法是在测试前置中通过 API 创建测试专用的数据测试结束通过 API 清理数据保证用例之间的数据隔离。尽量不依赖界面上手输造数据那样又慢又容易点错。test.beforeAll(async ({ request }) { // 通过 API 创建测试商品 const resp await request.post(/api/products, { data: { name: 端到端测试专用商品, price: 199 } }); expect(resp.ok()).toBeTruthy(); }); test.afterAll(async ({ request }) { // 清理测试数据 await request.delete(/api/products/端到端测试专用商品); });这种 API 打底结合 UI 操作的方式在业界也被称为UI API 混合测试它能规避大量由造数过程引入的不稳定因素而且执行速度更快。毕竟打开一个页面去填写几十个表单字段远远慢于一次接口 POST。4. 踩坑记录与排查技巧4.1 经典问题元素定位稳定性和 force click 的滥用前面提到 getByRole 好在哪这里说说我们踩过的坑。最初团队成员习惯了一堆page.locator(css)从 Selenium 带来的老思路结果前端同学把 CSS 类名一重构几十条用例集体变红。后来我去查失败的用例发现大量定位器写着.item-list .item:first-child这种从 DOM 结构反推的写法。换成了语义化定位之后类似的问题大幅减少。另一个坑是force: true这个选项。Playwright 的 click 默认会校验元素是否可见、是否可点击、是否被遮挡但有时候你太想快点让脚本跑通遇到明明在页面上却点不到的情况就直接click({ force: true })。这可能让测试检查不到真实的用户交互可行性生产环境用户根本点不了而你的测试却成功了。我们的经验是force click 只用于两个场景一是隐藏 input 元素比如原生文件上传框二是确认某个元素在页面上存在但不关心它的交互性。除此之外尽量找到元素不可点击的根因并修复产品而不是绕过它。4.2 网络请求相关的 flaky 问题E2E 测试里最头疼的就是网络波动导致的随机失败。我们的接口偶尔在弱网环境下响应慢Playwright 虽然会自动等待但如果后端超过 30 秒没返回超时照样触发。这背后要分清楚是页面加载慢还是接口真的挂了。排查真实原因时trace 文件和 API 日志缺一不可。打开 trace 记录后你会看到每一步操作对应的网络请求时间线以及控制台报错。我们遇到过一个经典问题测试脚本里点击按钮后立即断言一个提示文案出现但这个提示文案是由后端异步返回后渲染的偶尔接口在 3 秒后才返回断言就赶在渲染之前执行导致测试不稳定。解决方案有两个一是把断言改为await expect(locator).toBeVisible()这种自带重试的断言Playwright 默认在超时时间内反复检查二是针对特定接口用page.waitForResponse()精确等待某个请求完成。我推荐把这两者结合核心场景用waitForResponse确保数据返回之后再用自动等待断言验证 UI 状态。// 等待搜索接口返回后再验证页面结果 const respPromise page.waitForResponse( response response.url().includes(/api/search) response.status() 200 ); await page.getByRole(button, { name: 搜 索 }).click(); await respPromise; await expect(page.getByText(无线鼠标 Pro 版)).toBeVisible();这一段代码就是很典型的高稳定性写法保证断言时数据确实已返回而不是碰运气。4.3 跨环境跑 profile1 时的常见踩坑汇总我把这次实践里最容易踩的坑整理成一个速查表你在自己搭建时参考价值很高现象可能原因解决方案同一个用例本地跑通过CI 上失败环境变量未注入或 baseURL 错误CI 中显式配置 profile 的环境变量日志中打印 baseURL 前置校验登录用例第一次跑挂重试成功测试账号被别的用例登出每个 worker 分配独立测试账号或用 API 注册临时账号截图一片空白断言失败后页面已跳转开启 trace在 trace 里回顾完整时间线不要只依赖失败截图元素定位到了但点击没反应页面有弹层遮挡CSS 动画未结束用 locator 对应的click前加scrollIntoViewIfNeeded检查是否有 iframe考虑动画结束后再交互登录后 cookie 丢失浏览器上下文隔离导致使用 Playwright 内置的 storageState 持久化登录态或在一个 context 内连续执行相关用例浏览器启动慢导致超时并行 worker 数开太多调低 workers或在 CI 配置中为浏览器启动预留充足超时页面有中文getByText 找不到文本节点被拆分使用正则表达式getByText(/无线鼠标/)避免空格和换行干扰本地数据库数据污染测试数据未清理所有测试数据创建时打 tag 标记通过全局 teardown 统一清理这些坑每个单拎出来都能写一篇文章但关键是你要理解背后的共性E2E 测试的不稳定性主要来自环境、数据、时序三个维度解决思路就是让每个维度都可控。环境维度用 profile 隔离数据维度用 API 清理时序维度用自动等待替代 sleep。把这三个维度管好了E2E 测试的稳定性会大幅提升。4.4 让 E2E 测试嵌入 CI 的最佳姿势一个不能自动跑的 E2E 测试体系就是个摆设。我们把 E2E 测试接入了 GitLab CI核心配置是一个 pipeline stage。这里要注意一点E2E 测试必须在应用部署完成之后执行否则页面都起不来全是 404。# .gitlab-ci.yml 片段 e2e:test: stage: test image: mcr.microsoft.com/playwright:v1.40.0-focal script: - npm ci - npx playwright install --with-deps - npx playwright test --projectprofile1-chromium --grep smoke artifacts: when: always paths: - playwright-report/ - test-results/ expire_in: 7 days这段配置有几点值得说明。第一使用了 Playwright 官方 Docker 镜像它已经预装了浏览器和所有系统依赖不用再手动安装各种底层库。第二--grep smoke实现按 tag 过滤用例。第三artifacts 配置会保留所有 HTML 报告和测试结果即使失败也能下载到现场资料。这个 Docker 镜像体积比较大拖下来大概几百 MB但胜在一劳永逸不需要处理一堆 Linux 系统库的兼容问题。5. 进阶技巧与效率提升5.1 自动化测试的代码规范与项目结构当测试用例规模增长到几百条时没有规范的代码结构就是一场灾难。我们最终沉淀下来的目录结构长这样e2e-project/ ├── playwright.config.ts ├── .env.local ├── .env.test ├── fixtures/ │ ├── auth.ts # 登录态 fixture │ └── product.ts # 商品数据 fixture ├── helpers/ │ ├── api-client.ts # API 封装 │ └──>
