企业官网建设流程全解析

提到 e2e，不同角色脑子里浮现的画面完全不一样：产品经理想的是“从登录到下单整条链路都能通”，开发想的是“终于有个东西能替我盯着核心流程别崩”，而真正动手写自动化测试的人最直接——这是自动化测试里最容易翻车、也最容易被质疑“你怎么又在修用例”的那部分工作。我在自动化测试这条路上走了五年多，从 Selenium 时代一路用到现在的 Playwright 项目，踩过的坑不夸张地说能写满一本流水账。这篇东西不打算复述官方文档，我想聊聊 e2e 到底测什么、框架怎么选、工程怎么搭、profile（测试画像）怎么管，以及 CI 流水线上那些让 e2e 从“本地能跑”变成“长期稳定”的细节。

1. E2E到底测什么：动手之前先搞清测试分层

1.1 单元、集成、端到端的分工边界

很多人把 e2e 理解成“多按几个按钮的UI测试”，这是最常见的误会来源。标准的测试金字塔把自动化测试分成三层：单元测试、集成测试、端到端测试。单元测试针对的是单个函数、单个组件，速度快、定位准，粒度最小；集成测试验证模块与模块之间能不能对上话，比如 Service 层和数据库、调用方和被调用方的接口契约；e2e 则是站在真实用户的视角，把整套系统当作一个黑盒，从打开浏览器开始，一路操作到业务终点，验证的是“整条链路合起来能不能兑现用户价值”。

三者的区别，我用一个生活化的类比来解释：单元测试相当于检查发动机里的每一个齿轮是否合格，集成测试相当于把变速箱和发动机装在一起看能不能咬合，e2e 则是把整车开到真实路面上，踩一脚油门跑一圈。齿轮都是好的、装起来也能转，并不代表整辆车开着就顺手——真实跑起来才会暴露怠速不稳、换挡顿挫、刹车响应慢这类系统级问题。

1.2 一个真实交易链路：E2E的价值藏在业务风险里

拿最常见的电商下单链路来说，登录、搜索商品、加入购物车、进入结算页、提交订单、调用支付、看到订单结果，这一串操作涉及前端页面、路由、状态管理、下单接口、库存系统、支付回调、订单中心至少七个环节。单测能保证每个页面组件渲染正确，集成测试能保证下单接口的参数和返回格式没问题，但“前端发出的请求字段”和“订单中心实际期望的字段”是不是一致，往往只有真实跑一遍才能暴露。

我在一个二手交易平台的项目里就遇过这种事故：下单接口联调时用的是旧版字段名，后来订单服务升级把字段名改了，前后端各自测试都通过，但因为改接口当天部署顺序出了问题，线上用户点“立即购买”直接报 500。这种级别的故障，靠单元测试和集成测试很难覆盖到，而一条 e2e 用例能在每次发布前就把它拦住。注意，e2e 不是说测完就能替代其他测试，它的价值在于覆盖“跨系统协作”这个最容易出事的盲区。

1.3 什么场景不该上E2E

与之相对，我也见过团队一上来就想把所有功能都写成 e2e，最后套件几百条用例、跑一次四十分钟、半数在修。E2E 的成本是明摆着的：执行慢、依赖环境、数据容易互相污染，维护成本远高于单测。我的经验是，只有三类场景值得上：一是业务的核心转化链路（注册登录、下单支付、内容发布这类）；二是跨系统、跨服务的复杂流程；三是高频变更、回归频繁的模块。而纯算法逻辑、内部管理后台的简单增删改查、还在频繁改 UI 的原型页面，都不适合硬写 e2e，硬上的结果就是天天陪跑、天天修。

2. 框架选型：从Selenium到Playwright，我为什么反复横跳

2.1 那些年被Selenium支配的日子

