企业官网建设流程全解析

1. 端到端到底在解决什么问题：从一次线上事故说起

做后端出身的人，最初对 e2e 这个缩写多半是又爱又恨。爱是因为它听起来很“全”，恨是因为它跑得慢、容易挂、维护成本高。但我真正改变对端到端测试的态度，是源于一次让我印象深刻的线上事故。

当时我们交付了一个订单模块的小版本改动，单元测试全绿，接口联调也通过，结果上线半小时后，用户反馈“支付成功后页面一直停在回跳中的状态”。查到最后发现，问题出在前端路由守卫拦截了回调参数，而这一层逻辑单元测试压根覆盖不到，接口测试也不会去走真实浏览器流程。从那以后我明白了一个很朴素的道理：测试层级再高，如果缺少一条从用户视角把真实链路走到底的防线，交付质量就是赌运气。

1.1 那一次线上事故，让我重新审视 e2e

那次事故的直接原因是前端对回调 URL 的校验写得太死，被判为非法的跳转来源直接拦截。代码层面看，每个函数单测都正常，但问题恰恰出在“跨模块组合之后”的交互行为上。单元测试验证的是“函数给我正确输入就返回正确输出”，可用户操作是另一个维度——他要经过登录、填单、支付回调、页面路由跳转这一整条链。这一层组合逻辑，在旧体系里没有任何一条测试链路做过真实覆盖。

事后我们复盘，如果当时有这么一条 e2e 用例——真实登录、真实提交订单、模拟支付回调、断言最终页面状态——这个 bug 在 CI 阶段就能被卡住，根本不会流到线上。所以，e2e 的本质不是“多写几个测试”，而是给“跨模块交互”和“用户关键路径”买一份保险。它能回答的问题只有一个：真实用户能不能顺利走通这条业务链路。

1.2 e2e 和单元测试、集成测试的分工边界

很多团队觉得“有了单元测试和接口测试，还要 e2e 干什么”。我的看法是，这三个东西根本不在同一个维度。

单个函数内部逻辑对不对，是单元测试的事；模块之间接口契约对不对，是集成测试的事；而“用户打开页面能不能完成整个旅程”，这才是 e2e 该管的事。接口测试再充分，它也不知道前端传参时会不会莫名其妙丢掉某个字段，也不知道第三方登录回调在真实浏览器环境里会不会被路由拦截。反过来，e2e 也不适合用来验证函数返回值这种细颗粒度逻辑——让浏览器为了验证一个纯函数跑一次全链路，成本明显不划算。

所以我的落地原则是：低频但关键，少而精。单元测试管逻辑密度，接口测试管契约稳定，e2e 只管“核心用户旅程是否通畅”。这样各自边界清楚，维护成本也不会爆炸。需要特别说明的是，这个分层思路是我在实际项目中逐步验证出来的，并不是教科书上的标准答案，但它确实帮我避开了“要么不写、要么写一堆跑不稳”的极端。

2. 工具选型：为什么我从 Cypress 迁到了 Playwright

工具选型是 e2e 落地中的第一个岔路口。我最早用的是 Selenium WebDriver，后来在另一个项目里换成了 Cypress，再后来主力变成了 Playwright。说实话，这三个框架都能做端到端测试，但它们解决同一个问题时的手感差别很大。

先说为什么当年选 Cypress。它的学习曲线极低，写用例就像写普通 JavaScript，语法简单，自带时间旅行调试，看执行过程非常直观。如果你是第一次接触 e2e，或者团队前端基础偏弱，Cypress 是一个很友好的起点。但它有个让我越来越难受的硬伤：它跑在自己的进程环境里，很难实现多标签页、多浏览器的复杂场景模拟。而我们的业务里偏偏有大量“从管理后台打开新标签页查看订单详情”的流程，Cypress 对这类场景支持起来很蹩脚。

2.1 三个主流框架的核心差异

我用过一段时间之后做了个对比表，基本代表了我个人的体感：

