企业官网建设流程全解析

1. 从“e2e”说起：端到端测试到底在测什么

第一次看到“e2e”这个词，很多人会以为是某个新框架的缩写，或者某个内部项目的代号。其实它就是end-to-end的简写，中文叫“端到端”。在软件研发语境里，e2e 测试指的是：从用户真实操作的入口开始，一路走到系统最末端，验证整条链路上每个环节是否都能正常协作。它不关心某个函数写得对不对，也不关心某个接口返回的字段格式是否优雅，它只关心一件事——用户点下去之后，结果对不对。

我做了十多年一线研发和测试，见过太多团队把 e2e 当成“高级一点的集成测试”来用，结果写出来的用例又慢又脆，三天两头挂，最后被 CI 流水线嫌弃，直接标记成“非阻塞”。这其实是对 e2e 最大的误解。e2e 的价值不在于覆盖多少代码，而在于它模拟的是真实用户路径，它验证的是“系统作为一个整体，能不能把一件事办成”。这个定位决定了它的写法、运行时机、维护策略，跟单元测试、集成测试完全不是一回事。

那 e2e 到底适合谁来写、谁来用？我的经验是：测试工程师负责设计场景和断言，前端/后端研发负责提供稳定的测试数据和可测性支持，DevOps 负责把运行环境跑通。三方缺一不可。如果你是一个刚接触 e2e 的同学，或者团队正准备从零搭建 e2e 体系，那这篇内容就是写给你的。我会从设计思路、工具选型、实操步骤、常见坑几个角度，把 e2e 这件事讲透，让你看完就能动手搭一套能跑、能维护、能进 CI 的 e2e 方案。

2. e2e 测试的整体设计与思路拆解

2.1 为什么 e2e 不能照搬单元测试的写法

单元测试的核心是“隔离”，把依赖全部 mock 掉，只测一个函数或一个类。e2e 的核心恰恰相反，它要的是“真实”——真实浏览器、真实网络请求、真实数据库、真实第三方服务（或者至少是高度仿真的沙箱）。这两者的设计哲学是冲突的。如果你用写单元测试的思路去写 e2e，比如把登录接口 mock 掉，那你就不是在测端到端，而是在测“前端页面在假设后端永远正确的情况下能不能渲染”。这种用例跑得再快，也发现不了“登录接口超时导致页面白屏”这类真实问题。

所以 e2e 的设计原则第一条就是：尽量少 mock，能走真实链路就走真实链路。那什么时候可以 mock？我的经验是，只有两种情况值得 mock：一是第三方支付、短信这类无法在测试环境真实调用的外部服务；二是某些极端异常场景，比如“数据库连接池耗尽”，这种在真实环境很难稳定复现，可以用 mock 来模拟。除此之外，一律走真实。

2.2 测试金字塔里的 e2e 应该占多少

经典的测试金字塔是：单元测试最多，集成测试次之，e2e 最少。但“最少”到底是多少？很多团队拍脑袋说“10% 吧”，结果写了 200 条 e2e，跑一次要 40 分钟，维护成本爆炸。我的建议是：e2e 用例数量控制在 20 到 50 条之间，覆盖核心用户旅程即可。什么叫核心用户旅程？就是“如果这条路径断了，业务就挂了”的那些场景。比如电商系统的“浏览商品→加入购物车→下单→支付→查看订单”，比如 SaaS 系统的“注册→登录→创建项目→邀请成员→导出数据”。这些路径每条写 1 到 2 条 e2e，加起来不会超过 50 条。

那剩下的覆盖率怎么补？靠集成测试和单元测试。e2e 不追求覆盖率，它追求的是对核心业务流的信心。你可以在 CI 里把 e2e 设成“每日构建跑一次”或者“合并到主分支前跑一次”，而不是每次提交都跑。这样既保证了核心路径的验证，又不会拖慢开发节奏。

2.3 环境策略：本地、CI、预发怎么分工

e2e 最头疼的问题之一就是环境。本地跑一套，CI 跑一套，预发又跑一套，结果三套环境行为不一致，用例在本地过、在 CI 挂。我的做法是：尽量让本地和 CI 使用同一套容器化环境。用 Docker Compose 把前端、后端、数据库、缓存全部编排起来，本地开发用docker compose up启动，CI 里也用同一份 compose 文件。这样环境差异被压到最小。

预发环境则用来跑“冒烟级”的 e2e，也就是最核心的那 5 到 10 条用例，在每次发布前跑一遍，确认没有致命问题。预发环境的数据是接近生产的，所以能发现一些在测试环境发现不了的问题，比如数据量大了之后的分页性能问题、某些配置项在生产才生效的问题。

注意：千万不要在预发环境跑会写数据、发短信、发邮件的 e2e 用例，除非你有完善的清理机制。我见过一个团队在预发跑下单用例，结果真的生成了几百条测试订单，最后人工删了一下午。

3. 核心细节解析与实操要点

3.1 工具选型：Playwright、Cypress、Selenium 怎么选

工具选型是 e2e 落地的第一道坎。目前主流的三款是 Playwright、Cypress 和 Selenium。我直接给结论：新项目一律优先考虑 Playwright。原因有三点：第一，它原生支持多浏览器（Chromium、Firefox、WebKit），而且不需要额外装 driver；第二，它的自动等待机制做得最好，很多场景不需要你手写waitFor，减少了 flaky 用例；第三，它支持多标签页、多窗口、文件下载、网络拦截，功能覆盖最全。

