企业官网建设流程全解析

如果你去翻任意一家稍微有点规模的互联网公司的测试用例库，大概率会看到一类文件名里带e2e的项目。e2e 这三个字母在行业里的固定含义是 end-to-end，端到端测试。说人话就是：站在用户角度，把整个产品当一台真车去路试，而不是只测某个零件。今天我想把这几年真实跑 e2e 测试踩过的坑、总结出来的经验，整理成一篇能直接照着上手的笔记，从概念、选型、落地到排查，一次讲透。这篇内容既适合刚接触前端测试的新人，也适合正在被用例稳定性折磨的后端、前端、测试同学。

很多人最早接触 e2e 是因为"线上出了 bug，但单元测试和接口测试全绿"。这几乎是每个技术团队都会经历的尴尬时刻。单元测试验证的是代码段逻辑，接口测试验证的是数据交互，但用户根本不在乎你的函数返回值，他关心的是：登录、搜索、加购物车、下单、付款、看到订单，这一整条路能不能走通。e2e 要验证的恰恰是这条完整链路，它把你的系统当作一个黑盒，从用户入口开始，一路点到用户出口，中间任何一个环节断了，用例就会红。

这篇文章不会只讲理论。我会从测试金字塔说起，解释为什么团队需要 e2e，然后对比主流的工具选型，接着给出一套可以直接复制的项目结构和核心用例写法，最后把我实际遇到的高频问题和排查思路全部摊开。如果你正在犹豫要不要引 e2e，或者已经被一堆 flaky 用例折磨到想删库跑路，这篇文章应该能帮你省下不少时间。

1. e2e 到底是什么？先把它放在整个测试体系里看

1.1 测试金字塔到底在说什么

测试金字塔是行业里一个老掉牙但至今不过时的模型。它把测试分成三层：底层是数量最多、跑得最快的单元测试，中间是接口测试或集成测试，顶层是数量最少、成本最高的 e2e 测试。很多团队一上来就猛写 e2e，结果用例又慢又脆，最后离题万里。问题的根源就是没搞懂金字塔的分工。

我习惯用一个造车的类比来解释：单元测试好比逐个检测螺丝、齿轮、电路板，确认每个零件本身没问题；接口测试好比把发动机、变速箱、底盘组装起来，检测部件之间的咬合；e2e 测试则是整车路试，点火、踩油门、打方向、过弯、刹车，整个流程走下来，看驾驶员体验正不正常。零件没问题不代表车好开，这正是 e2e 的价值。

从投入产出比看，单元测试单个用例耗时几毫秒，e2e 单个用例动辄几秒甚至几十秒，因为它要启动真实浏览器、真实页面、走真实网络请求。所以行业里普遍认可的比例是：单元测试占大头，e2e 只覆盖最关键的核心路径。你可以没有几百条 e2e，但必须有那几条"挂了就完蛋"的核心主流程 e2e。

1.2 e2e 能解决什么，又解决不了什么

e2e 最大的价值是"信心"。每次发版前，只要核心链路用例是绿的，你就敢点发布按钮。它能发现模块联调的问题、前端页面与后端接口不匹配的问题、权限控制的问题、路由守卫漏配的问题、甚至某些样式遮挡导致按钮点不了的问题。这些问题在单元测试和接口测试里几乎不可能暴露，因为它们发生在真实用户交互的边界上。

但 e2e 不是万能药。它测的是"流程是否通"，不是"逻辑是否对"。比如金额计算错误、优惠券叠加规则写错，只要页面没报错，e2e 照样绿。这类问题要靠单测和代码评审去兜。另外 e2e 慢、贵、容易不稳定，这一点必须提前有心理预期。如果你们团队的用例动不动跑四十分钟，又不做并行和分片，那基本没人愿意在看板上等它。

接受 e2e 的定位很重要：它是一张安全网，不是全部测试。你的单测、接口测试、代码评审越扎实，e2e 就越省心；反过来指望靠 e2e 掩盖所有质量问题，只会把用例维护活活拖成事故现场。

1.3 "e2e profile1"这类热词的背后，其实是运行档案的概念

最近总能看到"e2e profile1"这类的热词被搜来搜去。我猜大部分人想查的是"e2e 测试里 profile 到底是什么"。这个词在 e2e 工程里非常常见，通常指"配置档案"或"运行环境档位"。

