企业官网建设流程全解析

上个月我们一个订单系统出了线上故障：用户提交订单后页面显示成功，服务端也写了订单，但确认短信迟迟没到。排查了一天，最后定位到是第三方短信供应商灰度发布后，回调参数里的status字段从字符串变成了数字，而系统旧代码只兼容字符串。单元测试和接口测试全过了，因为它们都直接 mock 了回调，没人跑过一条真实用户提交订单、触达短信网关的完整链路。那次事故之后，我给团队立了个规矩：核心链路必须要有 e2e 测试兜底。这篇文章就聊聊我搭 e2e 测试时的一些做法，尤其是 profile 这套配置思路——很多人第一次看到 “e2e profile1” 这类名词会被绕晕，其实它远没你想的复杂。

这套内容适合谁？如果你是后端工程师想补前端链路的覆盖，如果你是测试开发想从零搭一套端到端自动化，或者你只是被领导安排去“把 e2e 跑起来”的倒霉蛋，这篇都能给你一个能直接落地的参考。我会从为什么需要 e2e 讲起，到框架选型、profile 机制、实际场景编写、稳定性排查，最后聊一点治理经验。全程不吹概念，只讲代码和踩坑。

1. E2E到底在测什么

1.1 从一次线上故障说起

先继续说刚才那个事故。我们的代码里有单测、有接口测试，覆盖率报表常年显示 90% 以上。可实际出问题时，一个字段类型变更就能让生产环境“静默失败”。为什么？因为单测测的是函数内部逻辑，接口测的是服务间协议，它们都用了 mock 或固定数据，唯独没有一个人从浏览器里真实地走完“用户注册 -> 登录 -> 搜索商品 -> 加购 -> 结算 -> 提交订单 -> 收到短信”这条完整旅程。

你可能会说“这不是业务测试同学手动点的吗”？但手工回归存在两个问题：一是频率低，发布前才跑一次，发现问题往往要回滚，成本很高；二是人会有疲劳，点 20 遍同一条流程之后，注意力下降得厉害。e2e（end-to-end）测试要补的，正是这个覆盖盲区。它模拟真实用户操作，从 UI 发起请求、经过前端渲染、调用后端接口、落库、触发外部依赖，把整条链路上的问题一次性暴露出来。

那次故障后，我们补了一条 e2e 用例，它会真实打开浏览器，完成下单，并且在最后等待短信网关的 webhook 回调事件。后来的效果非常直接：类似的第三方字段类型变更问题，在上线前就能被红灯拦住，而不是等用户来投诉。

1.2 E2E测试解决的核心问题

E2E 的核心价值不是“自动化点击”，而是“站在用户视角验证系统整体行为”。它不关心某个函数返回值对不对，不关心某个接口状态码是不是 200，它关心的是：一个真实用户能不能在这个系统里完成目标。

这意味着它能帮你发现三类很隐蔽的问题。

第一类是集成问题。前后端联调时，接口字段、鉴权方式、跨域配置、环境路由，任何一环不对，单测都不容易发现，但在 e2e 里只要页面报错，立刻就能暴露。第二类是配置问题。我在好几个项目里遇到过 staging 环境一切正常、生产环境登录失败的场景，最后发现是生产域名没加到回调白名单。这种东西靠代码审查很难发现，但 e2e 跑一次就现形。第三类是权限和交互问题。用户点了按钮没反应、表单校验提示不出现、菜单权限和页面路由不一致，这些都需要真实浏览器渲染才能验证。

所以 e2e 不是给代码“挑毛病”，而是给系统的“可用性”上保险。它的定位应该是：上线前的最后一道闸门，其他测试全过了也要靠它来确认核心用户旅程是通的。

1.3 和单元测试、接口测试怎么分工

我经常被问：有了 e2e，是不是就不用写单测和接口测试了？我的回答是：别做梦了，三者的分工完全不同。

单测像体检中的血常规，能快速发现小毛病；接口测试像胸透，看各个器官之间的连接是否正常；e2e 更像一次完整的体能测试，直接看你整个人能不能跑完 5 公里。三件事优先级不同，成本也不同。E2E 因为要启动真实浏览器、等待渲染和网络，运行最慢，维护成本也最高，所以不应该所有功能都写 e2e，而应该集中覆盖核心链路和高频业务场景。

业界的测试金字塔也一直在强调这个比例：底层单测最多，中间接口测试次之，最上层 e2e 精而少。一旦违背这个比例，测试会变得又慢又脆，最后团队会失去维护意愿。这在我见过的大大小小的项目里几乎成了铁律。