早年做 e2e 基本绕不开 Selenium。它兼容性广、支持多语言，但用过的人都知道痛在哪：没有自动等待，元素没加载出来就要你手动Thread.sleep或者写一堆WebDriverWait；脚本跑起来又慢又脆，稍微有一点动画、弹窗或者网络波动就开始随机失败；分布式跑还要自建 Selenium Grid，维护节点本身就是一个团队的负担。我印象最深的是有一次跑 30 条用例，其中有 12 条是“Element not clickable”挂掉的，点开日志发现全是等待策略不合理，真问题一个没查出来，光跟 flaky 死磕就耗了一天。

2.2 Playwright的自动等待和Web-first断言为什么省心

后来切到 Playwright，最直观的感受是“它默认帮你把等待做了”。Playwright 对每个操作都内置了可操作性检查：元素可见、稳定、不被遮挡、可点击，不满足条件就持续等待直到超时。所以大多数情况下，你不用再写显式等待，代码变得干净很多。它还引入了 web-first 断言，比如await expect(page.getByText('订单提交成功')).toBeVisible()，这个断言本身会轮询等待，最多等到超时时间，而不是“断言瞬间失败”。

另外一个让我彻底回不去的点是 trace 和 codegen。npx playwright codegen可以直接录制操作生成代码，调试时用npx playwright show-trace打开 trace 文件，能看到每一步操作、网络请求、DOM 快照和控制台日志。以前在 Selenium 里出问题只能靠截图和日志去脑补现场，现在相当于有了黑匣子。

2.3 Cypress和Playwright怎么挑

Cypress 的开发体验确实好，交互界面友好、文档亲切，前端工程师上手成本很低。但它的架构决定了它在浏览器里跑、命令队列式执行，历史上对多标签页支持差，跨域和 iframe 场景绕起来也比较累。如果你的站点大量依赖多标签页协作、嵌入第三方 iframe，或者团队测试代码用 Python/Java 写，Cypress 会让人越用越憋屈。Playwright 走的是协议层驱动，能同时控制多页面、多 context，语言支持也更广，所以我个人在需要跨端、跨域、复杂交互的场合理所当然地选了它。

2.4 一张表说清楚选型逻辑

如果你要新起一个 e2e 项目，我的建议很简单：团队全是前端、项目也纯前端，Cypress 可以很舒服；需要跨浏览器、多语言、复杂场景，直接选 Playwright，大概率不会后悔。Selenium 到今天，更多是历史包袱和存量项目的选择，而不是新项目的第一选项。

3. 搭一套能跑的E2E工程：目录、配置与第一个用例

3.1 项目结构：把选择器和测试逻辑分开

很多人的 e2e 项目长成“一个文件夹里堆满 spec 文件”，用例一多就开始失控。我现在的习惯是把工程拆成几个明确区域：tests/放测试用例，pages/放 Page Object，data/放测试数据和 profile 定义，auth/放登录态快照。下面是一个最小可用的 Playwright 项目结构：

e2e/ ├── playwright.config.ts ├── package.json ├── tests/ │ ├── auth.setup.ts │ ├── checkout.spec.ts │ └── smoke.spec.ts ├── pages/ │ ├── LoginPage.ts │ └── CheckoutPage.ts ├── data/ │ ├── profiles.ts │ └── users.ts └── auth/ ├── profile1.json └── admin.json

这样划分的原因很朴素：选择器是最容易变的，业务逻辑次之，测试用例应该是最稳定的层。一旦前端改了按钮文案、class 名，受影响的范围被控制在 Page Object 里，而不是散落到几十个用例文件中。

3.2 配置项里最容易犯的三个错

第一是 timeout 设置不合理。默认超时 30 秒在某些慢环境里不够，但很多人一上来就调成 90 秒，结果是真挂了也要等很久才知道。我建议普通操作保持 30 秒，个别慢接口的断言单独放宽到 60 秒。第二是 retries 在本地和 CI 不一致。本地调试时重试会掩盖问题，CI 里完全不重试又会让偶发问题直接打断开发，所以常见做法是retries: process.env.CI ? 2 : 0。第三是 workers 并行度和数据隔离没考虑好。默认并行数等于 CPU 核数，如果你的用例共享登录账号和测试数据，并行一开就互相踩，这部分我会在 profile 章节展开讲。

