做了这么多年 Web 项目，我慢慢总结出一个规律：单测、接口测试全绿，并不代表上线就稳。真正的翻车点往往不在某个函数逻辑，而在用户从登录到操作再到回显的完整链路里，哪怕只有一个环节对不上，线上就会立刻出问题。端到端测试（E2E）就是为这段完整链路兜底的手段。

这篇文章不讲那些谁都会背的概念，直接讲我实际是怎么把 E2E 落地到项目里的，包括 profile 这个词到底在配什么、为什么同一份用例要拆成多套配置跑、以及那些每次 CI 一挂就让人血压升高的经典问题怎么排查。想用这套东西给现有项目加一层保障的同学，可以参考着抄。

1. 端到端测试解决的，恰好是其他测试视而不见的盲区

1.1 单测、接口测都通过，为什么还会翻车

我先说一个真实场景。之前做一个后台管理系统，用户登录模块的单测覆盖率接近 90%，接口测试也写了权限校验相关的用例，按道理这块应该很稳。结果联调的时候发现，用户在页面上输入账号密码后明明提示登录成功，下一个请求却又被重定向回登录页。

排查下来问题出在会话令牌的写入时机上：登录接口返回的令牌被写入了一个内存变量，但页面路由跳转之后，另一个模块从本地缓存里读取会话信息，两边信息不同步，导致前端认为“已登录”，后端每次请求都验证不过。这种问题，单测基本不会暴露，因为它关注的是单个函数是否能处理输入输出；接口测试也容易漏，因为它是绕过了 UI 直接调接口，根本没走浏览器里的存储交互。

这就是端到端测试存在的意义。它站在真实用户的角度，启动浏览器，输入账号密码，点击登录，然后断言页面上是否真的出现了预期的内容，以及跳转之后再次发请求是否成功。这个完整链路里，前端状态、浏览器存储、后端接口、权限路由全都会被真实地串起来。

1.2 E2E 真正适合用来验证哪些业务场景

不是所有业务都值得写 E2E，这一点要先想清楚。我自己的判断标准是：这个流程一旦出错，用户能不能直观感受到，损失有多大。以下这几类场景我建议优先覆盖。

注册、登录、退出整个会话生命周期。尤其是登录态失效之后跳转登录页、重新登录回到原页面这类细节，用户感知极强。

带核心交易的闭环流程，比如选择商品、加入购物车、填写地址、提交订单、支付成功、订单列表出现新记录。这类流程往往跨页面、跨模块，中间任何一环断掉，用户就流失了。

权限控制相关，比如普通用户没有某个入口、管理员能看到某个按钮并操作成功。权限写在接口层还不够，因为前端客户端经常要配合按钮显隐和路由守卫，这部分只能在浏览器里验证。

跨系统或跨域的跳转和回跳，例如从官网跳转到主站、再跳转到支付平台，完成后回到业务系统。这类流程涉及多个域名，普通接口测试根本模拟不了。

这些业务链路里，前端和后端各自可能都是正常的，但放在一起运行时才会暴露出契约问题。E2E 的价值就在这里：它校验的是系统作为一个整体能不能正常工作。

1.3 不要一上来就把 E2E 当成测试主力

很多团队一听 E2E 能抓链路问题，就恨不得把所有用例都改成 E2E，这是最典型的坑。E2E 跑起来比单测慢好几个数量级，一个完整业务链路的用例可能需要几十秒；它还要依赖真实环境、真实数据，环境一抖动就很容易误报；而且浏览器自动化对选择器、网络时序都特别敏感，维护成本并不低。

合理的组合是金字塔结构：底层大量单测和模块测试，中间层接口测试，最顶上放少量但关键的 E2E 用例。E2E 不是替代谁，而是给那些跨模块、跨系统的关键路径兜底。我自己一般在项目里控制 E2E 用例数量，一条核心链路配两到三个用例就够，剩下的靠接口测试去覆盖分支逻辑。

2. E2E 的 profile 设计：为什么同一份用例要跑多套配置

标题里提到的 profile1，就是我下面要展开的重点。很多刚开始写 E2E 的人会把环境地址、账号密码、超时时间直接写在测试代码里，跑本地时改一遍，跑测试环境再改一遍，上线前又改一遍，最后谁也不敢动这些测试文件。profile 要解决的，正是这个问题。

2.1 profile 里到底放什么东西

你可以把 profile 理解成一组“测试运行参数”的集合。每套环境都有自己的基础地址、账号体系、数据权限范围、服务端口，这些参数如果散落在测试代码里，环境一多就完全失控。我一般把以下信息放到 profile 里：