2. 工欲善其事：E2E测试框架选型

2.1 主流框架对比

先给一张框架对比表，是我 2024 年在几个不同类型项目里实测下来的感受，不一定完全客观，但能帮你做个初步判断。

Selenium 是老牌选手，生态最大，几乎所有浏览器和语言都能覆盖，但它的自动等待能力弱，写起来要小心处理元素加载状态，维护成本高。Cypress 的开发者体验做得很好，有内置调试器、自动截图，但它在多浏览器和并行能力上有局限，组织架构上更适合纯前端团队。Playwright 是微软开源的项目，基于 CDP 协议，在现代浏览器上的控制力很强，自动等待、多 profile、Trace Viewer 这些能力对搭建 e2e 体系非常友好。

我不建议盲目追新，如果你摩下 Selenium 脚本已经几百条、跑得稳稳的，没必要重写；但如果是从零开始，我建议认真考虑 Playwright。

2.2 为什么我推荐 Playwright 起步

我推荐 Playwright，核心原因是三个：自动等待、fixture 和多 profile 支持。

自动等待是 e2e 稳定性的救星。Selenium 时代需要手写sleep或WebDriverWait，一旦操作快了慢了就容易随机失败。Playwright 在点击、填写、读取元素时，会持续检查元素是否可交互，不行就自动重试，不需要你到处塞睡眠。这个机制把测试从“碰运气”变成了“等条件满足”。

fixture 机制让你能为每个测试用例创建独立的浏览器上下文、登录状态、API 请求上下文，用完自动销毁。比在每个用例里自己写 setup/teardown 干净得多。

多 profile 支持则直接对应标题里的 “e2e profile1”。Playwright 的projects配置可以同时定义多套运行参数，比如 profile1 跑 staging + 桌面端 Chromium，profile2 跑生产 + 移动端 WebKit，互不干扰，一条命令切换。我在下面的第 3 章会详细拆开讲。

2.3 搭建最小项目结构

先给大家看我最常用的项目结构，不一定适合所有团队，但足够作为起点：

e2e/ config/ profile1.ts profile2.ts fixtures/ login.ts pages/ home.ts checkout.ts tests/ order.spec.ts login.spec.ts utils/ db.ts api.ts playwright.config.ts package.json

几个关键设计点：

• config/下每个 profile 对应一个文件，集中管理 baseURL、浏览器、viewport、测试账号等参数。
• pages/放页面对象，把页面元素定位和操作封装起来，测试用例里只写业务步骤，不写选择器碎头发。
• fixtures/放测试夹具，比如登录状态、数据库连接、接口客户端。
• tests/只放用例文件，命名用.spec.ts后缀，方便框架发现。
• playwright.config.ts是总配置，把 profile 文件里的参数挂到projects上。

这个结构一开始可能觉得繁琐，但它为后面的多环境、多配置切换打好了底子。如果你的项目很小，只有一套环境一个浏览器，也可以把 profile 直接写在playwright.config.ts里，不必单独拆文件。我的经验是：越早拆分，后面加第二套环境越轻松。

3. 拆解 profile 机制：一套代码多环境跑

3.1 什么是 profile，为什么要用 profile

先回答标题里的 “profile1” 到底是什么。Profile 在这里就是“配置档”的意思，你可以把它理解成一组定义好的运行参数，包括环境地址、浏览器、视口、登录态、超时时间等。e2e 项目通常不会只在一个环境上跑，staging 要验证新功能，生产要冒烟回归，本地环境要开发和调试；而且不同环境可能有不同的域名、不同账号、不同测试数据。如果你靠改配置文件的代码来切换环境，改来改去总有出错的时候。

Profile 机制就是把这些参数收拢成一个个有名字的配置项，比如profile1、profile2。运行测试时，用参数指定你想用哪一份配置，其他配置和代码都不用动。

我打一个比方：你的衣橱里同一件外套，冬天加上围巾手套，夏天换成防晒袖套。你不用换外套，只需要按季节选择配饰。Profile 就是在测试项目里做这件事的“配饰包”。

3.2 profile1 配置骨架详解

下面是一份典型的profile1配置，以 Playwright 为例：

// config/profile1.ts export const profile1 = { name: 'staging-desktop', baseURL: 'https://staging.example.com', browser: 'chromium', viewport: { width: 1440, height: 900 }, storageState: './state/staging-login.json', timeout: 30_000, retries: 1, };