Cypress 的优势在于开发体验好，调试界面漂亮，但它的架构决定了它很难做多标签页测试，而且跨域访问限制比较多。Selenium 是最老牌的，生态最全，但它的 API 比较底层，自动等待需要自己封装，新手容易写出不稳定的用例。

3.2 选择器策略：为什么 class 选择器是灾难

e2e 用例脆弱的头号原因就是选择器写得太随意。很多同学喜欢用 CSS class 来定位元素，比如.btn-primary、.login-form input。这种写法在页面改版时必挂，因为 class 名是最容易变的。我的建议是：优先使用>// 示例：在 beforeEach 中创建测试用户 test.beforeEach(async ({ request }) => { const res = await request.post('/api/test/users', { data: { email: `e2e-${Date.now()}@example.com` } }); testUser = await res.json(); }); test.afterEach(async ({ request }) => { await request.delete(`/api/test/users/${testUser.id}`); });

4. 实操过程与核心环节实现

4.1 从零搭建 Playwright e2e 项目

假设你现在要在一个 Web 项目里从零搭 e2e，我按步骤带你走一遍。首先初始化项目：

mkdir e2e-tests && cd e2e-tests npm init -y npm install -D @playwright/test npx playwright install

然后创建playwright.config.ts，这是核心配置文件。我一般会配置三件事：baseURL、重试次数、报告器。baseURL 让用例里可以直接写/login而不是完整 URL；重试次数设成 1 到 2 次，用来对抗偶发的网络抖动；报告器用 HTML 加 list，方便本地看和 CI 存档。

import { defineConfig } from '@playwright/test'; export default defineConfig({ testDir: './tests', retries: 1, use: { baseURL: process.env.BASE_URL || 'http://localhost:3000', trace: 'on-first-retry', screenshot: 'only-on-failure', }, reporter: [['list'], ['html', { open: 'never' }]], });

trace: 'on-first-retry'这个配置非常关键。它会在用例第一次失败重试时录制完整的操作轨迹，包括每一步的 DOM 快照、网络请求、控制台日志。排查 flaky 用例时，打开 trace 文件就像看录像回放一样，能直接定位到是哪一步出了问题。

4.2 写第一条核心旅程用例

以登录为例，写一条完整的 e2e 用例：

import { test, expect } from '@playwright/test'; test('用户可以使用邮箱密码登录并看到仪表盘', async ({ page }) => { await page.goto('/login'); await page.getByTestId('email-input').fill('e2e-user@example.com'); await page.getByTestId('password-input').fill('Test123456'); await page.getByTestId('login-button').click(); await expect(page).toHaveURL('/dashboard'); await expect(page.getByTestId('welcome-message')).toContainText('欢迎'); });

这条用例看起来简单，但里面有几个细节值得说。第一，getByTestId比locator('.email')稳定得多。第二，expect(page).toHaveURL自带自动等待，不需要手写waitForTimeout。第三，断言要具体，不要只断言“页面没报错”，要断言“看到了欢迎消息”，这样才能真正验证业务逻辑走通了。

4.3 参数化与数据驱动

如果同一个流程需要用不同角色验证，比如“普通用户登录看到 A 菜单，管理员登录看到 B 菜单”，可以用参数化：

const roles = [ { role: '普通用户', email: 'user@example.com', expectedMenu: '我的项目' }, { role: '管理员', email: 'admin@example.com', expectedMenu: '系统设置' }, ]; for (const { role, email, expectedMenu } of roles) { test(`${role}登录后能看到对应菜单`, async ({ page }) => { await page.goto('/login'); await page.getByTestId('email-input').fill(email); await page.getByTestId('password-input').fill('Test123456'); await page.getByTestId('login-button').click(); await expect(page.getByTestId('side-menu')).toContainText(expectedMenu); }); }

这种写法比复制粘贴两条用例优雅得多，而且新增角色只需要加一行数据。

4.4 接入 CI 流水线

e2e 最终要进 CI 才有价值。以 GitHub Actions 为例，核心配置如下：

name: e2e on: pull_request: branches: [main] jobs: test: 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 - run: docker compose up -d - run: npx playwright test - uses: actions/upload-artifact@v4 if: failure() with: name: playwright-report path: playwright-report/

这里的关键点是：失败时上传报告。CI 里跑挂了，你不可能坐在那里看日志，把 HTML 报告和 trace 文件传上去，下载下来本地打开，排查效率高十倍。

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

5.1 用例不稳定（flaky）怎么办

flaky 是 e2e 的头号敌人。一条用例今天过明天挂，跑三次挂一次，最消耗团队信心。排查 flaky 我一般按这个顺序：先看是不是等待问题，再看是不是数据问题，最后看是不是环境问题。

等待问题最常见。很多同学喜欢用page.waitForTimeout(3000)这种硬等待，网络快的时候浪费 3 秒，网络慢的时候 3 秒不够还是挂。正确做法是用 Playwright 的自动等待断言，比如await expect(locator).toBeVisible()，它会轮询直到元素出现或超时。如果确实需要等某个接口返回，用page.waitForResponse而不是硬等。

数据问题也很常见。比如两条用例并行跑，都去操作同一个订单，互相干扰。解决办法就是前面说的“用例自给自足”，每条用例用独立数据。

环境问题包括：CI 机器性能差导致渲染慢、测试环境数据库被其他团队重置、第三方服务不稳定。这类问题只能通过“重试 + 监控”来缓解，重试设 1 到 2 次，同时记录哪些用例经常重试，定期优化。

5.2 常见问题速查表