• 环境标识，比如 dev、staging、prod，用来区分当前跑的是哪套环境。
• 基础 URL，包括前端地址、后端 API 地址、以及第三方跳转地址。
• 测试账号，有时还需要多个不同权限等级的账号。
• 超时时间配置，比如接口慢的环境就把整体超时放宽。
• 行为开关，例如是否需要清缓存、是否需要拦截指定外部请求、是否开启视频录制。

把这些参数收拢到一个配置结构里之后，测试代码本身只依赖抽象配置，不需要关心自己跑在哪套环境上。这也是“同一份用例跑多套配置”的底层逻辑。

2.2 我常用的一套 profile 划分方式

在实际项目里，我不会只分 dev 和 prod 两个 profile，而是按“数据隔离程度”和“权限范围”进一步拆分。

这里的 profile1 在真实项目中可能对应的是预发布环境的验证配置，它跟 test profile 最大的区别是数据不能被随意清理。所以我会把权限和数据准备策略区分开，profile-test 可以建数据、删数据，profile1 则只允许对特定前缀的测试数据做校验。

你不需要死板地复制我的方案，但核心原则要记住：每个 profile 必须能独立解释正在跑的环境特性，测试代码里不出现任何环境相关的魔法值。

2.3 profile1 的落地示意：配置拆分与权限控制

下面用一个配置结构的示例来演示。这里我用 TypeScript 类型定义一个 Profile 结构，再派生出若干个具体 profile 对象。

export interface E2EProfile { name: string; baseURL: string; apiBaseURL: string; users: { admin: { username: string; password: string }; readonlyUser: { username: string; password: string }; }; timeouts: { pageNavigation: number; elementWait: number; }; options: { clearStorageBeforeRun: boolean; recordVideo: boolean; allowExternalRequests: boolean; }; } export const profiles: Record<string, E2EProfile> = { "profile-dev": { name: "dev", baseURL: "http://localhost:5173", apiBaseURL: "http://localhost:8080/api", users: { admin: { username: "dev_admin", password: "dev_pass" }, readonlyUser: { username: "dev_viewer", password: "dev_pass" } }, timeouts: { pageNavigation: 30_000, elementWait: 10_000 }, options: { clearStorageBeforeRun: true, recordVideo: false, allowExternalRequests: true } }, "profile1": { name: "staging", baseURL: "https://staging.example.com", apiBaseURL: "https://staging-api.example.com/api", users: { admin: { username: "staging_admin", password: process.env.STAGING_PASS ?? "" }, readonlyUser: { username: "staging_viewer", password: process.env.STAGING_VIEWER_PASS ?? "" } }, timeouts: { pageNavigation: 60_000, elementWait: 20_000 }, options: { clearStorageBeforeRun: false, recordVideo: true, allowExternalRequests: false } } };

注意 profile1 的密码我没有硬编码，而是从环境变量里读取。这是一个很重要的安全习惯：配置文件如果进了代码仓库，密码就必须避免出现明文，否则等于把测试环境的口令公开在仓库里。尤其是越来越多人喜欢把测试代码放到统一仓库管理，一旦账号密码泄露，配合真实环境数据，麻烦会很大。

加载 profile 的入口一般放在全局配置文件里，通过命令行参数指定跑哪套 profile：

PROFILE=profile1 npx playwright test

在playwright.config.ts里读取环境变量，然后传给每个测试用例使用。

3. 从零搭一套能落地的 E2E 项目

3.1 工具选型：为什么我现在更推荐 Playwright

E2E 工具现在可选的不多，主流的无非是 Selenium、Cypress、Playwright 这几个。Selenium 因为生态老、支持语言多，仍然有不少团队在用，但它的自动化等待机制和调试体验确实比较原始。Cypress 在国内还有不少存量项目，优点是学习曲线平缓，缺点是只能跑在浏览器同源策略允许的范围内，多标签页和多用户场景处理起来比较别扭。

我个人在最近的项目里更倾向于 Playwright，主要是这几点打动了我：

• 内置自动等待，不用写一堆sleep(3000)，它会自动等元素出现、可点击、网络空闲。
• 原生支持多标签、多上下文，甚至能在一个测试里同时模拟两个用户。
• 内置 trace 查看器，失败用例可以直接看到完整的操作时间线和每一个请求响应。
• 同样一套代码可以跑 Chromium、Firefox、WebKit，对浏览器兼容性有要求的项目非常友好。