每个字段都有它的用途：

• name是 profile 的名字，执行结果、报告里都会用它标识，方便排查是哪套配置出了问题。
• baseURL是所有page.goto('/xxx')的根地址。测试代码里写相对路径，把环境差异收敛到 profile 里，换环境时用例代码不用改。
• browser决定跑哪个浏览器内核：chromium、firefox还是webkit。桌面端常规回归用 Chromium 就够，想要覆盖也更全，可以再加一个 WebKit。
• viewport是视口大小，桌面端用 1440x900，移动端可以用 390x844。同一个用例在不同视口下可能暴露不同渲染问题。
• storageState是登录态的序列化文件，带上它，用例启动时就直接处于登录状态，不用每个用例都走一遍登录流程。
• timeout控制单步操作的默认超时时间，retries控制失败重试次数。这两个参数直接影响测试稳定性。

这些参数最终并不会自己生效，还得在playwright.config.ts里把它们挂到projects上。具体写法我放到下一小节。

3.3 通过命令行切换 profile

要让 profile 真正跑起来，需要把配置文件和总配置连接起来。以下是一个简化的playwright.config.ts：

// playwright.config.ts import { defineConfig } from '@playwright/test'; import { profile1 } from './config/profile1'; import { profile2 } from './config/profile2'; export default defineConfig({ outputDir: 'test-results', projects: [ { name: profile1.name, use: { ...profile1, testIdAttribute: 'data-testid', }, }, { name: profile2.name, use: { ...profile2, }, }, ], });

在projects数组里，每一项就是一个 profile。运行时，用--project参数选择要执行的配置：

# 只跑 profile1 npx playwright test --project=profile1 # 同时跑 profile1 和 profile2 npx playwright test --project=profile1 --project=profile2

如果你不喜欢长命令行，可以在package.json里加脚本：

{ "scripts": { "test:e2e:profile1": "npx playwright test --project=profile1", "test:e2e:profile2": "npx playwright test --project=profile2" } }

这样就实现了我说的“同一套代码，多套配置，命令切换”。团队成员不用关心 profile 内部细节，只需要记得今天是跑profile1还是profile2。

3.4 参数化与标签过滤的高级玩法

profile 不是静态死的，它还可以结合环境变量实现更灵活的运行策略。

假设你的 profile1 写死了 staging 地址，但你在本地也想用 profile1 的浏览器配置跑本地环境，可以这样改：

// config/profile1.ts export const profile1 = { name: 'profile1', baseURL: process.env.E2E_BASE_URL ?? 'https://staging.example.com', browser: process.env.E2E_BROWSER ?? 'chromium', };

然后运行时：

E2E_BASE_URL=http://localhost:3000 npx playwright test --project=profile1

这样 profile1 就不再绑定单一环境，可以复用。

除了参数化，标签过滤也很重要。你可以给用例打标签，比如@smoke、@checkout，然后用--grep只跑部分用例：

# 只跑 profile1 下的冒烟用例 npx playwright test --project=profile1 --grep "@smoke"

我平时会定义一个“冒烟集”，每个迭代上线前只跑这个子集，几分钟就能给出核心链路是否可以通过的信号。而完整的回归集放到夜间去跑，这样兼顾效率和安全。

4. 手把手写一个可落地的 E2E 场景

4.1 从登录到下单：定义用户旅程

纸上谈兵没有用，真正写一条用例才知道 e2e 的复杂度在哪里。我们以一个电商的“登录->搜索->加购->结算->下单”为例。

// tests/order.spec.ts import { test, expect } from '@playwright/test'; test('完整下单链路', async ({ page }) => { // 打开首页 await page.goto('/'); // 登录（这里用 profile 里预置的 storageState，一般不需要重新登录） // 如果没登录，可以先走 UI 登录 await page.getByRole('button', { name: '登录' }).click(); await page.getByLabel('账号').fill('e2e_user'); await page.getByLabel('密码').fill('e2e_pass'); await page.getByRole('button', { name: '提交登录' }).click(); await expect(page.getByText('欢迎回来，e2e_user')).toBeVisible(); // 搜索商品 await page.getByPlaceholder('搜索商品').fill('无线键盘'); await page.getByRole('button', { name: '搜索' }).click(); await page.getByText('无线键盘').first().click(); // 加购并结算 await page.getByRole('button', { name: '加入购物车' }).click(); await page.getByRole('button', { name: '去结算' }).click(); // 提交订单 await page.getByRole('button', { name: '提交订单' }).click(); await expect(page.getByText('订单提交成功')).toBeVisible(); });