这个表里最关键的其实是“网络请求拦截”和“并发执行”。我们的场景经常需要模拟支付回调、mock 第三方接口返回，Playwright 的page.route()可以非常干净地做到这些，而且拦截逻辑可以直接写在用例里，随时按需开启或关闭。在快节奏的 CI 里，并行的收益也很明显，同一台机器能同时跑多个 worker，整个套件耗时直接降一个量级。

2.2 Playwright 在稳定性上的几个设计

真正让我决定迁移的原因是稳定性。e2e 测试最怕的就是“昨天还绿，今天莫名其妙红，重跑又绿”。Playwright 的自动等待机制在这方面做得很好——它的操作会自动等待元素可交互、网络请求稳定，而不是像早期 Selenium 那样靠Thread.sleep硬睡，也不是像一些框架那样只管元素存在就往下点。

举个例子，点击一个按钮后页面会异步加载数据再渲染列表。在 Cypress 里我通常要主动写waitFor一个接口别名；在 Playwright 里，点击后的下一步操作如果依赖那个列表，它会自动等到对应的 DOM 状态稳定。这种“面向状态而非面向时间”的设计，大大降低了因网络抖动产生的偶发失败。对我来说，这比任何花哨功能都实在。

2.3 当前项目的技术栈与配置基线

我现在的主力技术栈是 TypeScript + Playwright Test。配置基线大概是这样：

// playwright.config.ts import { defineConfig } from '@playwright/test'; export default defineConfig({ testDir: './tests/e2e', timeout: 60_000, retries: process.env.CI ? 2 : 0, workers: process.env.CI ? 4 : undefined, use: { baseURL: process.env.E2E_BASE_URL || 'http://localhost:3000', screenshot: 'only-on-failure', video: 'retain-on-failure', trace: 'retain-on-failure', viewport: { width: 1440, height: 900 }, }, projects: [ { name: 'chromium', use: { browserName: 'chromium' } }, { name: 'firefox', use: { browserName: 'firefox' } }, ], });

这里有两个容易被忽略的细节。第一是trace: 'retain-on-failure'，失败了自动留一份完整的执行痕迹，包括 DOM 快照、网络请求、控制台日志，排查问题的时候等于回放一遍事故现场；第二是retries只在 CI 里开，本地失败重试反而会掩盖真实问题，我个人更习惯本地一次跑过。这套配置我沿用了很久，基本没有再因为“环境问题”浪费过一整个下午。

3. 测试骨架怎么搭：用例分层与可维护性设计

工具选完之后，真正考验功底的是用例怎么组织。很多团队 e2e 跑不起来，不是因为框架不好，而是用例设计成一团乱麻：每个用例都从登录页开始点半天，绕一大圈才进入核心操作，然后断言还写得模棱两可。这样的套件跑一次要半小时，失败了你都分不清是业务坏了还是用例自己写崩了。

我早期也走过这条路，写了四十多个用例，每个用例平均耗时四五分钟，维护成本高到想删库。后来借鉴了“测试金字塔”的思路，把 e2e 用例重新分了三层，整个局面才慢慢回到可控范围。

3.1 用例分层：冒烟、核心链路、深度回归

我把 e2e 用例分成三层：冒烟层、核心链路层、深度回归层。

冒烟层是跑得最快的 8 到 10 条用例，覆盖的是用户最高频的路径：登录、首页加载、搜索、创建订单、发起支付、查看订单列表。这一层的作用是在代码合入主干前给出最快的 signal——“这次改动有没有把最基本的用户旅程弄断”。

核心链路层比冒烟层更深入一些，会覆盖业务上最重要的完整流程，比如从下单到支付回调再到财务入账的全过程，中间可能涉及多个系统交互。这一层通常跑在 PR 验证或每日定时任务里，时间要求没那么苛刻，但覆盖面要到位。

深度回归层则是那些正常用户不太会操作、但出了问题影响很大的边缘路径，比如极致权限场景、超长文本输入、异常流程等。它们跑得最慢也最贵，一般只在夜间定时任务里执行，保证不会因为某次重构把角落逻辑弄坏。