你可以把 profile 理解为一份预置的"身份和环境套餐"：普通用户档案、管理员档案、游客档案、移动端分辨率档案、预发环境档案、灰度环境档案。每条 e2e 用例跑的时候，都会基于某个 profile 启动浏览器、注入登录状态、指定环境地址。这么做的好处是，同一套用例代码可以在不同 profile 下重复执行，不用改一行逻辑。

所以后面我讲到工程落地的部分时，会把 profile 的设计单独拎出来说。它不是花花架子，而是让 e2e 工程能并行、能复用、能分环境跑的地基。

2. 工具选型：Playwright、Cypress、Selenium 到底怎么选

2.1 三驾马车的定位差异

选 e2e 工具这件事，团队里经常吵得不可开交。我给你的建议是：先别管谁粉丝多，先看它的架构适不适合你的场景。

Selenium 是这个领域的老前辈，基于 WebDriver 协议，支持 Java、Python、C#、JS，生态最广，很多老项目在用它。优点是语言覆盖最全、能接各种云测设备平台；缺点是写起来繁琐，要自己处理显式等待，用例一多稳定性就看人品了。它给你的是一堆 API，不是一个完整的测试框架，断言、报告、重试全部要靠自己组装。

Cypress 是另一条路线。它把执行引擎跑在浏览器内部，所以安装轻、调试体验好，时间回溯功能非常帅，前端开发者上手很快。但它的架构决定了它在多标签页、跨域场景上有天然的短板，虽然官方这些年一直在补，但和 Playwright 相比，这类场景依旧不是它的主场。另外它支持的浏览器范围也相对受限，如果你要覆盖 Safari，它就不是首选。

Playwright 是微软开源的项目，后来捐给了 Linux 基金会，走的是浏览器调试协议（CDP / WebSocket）路线，架构上把浏览器控制能力做得非常底层。它内置了等待机制、多浏览器支持、多页面支持、浏览器上下文、测试 runner、trace 录像、自动重试，几乎把 e2e 需要的东西一次性打包好了。它的语言绑定支持 JS/TS、Python、Java、C#，覆盖面同样不差。

如果只是快速对比，可以记下面这张表：

2.2 我为什么最终把主力放在 Playwright 上

我们团队是从 Selenium 转到 Playwright 的，转完后的第一感受是"用例终于不靠运气了"。Selenium 时代最折磨人的就是 waiting：元素还没出来你就去点，点不到就等，等多久全凭经验。Playwright 的自动等待是内置的动作前置条件，它会自动轮询元素可见、可点、稳定，直到超时。绝大多数时候你不必写sleep，代码干净很多。

还有一个 Killer 功能是浏览器上下文（browser context）。每个上下文都是一个完全隔离的浏览器会话，相当于一个独立的"隐身窗口"。这意味着我可以为不同 profile 启动互不干扰的会话：普通用户一个上下文，管理员另一个上下文，两边 cookie、localStorage、缓存全部隔离。跑完即焚，不留痕迹。这在 Cypress 里要绕很多路，在 Playwright 里是原生能力。

再说诊断能力。e2e 用例跑挂了最怕的是什么？是跑挂了但你不知道页面当时长啥样。Playwright 默认可以在失败时自动截图、录视频、保存 trace。trace 里能看到每一步的 DOM 快照、网络请求、控制台日志和光标位置，排查问题基本不用再去问前端"你页面是不是改了什么"。这套东西对稳定性的帮助，远比你想象中大。

另外 Playwright 自带 codegen 工具，可以在浏览器里点操作自动生成脚本。我不会建议你完全依赖它，因为生成的脚本定位符很啰嗦，但用来快速探索页面结构、确认某个按钮的稳定定位方式，效率很高。

2.3 项目里的 profile 档案怎么设计

回到前面说的 profile。在 Playwright 工程里，我用「project + storageState」的组合来实现多档案执行。

简单说，一个 project 对应一个浏览器+设备+环境+登录态的组合。登录态用storageState表示，它是一份包含 cookie 和 localStorage 的 JSON 文件。跑全局 setup 的时候登录一次，把状态存成文件，后续的每个 project 都可以直接复用，不用每个用例都走一遍登录流程。这样 e2e 跑起来能省掉大量重复动作，同时保证每个用例的身份是干净的。

典型的档案划分是：普通用户档案（profile1）、管理员档案（profile2）、游客档案（profile3）、移动端档案（profile4）。具体用什么粒度，取决于你的业务有多少种身份。注意档案不是越多越好，每多一个档案，整套用例的执行时间就要乘一个系数。我建议先覆盖最重要的三到四种身份，别一上来就铺十来个矩阵。

3. 从零搭一套能落地的 e2e 测试工程