这串代码看起来简洁，但它背后有几个关键点：每个getByRole、getByLabel都尽量用语义化定位，而不是div > div:nth-child(3)；每次操作之间 Playwright 会自动等待元素可交互，所以你不需要手动sleep；每个expect起到了“关卡”作用，如果中途页面渲染失败，测试会立刻失败而不是继续往下执行。

4.2 使用 fixtures 注入浏览器上下文

真实项目里，绝大多数用例还没来得及走到下单，就会被登录挡在外面。如果每个用例都先走一遍 UI 登录，不仅慢，还容易因为验证码、多因素认证之类的因素失败。所以我们会用 fixture + storageState 把登录态变成“公共资源”。

我的做法是，在全局 setup 里登录一次，把 cookie 存到固定文件：

// tests/global-setup.ts import { test as setup } from '@playwright/test'; setup('generate login state', async ({ browser }) => { const context = await browser.newContext(); const page = await context.newPage(); await page.goto('/login'); await page.getByLabel('账号').fill('e2e_user'); await page.getByLabel('密码').fill('e2e_pass'); await page.getByRole('button', { name: '提交登录' }).click(); await page.waitForURL('/home'); await context.storageState({ path: './state/staging-login.json' }); await context.close(); });

然后在 profile1 配置里指定storageState: './state/staging-login.json'。这样每个测试用例启动时，浏览器就已经带着登录态了，不用再走 UI 登录。

如果你有更复杂的上下文，比如需要注入 API mock、数据库连接、自定义请求上下文，可以用 Playwright 的test.extend扩展 fixture。这个机制的好处是：每个测试用例拿到的是干净且可控的上下文，用完自动销毁，不会留下脏数据。

4.3 断言不是越多越好

我见过很多刚写 e2e 的同学，对expect有执念，恨不得把页面上的每个按钮、每段文案都断言一遍。结果是：测试非常磨叽，页面上一个无关紧要的元素样式变了，全盘红灯。断言的目的是“验证业务目标是否达成”，不是“验证 UI 有没有变化”。

以“下单成功”为例，你应该断言的是业务结果，比如“订单提交成功”提示可见，或者 URL 进入了订单详情页，而不是“按钮颜色是红色”这种和业务无关的细节。页面文案可以变，红色可以换成蓝色，但只要“订单提交成功”这个业务结果没变，这条用例就应该通过。

我常用的断言优先级是：业务结果（如订单编号显示、成功提示） > 关键页面元素（如登录后用户名） > 跳转路径 > 样式类名。越靠前的断言越值得写。少而准的断言，比多而杂的断言维护成本低得多。

4.4 在这份 profile 里跑起来

写好用例和配置后，执行命令：

npx playwright test --project=profile1

第一次跑你可能会看到很多“红色”，不用慌，大部分是定位失效或者等待超时。为了更高效地排查，我强烈建议你在总配置里打开 trace 和 video：

use: { trace: 'retain-on-failure', video: 'retain-on-failure', screenshot: 'only-on-failure', }

这样只要失败，测试结果目录里就会留下录制视频、截图和 trace 文件。打开 trace 可以回放整个测试过程，看每一步发生了什么。这比看日志猜原因高效多了。

Playwright 还会生成 HTML 测试报告，执行完以后自动打开一个页面，里面能看到每条用例的状态、耗时、console 日志和网络请求。团队里任何人都能拿这份报告去定位问题，不需要“干瞪眼”猜测试为何失败。

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

5.1 测试偶尔超时，重试就能过

这是 e2e 社区最经典的问题之一：“测试昨天是绿的，今天红了，我不改代码再跑一次又绿了。” 这种偶发失败，往往来自资源加载慢、动画未结束、第三方接口响应不稳定，而不是业务逻辑真的坏了。

我的策略是三层处理：

• 在playwright.config.ts的每个项目里配置retries: 1，只对 CI 保留一次重试。
• 配置expect超时：expect: { timeout: 10_000 }，避免默认 30 秒等待让失败时长拖得很长。
• 重试通过之后依然去翻 trace，如果看到失败点是在某个网络请求 pending 了 8 秒，就不要简单放过，要去查后端的慢接口，而不是靠重试掩盖问题。