一个我常用的配置模板大概长这样：

import { defineConfig, devices } from '@playwright/test'; export default defineConfig({ testDir: './tests', timeout: 30000, retries: process.env.CI ? 2 : 0, workers: process.env.CI ? 2 : undefined, reporter: [['list'], ['html', { open: 'never' }]], use: { baseURL: process.env.E2E_BASE_URL || 'https://dev.example.com', trace: 'retain-on-failure', screenshot: 'only-on-failure', video: 'retain-on-failure', }, projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'] } }, ], });

这里 trace、screenshot、video 都配置成失败时才保留，本地调试不用每次清理一堆产物，CI 上又能拿到完整的失败现场。

3.3 第一个用例：从登录到看见用户名

工程搭好之后，第一个用例我强烈建议跑一条端到端的冒烟路径，不要一上来就写复杂场景。以登录为例，用 Playwright 写起来是这样：

import { test, expect } from '@playwright/test'; test('用户登录后能看到自己的用户名', async ({ page }) => { await page.goto('/login'); await page.getByLabel('用户名').fill('profile1@example.com'); await page.getByLabel('密码').fill('password123'); await page.getByRole('button', { name: '登录' }).click(); await expect(page.getByText('profile1@example.com')).toBeVisible(); });

注意这里选用的全是面向用户的选择器：getByLabel对应表单标签，getByRole对应按钮语义，getByText对应页面文案。它们比#login-btn、.header-user这类 class/id 选择器稳定得多，前端改样式不会影响这些用例。

3.4 Page Object不是公式，是一个取舍

Page Object 模式经常被当成银弹，其实它要解决的核心问题只有一个：当 UI 变化时，把修改集中到一处。所以我写 Page Object 的原则是“不为封装而封装”，一个页面最多暴露几个关键操作方法和断言方法，保持薄薄一层，别把十几步业务逻辑硬塞进一个类里。否则你只是把测试代码的复杂度从用例文件搬进了 Page 类，维护成本并没有消失，只是换了个位置。

4. Profile才是E2E的灵魂：多用户、多环境、多状态的切换

4.1 什么是E2E里的profile

搜“e2e profile1”的人，撞到这个词的概率很大——因为在真实项目里，测试并不是拿“一个普通用户”从头跑到尾的。你需要管理员、普通用户、VIP 用户、只读用户、被封禁用户等多种身份，还需要 dev、staging、prod 等多套环境，甚至还要考虑移动端、平板端等多类设备。把“身份 + 环境 + 设备”打包成一个可复用的配置，就叫 profile。我最早在项目里定义的第一套画像就叫 profile1，它的定义很简单：一个已登录的普通注册用户，跑在 dev 环境、Chromium 桌面端上。后面所有用例都是从这个 profile1 派生出来的。

4.2 用浏览器Context做登录态隔离

理解 profile 在 Playwright 里面的实现方式，关键在 browser context。每个 context 都是一块完全隔离的“浏览器实例”，Cookie、localStorage、sessionStorage 互不共享。也就是说，我可以开两个 context，一个带 profile1 的登录态，另一个带 admin 的登录态，它们在同一时间并行存在，互不干扰。

代码层面是这样：

import { chromium } from '@playwright/test'; const browser = await chromium.launch(); const userContext = await browser.newContext({ storageState: './auth/profile1.json', }); const adminContext = await browser.newContext({ storageState: './auth/admin.json', }); const userPage = await userContext.newPage(); const adminPage = await adminContext.newPage();

以前在没有 context 这个概念的时代，我们做多角色测试要反复退出登录、再登录，又慢又容易脏数据。现在每个角色一个 context，切换角色就是把 context 换一下而已。

4.3 storageState固化登录：把每个用例的登录成本降到零

E2E 用例最耗时间的部分往往是登录。如果 100 条用例每条都要走一遍登录流程，光登录就得吃掉十几分钟。更麻烦的是，登录过程本身也可能 flaky（验证码、滑块、短信）。Playwright 的解法是：先跑一次登录，把登录后的状态保存成storageState文件，后续用例直接复用。

官方推荐的做法是用一个 setup project 来完成这件事：

// tests/auth.setup.ts import { test as setup, expect } from '@playwright/test'; const authFile = './auth/profile1.json'; setup('登录并保存profile1登录态', async ({ page, context }) => { await page.goto('/login'); await page.getByLabel('用户名').fill('profile1@example.com'); await page.getByLabel('密码').fill('password123'); await page.getByRole('button', { name: '登录' }).click(); await expect(page.getByTestId('user-menu')).toBeVisible(); await context.storageState({ path: authFile }); });

然后在playwright.config.ts里声明依赖关系：

projects: [ { name: 'setup', testMatch: /.*\.setup\.ts/ }, { name: 'chromium', use: { ...devices['Desktop Chrome'], storageState: './auth/profile1.json' }, dependencies: ['setup'], }, ]

这样跑测试时，Playwright 会先执行 setup 生成登录态，再跑去其他用例。用例文件里不再需要任何登录代码，直接就能访问需要登录的页面。我实测下来，一套 60 条用例的回归套件，光这一项就能省下十分钟以上。

4.4 环境profile：一套用例跑dev/staging/prod

身份层面的 profile 解决了“你是谁”的问题，环境层的 profile 则解决“你在哪跑”的问题。我的做法是用一个配置文件把环境相关的变量收拢起来，测试代码里不出现任何硬编码域名：

// data/profiles.ts export const envProfiles = { dev: { baseURL: 'https://dev.example.com', apiBase: 'https://api-dev.example.com', accounts: { profile1: { username: 'profile1@example.com', password: 'dev-password' }, admin: { username: 'admin@example.com', password: 'dev-admin-password' }, }, }, staging: { baseURL: 'https://staging.example.com', apiBase: 'https://api-staging.example.com', accounts: { profile1: { username: 'profile1@example.com', password: 'staging-password' }, admin: { username: 'admin@example.com', password: 'staging-admin-password' }, }, }, prod: { baseURL: 'https://www.example.com', apiBase: 'https://api.example.com', accounts: { profile1: { username: 'smoke-profile1@example.com', password: 'prod-smoke-password' }, }, }, } as const;

再通过环境变量指定当前跑哪套：

E2E_ENV=staging npx playwright test --project=chromium

配置文件里把baseURL指向对应环境的地址，storageState 的生成也按环境分开存放，比如auth/staging-profile1.json。这里有个安全提醒：生产环境的 profile 密码应该是专用的冒烟账号，绝不能拿真实用户账号写进代码库。生产环境我也只会跑冒烟用例，不会跑全量回归，免得对线上数据造成影响。

4.5 profile1的教训：测试数据必须隔离

我可以直接说，e2e 项目里遇到的绝大多数“灵异失败”，最后查出来都是测试数据污染。我自己就栽过一次：profile1 这个账号在测试环境混了好几年，所有涉及登录态的用例都复用它。某天开始，用例随机失败，报错要么是“用户不存在”，要么是“密码错误”。排查了半天才发现，有一条测试密码修改流程的用例把 profile1 的密码改了，而且它和别的用例并行执行，执行顺序每次都不同，所以失败完全随机。

从那以后我定了几条铁律：每个 profile 对应专属账号，绝不同时复用；用例里产生的数据必须带唯一前缀，比如-${Date.now()}-${process.pid}，跑完留在库里也能知道是谁创建的；破坏性操作只跑在独立创建的临时数据上，通过 API 清理而不是 UI 层层点删除。这些规则不是锦上添花，是 e2e 能长期稳定运行的前提。测试数据都不隔离，用例写得再漂亮也是空中楼阁。

5. 从flaky到稳定：一次完整的E2E排查链路复盘

5.1 flaky头号病因：等待与selectors

如果给 e2e 的不稳定排一个原因榜，前两名一定是等待和选择器。以前在 Selenium 时代，很多人习惯Thread.sleep(2000)硬等，后来用 Playwright 的习惯变好了一些，但我仍然见过有人在代码里写page.waitForTimeout(5000)去等一个接口响应。硬等的本质是“赌”，赌 5 秒内什么事情都会发生完——一旦环境慢一点，5 秒不够，用例就挂；环境快一点，又白等 5 秒，套件被拖得很慢。正确的姿势是用条件等待：等元素可操作、等接口响应、等网络空闲，Playwright 的自动等待和expect轮询就是为了处理这件事。

选择器问题则多出在“过于具体”的定位上。比如用 XPath 的//*[@id="app"]/div[2]/div[1]/span，前端稍微加个节点就崩。我现在的做法是优先用用户可感知的语义：按钮用getByRole，输入框用getByLabel，文案用getByText，实在没有合适语义再退到>expect received value must be a string

这个报错根本没指出问题在哪。首先我拿到了失败时自动保存的截图，发现页面停在“支付成功”弹窗上，按常理断言应该通过才对。接着打开 trace 文件，逐步回放失败前的操作，发现诡异之处：点击“确认支付”按钮后，页面先弹出了成功提示，但紧接着一个 banner 广告从页面顶部滑入，把弹窗里的“订单号”文字遮挡了一部分，导致getByText在解析时拿到了被截断的文本节点。

根因是广告组件的懒加载延迟触发，晚于支付成功回调。修复不是去调整测试，而是先跟前端确认这个行为是否合理。前端觉得广告遮住内容本身是个 bug，于是改成延迟出现且不出现在支付成功弹窗之上。改完之后，用例没动一行代码，连续一周没再失败。这次经历让我养成了习惯：e2e 失败不要急着改用例，先当“活 bug”处理，确认不是线上/测试环境问题，再考虑测试侧修复。

5.3 数据污染的完整定位过程

另一类更隐蔽的 flaky 是数据污染。有一次冒烟套件在本地单线程跑怎么都过，一上 CI 就随机挂，而且挂的用例每次还不一样。我先把 retries 调到 0、限制 workers=1，发现套件稳定通过；再把 workers 调成 4，又随机挂。这一下就锁定了方向：并行导致的数据竞争。

顺着这个方向，我打开失败用例的 trace，发现某个用例读取的商品库存数量是负数，另一个用例的订单里混进了别人的收货地址。最后定位到根因：所有测试共用一个商品池，多条用例并行下单，各自以为抢到了唯一库存，实际上库存字段已经被另一边改掉了。修复方案是在每个用例里用 API 动态创建专属商品数据，用例结束时再清理。听起来简单，但当时我们翻了整整一个下午的日志才把“并行执行”和“共享数据”这两个词联系起来。这也是为什么我说 profile 章节里的数据隔离不是理论，而是血泪教训。

5.4 怎么判断修复有效：不是“跑过一次就算赢”

修完 flaky 之后，最忌讳的就是“跑了一次通过，就宣告胜利”。我给出的验证方法是：先用--repeat-each=10在本地把这条用例连跑十遍，观察有没有间歇失败；再到 CI 上连续触发三次，对比每次结果。如果都稳定，再观察一周内的失败率。很多 flaky 的复现概率本来就不高，跑一次两次说明不了任何问题，只有足够多的样本量才能让“修复有效”这个结论站得住脚。另外，务必要看 retries 数据：如果 CI 里一条用例总是第一次失败、重试后才过，那它就是潜藏的 flaky，迟早会在某次部署窗口期咬你一口。

6. 把E2E塞进CI：从“本地能跑”到“流水线稳定”

6.1 CI环境里绕不开的三个坑

本地跑得好好的，一上 CI 就挂，这事几乎所有人都遇到过。第一坑是浏览器依赖缺失。Playwright 虽然能通过npx playwright install装浏览器，但 CI 环境还缺一堆系统库，完整命令是npx playwright install --with-deps chromium。忘了--with-deps，启动浏览器时会报各种动态链接库错误。第二坑是无头模式下的字体渲染，截图里文字糊掉或元素偏移，大多是因为 CI 镜像没有全部字体，装一下fonts-noto之类的包能解决大部分显示问题。第三坑是 artifact 没保留，跑完就删，失败后根本没有分析素材。CI 上一定要把playwright-report/和test-results/上传到构建物，否则排障等于闭着眼睛开车。

下面是一个我一直在用的 GitHub Actions 工作流片段：

name: e2e on: push: branches: [main] workflow_dispatch: jobs: e2e: 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 --shard=1/3 - uses: actions/upload-artifact@v4 if: failure() with: name: playwright-report path: playwright-report/ retention-days: 7

6.2 并行、分片和资源控制

E2E 跑得慢是客观现实，但并行不能无脑开。CI 上 2 个 worker 是我的默认起点，原因有两个：跑测试的机器内存有限，开太多 worker 会出现浏览器进程被杀；更重要的是，并行 worker 越少，测试数据冲突的概率就越低。如果套件规模变大，更推荐用分片而不是单纯加 worker——把测试用例按数量分成几片，每片跑在独立的 runner 上，比如--shard=1/3表示当前 runner 只跑第一片。这样每台机器负载稳定，数据隔离也更容易做。我见过有人把 workers 调到 16，结果套件没快多少，反而因为资源争抢引入了大把 flaky。

6.3 Smoke与全量回归的分梯队策略

不可能每次都把几百条 e2e 全跑一遍，尤其是 PR 阶段。我用标签把用例分成梯队：@smoke标记核心链路冒烟用例，@regression标记全量回归用例。PR 上只跑 smoke， nightly 定时任务跑全量回归。代码里只需要加一个 tag：

test('用户能完成下单支付', { tag: '@smoke' }, async ({ page }) => { // 用例内容 });

跑的时候用--grep过滤：

npx playwright test --grep @smoke

这个分层策略最直接的效果是：PR 阶段反馈时间从三十分钟缩短到五分钟，而真正的完整保障并没有丢掉，只是挪到了晚上批量执行。

6.4 维护成本控制：我坚持的几条纪律

最后这部分不是工具技巧，而是团队纪律，我花了很多年才意识到它比任何配置都重要。

第一，测试代码也是代码，需要评审。我看到过太多“测试代码随便写”的团队，最后全在给测试擦屁股。第二，E2E 不是用来追覆盖率的，不要试图覆盖每一个分支，核心链路才是它的主场；为了省时间，非 UI 临界的前置状态尽量通过 API 直接搭建，UI 留给真正需要验证的用户行为。第三，定期裁掉没有价值的用例。业务已经下线的页面、长期 override 的断言、从来没有抓到过 bug 的纯功能验证，这些都要及时清理，套件越臃肿，维护成本越高，失败时定位越难。第四，给套件设一个执行时间预算，全量回归控制在十五分钟左右，一旦超出，先裁用例而不是加机器。

我自己的一个习惯是，每次接手一个新项目的 e2e 测试，先不急着写架构和框架，而是先问业务同事一句：最值钱的那条业务链路是什么？然后从那里开始写第一条用例。profile 从这条链路需要的第一个用户身份开始定义，环境配置从这条链路实际部署的环境开始建。剩下的一切——更多角色、更多用例、更完善的 CI——都是在这条主线上慢慢长出来的。五年下来，真正让我觉得 e2e 有价值的时刻，从来不是某个自动化覆盖率数字变得好看，而是某天凌晨 CD 上的一条失败通知，恰恰拦住了明天早高峰要发生的事故。