3.1 目录结构与基础配置

我会直接用一个最小可运行的前端项目作为例子。假设技术栈是 React + Vite，Node 版本在 18 以上，先装 Playwright 测试框架：

npm init -y npm install -D @playwright/test npx playwright install chromium

npx playwright install会下载浏览器内核，如果不挂在公网环境，可以配置镜像源，这里不展开。装完之后，目录结构可以这样组织：

project-root/ ├── playwright.config.ts ├── .auth/ │ ├── user.json │ └── admin.json └── tests/ └── e2e/ ├── global-setup.ts ├── login.spec.ts └── order.spec.ts

playwright.config.ts是核心配置文件。我会把环境地址、超时时间、截图录像策略、project 档案都放在这里：

import { defineConfig, devices } from '@playwright/test'; export default defineConfig({ testDir: './tests/e2e', timeout: 30_000, expect: { timeout: 5_000 }, fullyParallel: true, workers: process.env.CI ? 1 : undefined, retries: process.env.CI ? 2 : 0, reporter: [['html', { open: 'never' }]], use: { baseURL: process.env.E2E_BASE_URL || 'https://staging.example.com', headless: true, screenshot: 'only-on-failure', video: 'retain-on-failure', trace: 'retain-on-failure', }, projects: [ { name: 'profile1-chromium', use: { ...devices['Desktop Chrome'], storageState: '.auth/user.json' }, }, { name: 'profile2-admin', use: { ...devices['Desktop Chrome'], storageState: '.auth/admin.json' }, }, ], });

有几点我想特别提醒。retries我在 CI 里开 2，本地开 0，因为重试是给不稳定环境兜底的，本地开发要的是快速反馈。workers在 CI 里设置为 1 不是为了让跑得慢，而是避免用例之间因为共享数据库数据互相打架，等用例稳定了再开并行也不迟。baseURL用环境变量注入，这样同一份用例可以在 dev、staging、prod 环境之间切换，前提是各环境数据准备到位。

3.2 核心用例长什么样

我们写一条最经典的"用户下单"用例。新手最容易犯的错，是上来就写一大堆步骤，每个步骤都点得很急。我会尽量让思考过程可见：