这三层对应不同的执行频率和触发时机，而不是一股脑塞进同一个 CI 流程。分层之后，最直接的好处是反馈变快了：PR 阶段只用跑冒烟层，十几分钟内就有结果，不需要等全套 e2e 跑完一个小时。

3.2 Page Object 与组件封装：少写一点脆弱的代码

e2e 用例最怕选择器改动。产品改个class名、加一层div，一串用例全红。为了减少这种脆性，我在项目里全面推行了 Page Object 模式。每个页面一个文件，把页面上所有关键操作封装成方法，用例里只跟这些方法打交道。

// pages/order-list.page.ts import { Page, Locator } from '@playwright/test'; export class OrderListPage { readonly page: Page; readonly searchInput: Locator; readonly firstRow: Locator; constructor(page: Page) { this.page = page; this.searchInput = page.getByPlaceholder('搜索订单号'); this.firstRow = page.locator('table tbody tr').first(); } async goto() { await this.page.goto('/orders'); } async search(keyword: string) { await this.searchInput.fill(keyword); await this.searchInput.press('Enter'); } async getFirstOrderStatus() { return this.firstRow.locator('[data-testid="status"]').textContent(); } }

这里有两个小建议。第一，优先使用getByRole、getByPlaceholder这类基于可访问语义的定位方式，绑定真实用户视角而不是描述性标签；第二，如果有条件，让前端在关键交互节点加上>// fixtures/order.js export async function createPaidOrder(request, { userId, amount }) { const res = await request.post('/api/test/orders', { data: { userId, amount, status: 'PAID', }, }); return res.json(); }

当然这需要后端在测试环境开放专用的测试接口。如果后端不愿意，至少要做到“数据库种子 + 指定测试账号”的隔离方案。测试数据造得好，一条用例的准备时间能从两三分钟压缩到十几秒，整体的执行密度就完全不一样了。

4. 环境隔离和数据处理：e2e 跑得稳的前提

e2e 用例本身写得再漂亮，环境不稳定照样一团乱。我在不同项目里见过这样的场景：测试环境和别人共用一套数据库，你跑用例的时候别人把数据改了就挂了；或者本地、CI、预发布都用同一个 baseURL，结果配置和生产几乎一样，谁都测不准到底测的是哪套环境。

我现在的做法是给 e2e 明确划定三条环境，三条之间互不干扰，所有用例都必须能在这三条上的某一条独立跑通。

4.1 区分本地、CI、预发布三套环境

从环境这个角度说，我的原则是让程序自己判断跑在哪，而不是靠人手动改配置。我会在全局维护一份环境清单，由E2E_ENV这个变量来切换。

这套逻辑并不复杂，但很多项目败在细节：比如切环境只改了一个 baseURL，结果登录态、回调地址、权限系统都没跟上，用例跑到一半就报错。所以我在配置里会同时把环境标识透传给断言逻辑，比如某些页面上展示的版本号、数据来源标签，用来确认当前确实是目标环境，而不是一上来就开始点。

4.2 用 API 造数取代 UI 走流程

造数这件事我前面提过一次，这里展开讲。为什么尽量用 API 而不是 UI 走流程？核心是稳定性。UI 走流程的任何一步都可能因为第三方依赖不稳定而失败，而造数只是准备阶段，不是被测对象的一部分。那些失败只会白白消耗用例时长，增加噪音。

具体实现上，Playwright 自带的requestfixture 很好用。它在同一个浏览器上下文里共享 cookie，等于用浏览器身份直接调后端接口。这样一来，测试里登录一次拿到会话，后面的造数请求都能带上有权限的会话，不需要额外处理鉴权。

test('已支付订单可以发起退款', async ({ request }) => { const order = await createPaidOrder(request, { userId: 'test-user-001', amount: 99.9, }); const response = await request.post(`/api/orders/${order.id}/refund`); expect(response.ok()).toBeTruthy(); });