记住，重试是“止血”，不是“治病”。如果一组用例每周都要靠重试才能过，它的稳定性就是假的。

5.2 同一个选择器本地稳，CI不稳定

本地跑得好好的，一上 CI 就开始答题。最常见的原因是环境差异：本地机器可能有缓存、网络更快、动画已经加载完；CI 上从头开始，首屏慢，图片加载慢，字体渲染慢，元素出现时间不稳定。

解决办法有几个。

第一，定位方式从 XPath 和层级选择器改成语义化定位。getByRole('button', { name: '提交' })比div:nth-child(3) > div > button稳定太多，它不在乎 DOM 结构怎么变，只关心这个按钮在可访问性树里有没有。第二，在 CI 里可以禁用动画。我自己会在测试启动时注入一行样式：

await page.addStyleTag({ content: '* { animation: none !important; transition: none !important; }', });

这样就不会因为动画未结束导致元素“看得见但点不到”。第三，如果某些操作真的需要等接口返回，可以显式等待接口响应：

await Promise.all([ page.waitForResponse((res) => res.url().includes('/api/order')), page.getByRole('button', { name: '提交订单' }).click(), ]);

这一步能避免“点了按钮但还没请求完就立刻断言成功提示”的竞态。

5.3 profile1 和 profile2 用例互相干扰

同时配置了 profile1 和 profile2，并行跑起来以后发现偶发失败，点开报告一看，两个 profile 都在操作同一个测试账号的订单数据，互相顶掉了。这就是共享测试环境最常见的问题。

你有多套 profile，不代表它们应该共享同一套数据和账号。我建议至少做到这个层面：每个 profile 使用独立的租户、独立的账号组。哪怕 staging 环境只有一个库，也要在账号体系上隔离出测试租户。

如果暂时还做不到数据隔离，可以先把并行度降下来：

fullyParallel: false, workers: 1,

但这只是权宜之计。长期来看，profile 之间必须做到执行上互不依赖，否则测试套件越大，随机失败越频繁。另一个经验是：测试用例里生成的数据尽量带唯一前缀，比如e2e_order_${Date.now()}，从源头上减少碰撞。

5.4 测试数据污染的四种应对方式

测试数据污染是所有 e2e 项目绕不过去的问题。我归纳出四种方式，你可以按项目情况选择。

每套 profile 我还会配一套“卫生检查”冒烟用例，专门验证测试数据是不是被清干净了，如果发现残留数据就报警。这一招看起来简单，实际非常省钱，能避免很多“查了半天原来是脏数据”的深夜。

6. 稳定运行之后我还在做的三件事

6.1 统计失败率并建立基线

e2e 跑通只是第一步，更关键的是知道它好不好。我每周都会把测试趋势拉出来看一次：失败率是多少，平均耗时是短了还是长了，哪个 profile 的偶发失败最频繁。没有数据的自动化测试，是一笔糊涂账。

我一般会定两条硬性指标：失败率不超过 2%，单用例平均耗时不超过 20 秒。超过阈值就要停掉新增用例，先处理稳定性。如果你连哪条用例在拖后腿都不知道，那这个套件迟早会被团队嫌弃，最后沦为“从不看报告的摆设”。

6.2 把 E2E 并入发布流水线

很多人一上来就想把 e2e 塞进每个 pull request，结果团队怨声载道，因为测试太慢太脆，所有人都被红灯卡住。我的建议是分三步走：

第一步，先定时跑 nightly，跑一周看看稳定性。第二步，稳定后，允许 PR 上通过手动标签触发 e2e，比如@e2e-ready。第三步，只有核心发布的 release 管道上强制跑冒烟集，完整回归依然是 nightly。这样既保证安全，又不会拖慢日常开发节奏。

6.3 定期维护用例和配置文件

最后说一个所有人都知道但很少有人做到的点：e2e 用例和 profile 配置需要维护。UI 改版、文案变化、登录策略调整、环境过期，都会让用例和 profile 失效。我每两周做一次“用例健康检查”，专门跑一遍标了@smoke的用例，再顺手翻一翻哪些选择器用的是旧文案，哪些 profile 里的账号该换了。

最后一个细节：profile 文件里放测试账号密码的话，一定要走环境的 secret 管理，别硬编码到 Git 仓库。我吃过这个亏，密码被提交到仓库之后泄露，只能一个个轮换。从那以后，所有敏感信息全部走环境变量，配置文件里只有process.env.E2E_USER这样的引用，否则再稳的 e2e 也是空架子。