import { test, expect } from '@playwright/test'; test('profile1 普通用户完成下单', async ({ page }) => { // 访问首页，打开登录框 await page.goto('/'); await page.getByRole('button', { name: '登录' }).click(); // 填写账号密码 await page.getByLabel('账号').fill('user001'); await page.getByLabel('密码').fill('pass001'); await page.getByRole('button', { name: '确认登录' }).click(); // 登录成功标志 await expect(page.getByText('欢迎回来')).toBeVisible(); // 搜索商品 await page.getByPlaceholder('搜索商品').fill('无线耳机'); await page.keyboard.press('Enter'); // 打开第一个商品详情 await page.locator('[data-testid="product-card"]').first().click(); // 加入购物车，断言购物车角标变化 await page.getByRole('button', { name: '加入购物车' }).click(); await expect(page.locator('.cart-badge')).toHaveText('1'); // 进入购物车并提交订单 await page.goto('/cart'); await page.getByRole('button', { name: '去结算' }).click(); await page.getByRole('button', { name: '提交订单' }).click(); // 最终结果断言 await expect(page.getByText('下单成功')).toBeVisible(); });

这里藏着几个常见的坑。第一，定位符优先用 role、label、placeholder 这类用户可见属性，少用一长串的 CSS 类名，因为前端重构时 CSS 类名说改就改，而按钮名字"提交订单"在业务意义上稳定得多。第二，>import { request } from '@playwright/test'; import { writeFile } from 'fs/promises'; export default async function globalSetup() { const ctx = await request.newContext({ baseURL: process.env.E2E_BASE_URL, }); const resp = await ctx.post('/api/login', { data: { username: 'user001', password: 'pass001' }, }); if (!resp.ok()) { throw new Error(`登录失败: ${resp.status()}`); } const state = await ctx.storageState(); await writeFile('.auth/user.json', JSON.stringify(state)); await ctx.dispose(); }

然后在playwright.config.ts里把这个 setup 注册进去，再把storageState指到输出文件。之后 profile1 下的所有用例启动时，浏览器里就已经带着登录 cookie 了，直接进入业务操作。

测试账号这块我强烈建议不要用线上真实用户账号。专门准备一批测试账号，密码规定好，权限固定，甚至用脚本定时重置。账号密码写在哪里也有讲究，可以直接放在环境变量或者一个不入库的配置文件中，配合各环境单独维护一份。

3.4 数据隔离、清理与稳定性策略

e2e 用例跑多了，最让人头疼的不是代码，而是数据。今天下单用例创建了一个订单，明天同一批数据还在库里，再跑一遍可能就出现"库存不足""重复提交"这类问题。

常规的做法有三板斧。第一，用例数据尽量唯一化，比如用户名直接用user_${Date.now()}，这样每次执行都产生新数据，不会撞车。第二，用例结束前做数据回收，通过 API 调用删除刚创建的订单、商品、记录，而不是在 UI 上点删除按钮，UI 删除动作也应该被测试，但它不适合用来做清理。第三，对于清理成本极高的数据，可以接数据库连接，在 setup 阶段把相关表重置到快照状态。

还有并行策略。Playwright 默认每个用例一个浏览器上下文，并行度很高，但如果多个用例同时写同一个账号的购物车，就会互相踢掉登录态。我会把用例按照 profile 划分，不同的 profile 用不同账号，同一个 profile 内的用例用同一账号，但要保证它们操作的资源互不重叠。这是 e2e 稳定性最容易被忽略的一环。

4. 真实项目里踩过的坑与排查实录

4.1 最常见的翻车现场：strict mode violation

这是我见过最多的一条报错：locator resolved to 2 elements.它的意思是你的定位符太宽了，页面上有好几个元素都能匹配上，Playwright 不知道你要操作哪一个。

比如页面上有"登录"按钮出现在弹窗里，同时导航栏也有一个"登录"入口。你写getByRole('button', { name: '登录' })，就会撞上 strict mode 的拦截。解决办法不是.first()一把梭，那是掩耳盗铃，以后页面结构调整时会继续挂。正确做法是让定位符更精确：限定弹窗容器，或者用getByRole('dialog').getByRole('button', { name: '登录' })，让它只匹配期望范围内的那个。

在项目里维护一套稳定的>await expect(page.getByText('下单成功')).toBeVisible();

这个断言默认会在 5 秒内反复检查，直到元素出现或超时。它比固定 sleep 更智能，因为条件满足会立刻返回，条件不满足也不会盲目等待。把expect的 timeout 调大到 10 秒、15 秒作为兜底，整体稳定性会好很多。记住一个原则：等待"结果"而不是等待"时间"。

4.3 数据污染与并发冲突

并行执行是 e2e 提速的王道，但并行是有代价的。我们曾经在一次发布前跑 8 个 worker，结果用例之间互相把对方创建的订单给删了，红了一大片。排查的时候发现，两个用例用同一个测试账号登录，一个人在购物车页面选商品，另一个人已经结算清空了购物车。

后来建立了两个规则。规则一：一个账号同一时刻只能被一个 worker 使用，可以通过用例名称做账号选择，比如user_${test.info().workerIndex}。规则二：核心业务数据，比如订单、支付单，用带时间戳的唯一标识生成。这看起来是测试代码的细节，实际上它决定了你的用例在 CI 上是稳定 20 分钟跑完，还是频繁挂给你看。

另外一个隐蔽的数据坑是"测试环境漂移"。预发环境被产品同学手工点了一堆数据进去，你的用例假设页面是空白的，结果一进去全是别人的脏数据。这种情况要去推动环境治理：e2e 用独立环境，谁都不许手点，需要数据就调接口造。

4.4 CI 上的无头模式与失败取证

本地跑得好好的 e2e，一上 CI 就挂，这是标准剧本。原因不外乎几个：CI 上没有显示器，浏览器跑在无头模式，某些依赖 GPU 或系统字体的渲染会有差异；CI 的网络到测试环境更慢；CI 时间和本地时区不同。

我的建议是，从第一天起就让 e2e 在无头模式下跑，不要让"本地有头能过"成为一种幻觉。CI 脚本里明确设置headless: true，并固定浏览器版本，不要让它自动升级，浏览器一升级，行为就可能变。Playwright 的浏览器安装在~/.cache/ms-playwright下，CI 上通过npx playwright install --with-deps chromium安装固定版本，每次跑都是同一个内核。

失败取证方面，前面配置里的trace: 'retain-on-failure'会保留失败用例的完整录制。trace 文件可以打开 Playwright Trace Viewer 查看，能看到每一步操作前的 DOM 快照、页面截图、网络请求耗时、控制台报错。排查 CI 上偶发的失败，这个工具比任何日志都好用。

4.5 常见问题速查表

我把实际工作中遇到的高频问题整理成一张表，留着排查时当字典用：