如果你所在团队已经完全基于 Cypress 写了一套用例，没必要强行迁移，工具不是关键，关键的还是配置管理和用例设计。但如果你是从零开始，或者刚好在选型阶段，我建议直接试 Playwright。

3.2 初始化项目与基础目录结构

下面是从零到能跑的最小步骤。

mkdir e2e-demo cd e2e-demo npm init -y npm i -D @playwright/test npx playwright install chromium

初始化之后我会把目录整理成这样的结构：

e2e-demo/ ├── playwright.config.ts ├── profiles/ │ └── index.ts ├── tests/ │ ├── login.spec.ts │ └── order-flow.spec.ts ├── utils/ │ └── testdata.ts └── package.json

playwright.config.ts负责读取 profile、配置浏览器和 reporter，profiles/index.ts放 profile 定义，tests/下按业务模块组织测试文件，utils/放数据生成和公共操作。这个分层方式不需要很复杂，但能保证新增用例时不会把环境配置和测试逻辑混在一起。

playwright.config.ts的核心配置大致是这样的：

import { defineConfig } from "@playwright/test"; const profileName = process.env.PROFILE ?? "profile-dev"; const profile = profiles[profileName]; export default defineConfig({ testDir: "./tests", timeout: profile.timeouts.pageNavigation, retries: process.env.CI ? 2 : 0, use: { baseURL: profile.baseURL, actionTimeout: profile.timeouts.elementWait, screenshot: "only-on-failure", video: profile.options.recordVideo ? "retain-on-failure" : "off", trace: "retain-on-failure", storageState: undefined }, projects: [ { name: "chromium", use: { browserName: "chromium" } } ] });

这里有个细节值得注意：我把retries只在 CI 环境设置为 2。本地调试时如果直接自动重试，反而会掩盖问题，因为你不知道首次失败的真实原因。CI 上重试是为了应对偶发的环境抖动，两者逻辑不同。

3.3 核心用例的实现过程

我拿“登录后创建一个新项目并验证列表出现”这个场景来做演示。这不算复杂，但它包含了登录、表单填写、网络请求等待、列表断言这几个 E2E 最常用的动作。