如果你所在的项目后端没有开通测试专用接口，退而求其次的选择是数据库直接插种子数据，但一定要保证测试库和生产库完全隔离，并且要有能力在用例结束后把数据清理干净，否则隔几天就跑出一堆脏数据，测试结果就完全不可信了。

4.3 账号和数据的关键隔离原则

最后环境层面我始终坚持一条底线：不能用一个正常的线上或准生产账号，去 e2e 环境里乱造数据。哪怕只是创建订单这种“普通操作”，在一套跟生产共用的数据库里也是捣乱。

现在我的项目里每个环境都有独立的测试账号池，按角色分好，比如普通买家账号、卖家账号、管理员账号，全部由脚本创建并初始化。测试用例执行前可以调一个“重置账号”的接口，把用户状态归零，确保跑出来的结果不依赖上一次执行。账号隔离这件事看起来很小，但我吃过的亏证明它足以让一整套 e2e 变成笑话——因为不同测试共用账号导致登录态互相挤掉，用例全军覆没的次数，比我记忆里任何代码 bug 都多。

5. 把 e2e 接进 CI：执行策略比脚本本身更关键

很多团队把 e2e 写好了，结果一接入 CI 就发现一连串问题：跑得太慢拖累发布、偶发失败没人管、日志太多看不出失败原因。这种境况下，真正要动脑筋的地方不是“怎么写用例”，而是“怎么调度这些用例”。

我自己在两个项目里分别试过“每个 PR 都跑全套”和“每个 PR 只跑冒烟层”的做法，最后不约而同选了后者。原因很现实：全套 e2e 如果跑四十分钟，几个 PR 同时排队，整个流水线会堵成一锅粥。而且全量跑的失败定位也麻烦——到底是这个 PR 引入的问题，还是测试环境本身的波动？你很难快速分辨。

5.1 执行频率怎么定：冒烟进 PR，回归走定时

我现在的执行分层策略是：每个 PR 和合入主干前，跑冒烟层加受影响模块的定向用例；每天凌晨跑一次全量回归；发版前再跑一次 staging 环境的完整套件。这样三层各司其职，既能快速反馈，又能保证覆盖深度。

冒烟层的时间控制也挺重要。在我做过的项目中，一套 10 条以内的冒烟用例，在 4 个 worker 并行下控制在 5 分钟内属于合理水平。如果超过 10 分钟，说明用例本身太重了，建议检查有没有不必要的等待和冗余操作，而不是盲目加机器。日常全量回归跑半小时左右是可以接受的，配合并行能力压一压大多数项目都能做到。

5.2 分片、重试与失败报告：别让一台机器拖垮全套

Playwright Test 天然支持多 worker，我在配置里直接让 CI 并行跑。分片其实不需要自己写，重要的是执行时间预估和失败后的处理策略。我现在坚持三个原则：

1. 偶发失败自动重试，但只重试一次，重试次数多了会掩盖真实问题。
2. 失败后必须留下可读性强的现场信息，包括截图、视频、trace 文件、控制台日志。
3. 失败任务的优先级要高于新用例开发——跑挂的 e2e 不修好，后面写再多也都是债。

失败报告这块，Playwright 官方提供的 HTML Reporter 可以直接把失败用例、截图、日志汇总成一个页面，我在 CI 里会把 artifact 保留一周，方便出问题的时候回去翻。

5.3 一个能在 GitHub Actions 里直接参考的配置

如果用的是 GitHub，下面这个配置是我实际用过的简化版，可以直接抄：

name: e2e-smoke on: pull_request: branches: [main] jobs: e2e: runs-on: ubuntu-latest services: postgres: image: postgres:16 env: POSTGRES_PASSWORD: e2e ports: - 5432:5432 options: >- --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5 steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 cache: npm - run: npm ci - run: npx playwright install --with-deps chromium - run: npm run build - run: npm run db:migrate - run: npm run db:seed - run: npx playwright test --grep @smoke env: E2E_ENV: ci E2E_BASE_URL: http://localhost:3000 - uses: actions/upload-artifact@v4 if: failure() with: name: playwright-report path: playwright-report/