import { test, expect } from "@playwright/test"; test("登录后创建新项目并出现在列表", async ({ page }) => { // 先从 profile 里取账号信息 const { admin } = profiles[process.env.PROFILE ?? "profile-dev"].users; await page.goto("/login"); await page.getByLabel("用户名").fill(admin.username); await page.getByLabel("密码").fill(admin.password); await page.getByRole("button", { name: "登录" }).click(); // 等待登录请求返回成功 await page.waitForResponse(resp => resp.url().includes("/api/login") && resp.status() === 200 ); await expect(page.getByText("工作台")).toBeVisible(); const projectName = `e2e-${Date.now()}`; await page.getByRole("button", { name: "新建项目" }).click(); await page.getByLabel("项目名称").fill(projectName); await page.getByRole("button", { name: "确认" }).click(); // 等待创建接口结束，避免列表刷新前就断言 await page.waitForResponse(resp => resp.url().includes("/api/projects") && resp.status() === 200 ); await expect(page.getByText(projectName)).toBeVisible(); await expect(page.getByRole("row", { name: projectName })).toContainText("运行中"); });

这里面的几个等待不是为了等固定时间，而是等真实的业务事件。登录后我等待的是api/login这个响应返回，创建项目后等待的是api/projects这个响应返回。

为什么要等响应而不是等元素？因为创建请求返回 200 之后，前端可能还有一个短暂的列表刷新渲染阶段，如果立刻断言项目名，很可能因为列表还没更新而失败。先等接口，再等 UI，这一条基本能消灭 80% 的偶发失败。

3.4 本地运行与 CI 执行的区别

本地调试时我喜欢只跑自己改动的文件，加上一个 headed 模式，看到浏览器真实走到哪一步：

npx playwright test tests/order-flow.spec.ts --headed

在 CI 里则完全不一样。CI 上没人在旁边看浏览器，如果用例失败，你需要的是能离线分析的产物。所以 CI 的配置里我往往会打开视频录制和 trace，同时按浏览器分片执行来减少总耗时。

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 env: PROFILE: profile1 STAGING_PASS: ${{ secrets.STAGING_PASS }} - uses: actions/upload-artifact@v4 if: ${{ !cancelled() }} with: name: playwright-report path: playwright-report/

这里有几个容易踩的坑。CI 的容器里不一定有浏览器依赖，所以npx playwright install --with-deps chromium这一步不能省。secrets 传密码是用环境变量方式注入，而不是把密码写进仓库。最后无论测试成功还是失败，都要用if: !cancelled()把报告产物上传回来，否则你根本看不到失败现场。

还有一个容易忽略的点：CI 机器性能和本地差异很大，同样的用例本地跑 5 秒，CI 可能要跑 20 秒。所以 profile 里超时时间要区分本地和 CI 两档，不要直接写死成同一个值。

4. E2E 最常见的问题与排查经验

写 E2E 的过程里，我踩过的坑、排查过的问题实在太多了，这里挑最有代表性的几类整理出来，后面真遇到了可以直接对着查。

4.1 测试数据污染，是大多数不稳定用例的根源

我最早遇到的一个问题是：用例在本地永远能跑过，在 CI 上却隔三差五失败。后来发现是因为大家都在同一套测试环境跑，A 同学创建的测试数据还没清理，B 同学执行用例时查询列表按名称排序，结果前 10 条全是别人的数据，断言自然就挂了。

数据污染最常见的表现是：用例单独跑是绿的，放到整个 suite 里就有概率红。解决思路有几种：

• 每个用例使用独立的测试账号，账号之间数据天然隔离。
• 项目名、订单号等唯一字段拼上时间戳，避免和前一次执行撞车。
• 在 setup 阶段调用后端接口清理指定前缀的测试数据。
• 实在清理不了的环境，执行前做一次数据库快照重置。

我给推荐顺序是：优先独立账号，其次动态数据，最后是清理钩子。独立账号改动比较大，但是最彻底；动态数据改动小，适合快速止血。

4.2 元素交互不稳定：等待、提示框、动画

E2E 跑起来之后，第二大痛点就是元素交互不稳定。界面刚加载出来，输入框看起来在，但还不能输入；按钮显示的是“确定”，但点击没反应；下拉框第一次展开一半就收起了。问题几乎都出在“时序”上。

应对方法是在代码里用语义化的等待，不要用固定sleep()。Playwright 自带自动等待，所以大多数情况下你只需要直接调用fill()、click()，它会等元素可操作。但如果页面里有自定义动画，一个元素可能已经能点击，点完之后界面状态却没即时更新。这时候我用的是等接口响应或者等某个业务状态出现。

处理弹窗也是一个常见坑。有些弹窗关不掉是因为遮罩层覆盖了按钮，报错信息是“元素被遮挡”。解决方式不是盲目加force: true，而是先判断是不是动画还没结束，可以等元素的一种状态变为稳定后再点击。force: true能绕过错点击，但它会掩盖真实交互问题，我只有确认为视觉层遮挡且业务操作不需要用户输入时才会使用它。

4.3 调试三板斧：截图、视频、trace

有一次线上 CI 失败，测试报告里只有一个普通错误，连报错信息都看不出问题，我差点就灰心地加上重试然后放过了。后来打开测试产物里的 trace，一步步看操作回放，才发现是测试环境某个第三方登录按钮的文案从“联合登录”改成了“第三方登录”，按钮没找到，用例才失败的。

我把调试手段按优先级排列，失败的时候按顺序去翻：

• 失败截图，这是最直接的第一现场，能看到页面最后停在哪里。
• 视频录制，能回看整个操作的快慢变化。
• Trace 文件，里面包含每一步操作、网络请求、控制台日志，连前端报错都能看。

在playwright.config.ts里打开：

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

三个都打开后，CI 失败的用例会自动生成一个 zip 包。在产物目录里找到trace.zip，用浏览器打开 trace 查看器，你会看到每一帧页面状态、每一个 console 输出、每一个接口请求时间线。排查 E2E 问题时，这套组合基本能让你不靠“猜”就能定位根因。

补充一个实用技巧：Profile1 这种预发布环境关闭了外部请求时，如果用例需要验证跳转到第三方页面，最好在配置里把这个域名加到允许清单。这个细节我第一次没注意到，结果用例在本地能正常跳转，到了 profile1 环境却一直卡在阻断页，排查了很久。

5. 一点实在话

端到端测试做得久了，你会发现真正难的其实不是写脚本，而是把配置、数据、环境、CI 机制理顺。profile1这种看似不起眼的配置拆分，背后就是为了解决“同一段业务逻辑在不同环境表现不一致”的现实问题。

我个人实际操作中的体会是，E2E 的价值不取决于写了多少条用例，而取决于是不是把你最核心的用户路径保护住了。与其十个页面各写几条脆弱的冒烟用例，不如集中精力把一条关键链路的稳定性做到极致。每次 CI 全绿的时候，那种确定性带来的安全感，是单测和接口测试给不了的。