这里面有三个细节值得注意：一是用--grep @smoke只跑打了标签的冒烟用例；二是用 GitHub Actions 的 service 容器起一个独立的 PostgreSQL，每次跑之前都做一次干净的迁移和种子，避免残留数据互相影响；三是失败时无条件上传报告目录。这套流程跑了一段时间，基本没有再出现“本地过、CI 挂”的玄学问题。

6. 稳定性优化问题排查实录：那些真实的失败与解决

接进 CI 之后，e2e 最大的敌人就是稳定性。很多团队最终放弃 e2e，不是因为它没用，而是因为它天天挂。这里我把实际排查过程中最有代表性的三类问题拿出来说，每一类都能在网上搜到一堆讨论，但我的经验是：只有理解了底层机制，才能真正举一反三。

6.1 最经典的等待问题：从 sleep 到 waitFor 的进化

最初写 e2e 的人大多经历过sleep(3000)这种用法——反正等三秒总能等到吧。后来发现三秒不够，那就五秒。这类代码的问题是：执行快的机器浪费时间，执行慢的机器照样挂。Playwright 的自动等待解决了一部分，但并不是所有场景都能自动识别。

比如单测里要等一个倒计时结束，或者要等一个第三方脚本的特定回调触发，自动等待机制是感知不到业务语义的。这种情况我的做法是用expect轮询，而不是固定等待：

await expect(page.locator('[data-testid="countdown"]')).toHaveText('0', { timeout: 15_000, });

toHaveText会不断轮询直到超时，元素一满足条件立刻往下走，比 sleep 快得多也稳得多。如果遇到的是自定义轮询，直接写page.waitForFunction也不难。关键是把握一个原则：永远等待业务状态的完成，而不是等待某个固定时长。

6.2 定时器、动画和交互动效带来的干扰

布局动画是 e2e 里一个很有意思的干扰源。按钮有 CSS 过渡动画，元素虽然已经可以接收点击，但点下去的一瞬间视觉位置在移动，就可能导致点击到错误坐标。这类问题的解法我看过很多，有人直接关闭动画：在启动参数里加--disable-animations，或者注入样式把transition: none、animation: none全盖掉。这确实有效，但副作用是你测的已经不是用户在真实环境里的感知了。

我通常的做法是保留动画，但在关键操作前先断言“动画结束标志”。比如一个抽屉面板，等它的opacity稳定到 1，或者某个 aria-expanded 属性变成期望值，再继续下一步。这个“标志”如果前端能提供，是比任何 hack 都可靠的方案。再一个干扰源是轮询定时器，页面每隔几秒刷新数据，导致表格行数一直在变，用例断言还没跑完页面又换了一轮。这种我会建议前端在测试环境把轮询调长或暂停，或者用路由拦截把刷新接口 mock 掉，让状态可控。

6.3 日志、调试与日常维护的“细节管理”

稳定性不只是靠代码技巧，还包括日常的维护习惯。我现在每个 e2e 用例里都会刻意加上场景标记和清晰的断言描述，失败时候第一步看的就是消息和 trace，而不是盲猜。

我还习惯在 CI 里接一个简单的失败分析脚本：按失败用例统计最近一周的发生次数，如果某条用例一周挂超过两三次，即使每次重跑都过了，也要专门开会看一下——频繁偶发失败通常意味着测试环境或产品行为存在不确定因素，放着不管迟早出事。这些“小事”看起来不酷，但正是它们决定了 e2e 能不能长期跑下去。

最后说一点个人体会。e2e 不是银弹，它成本高、写起来慢、运行起来也比别的测试层级更“娇气”。但当我经历过一次线上问题被 e2e 提前拦截之后，我对这套东西的态度从“要不要写”变成了“怎么设计才不痛苦”。它不应被当成替罪羊，也不该被神化成 QA 的全部。作为工程体系里的最后一道闸门，关键就一个字——稳。跑得稳，才有人敢依赖它；有人依赖它，它才真正值回票价。