企业官网建设流程全解析

1. 为什么大家都在聊e2e

1.1 从一次事故说起

大概半年前，我们上线了一个优惠券功能，单元测试全绿、接口测试也过了，结果用户真实操作到第三步——选完商品准备核销时，页面直接白屏。原因说起来特别蠢：前端调了一个后端根本没暴露出来的字段，后端联调的时候压根没发现。事后复盘，最大的问题不是代码写得不好，而是我们缺了一层“像真实用户一样走完整条链路”的验证，这就是e2e测试——端到端测试——存在的意义。

e2e测试，简单说就是模拟真实用户在完整系统上执行典型操作流程，验证整个链路是否按预期工作。它覆盖的范围不是某一个函数、某一个接口，而是从前端页面点击、到后端接口调用、再到数据库状态变更，最后回到页面上呈现结果的整条链路。这正好补上了单元测试和集成测试覆盖不到的盲区，也是为什么现在越来越多的团队把e2e作为上线前的最后一道关卡。

这篇文章适合正在做web开发、想引入e2e测试但不知道怎么落地的朋友，也适合已经写过一些自动化用例、但经常被用例稳定性折磨的团队。我会从最核心的设计思路讲起，再给出一套可以直接照搬的实操方案，最后把我踩过的坑都列出来，帮你少走弯路。

1.2 一个容易被误解的概念

很多人一听e2e测试，第一反应是“哦，就是拿Selenium点点点嘛”。这句话对了一半，但也因为只对了一半，导致很多团队把e2e做成了“每天跑一次、挂了就截图、修了也白修”的鸡肋。

真正的e2e测试有三个关键词：用户视角、完整链路、真实环境。用户视角意味着测试用例是从一个真实用户出发的，用户怎么操作，用例就怎么操作，而不是为了测某个接口故意走一条不自然的路径；完整链路意味着从浏览器发起请求，一直到数据库写入或者第三方支付回调，整条链路都要走通；真实环境则强调测试环境、测试数据、依赖服务都要尽量贴近生产。

我见过一个很典型的错误做法：为了图省事，在e2e用例里直接调用内部接口把数据装配好，然后跳过前端页面去断言接口返回值。这虽然跑得快，但本质上又变成了集成测试，前端的问题、交互的问题、用户路径上的问题依然发现不了。所以这整篇文章我所有的方案，都会围绕上面三个关键词来展开。

2. e2e测试的核心设计与选型思路

2.1 在分层测试里，e2e到底站在哪

要理解e2e测试的价值，先看一张常见的测试金字塔：

• 底层是大量的单元测试，跑得快、定位准，验证单个函数或模块的行为；
• 中间是集成测试，验证模块之间、服务之间的交互；
• 顶层是e2e测试，数量最少、跑得最慢、成本最高，但最贴近用户真实行为。

金字塔模型告诉我们，e2e测试不应该试图覆盖所有业务分支，那是单元测试和集成测试该干的事。e2e只需要覆盖核心用户旅程，也就是一旦出错就会造成重大损失的路径。我一般建议控制在20条以内的核心用例，比如注册登录、加购下单、支付回调、订单状态流转这类主干流程。

这样分配的原因很现实：一条e2e用例在真实环境上跑一遍，可能需要几十秒甚至几分钟，如果把它当成单元测试来用，写了上百条，那么等用例跑完，程序员的热水都已经凉了。而过长的执行时间会让团队下意识逃避运行，最终这套测试名存实亡。所以我做e2e设计的第一原则，不是“尽量多写”，而是“只写值得写的那20条”。

2.2 工具选型对比：Playwright、Cypress、Selenium

选对工具，e2e就成功了一半。这里我不报菜名，只说我实际用下来最核心的三个选项。

我最终为团队选的是Playwright，原因有三点。第一，真正的多浏览器支持，项目里有需要验证Safari兼容性的场景，Playwright能直接用WebKit跑，不用额外装真机；第二，自动等待机制写起来更省心，不用到处写sleep和waitForVisible；第三，trace viewer对排查复杂问题帮助极大，录下来的上下文信息比截图丰富太多。

选型时还有一个容易忽略的点：团队现有的技术栈。如果团队对Node.js很熟，Playwright和Cypress都合适；如果团队原来是Java技术栈，Selenium生态可能更顺。反正工具没有绝对最好，只有和团队匹配度最高。下面所有实操演示我就基于Playwright展开，思路同样适用于其他工具。

2.3 再说说Profile，也就是环境配置

关键词里出现了“e2e profile1”，这个“profile”其实是e2e实践里很容易被跳过、但非常关键的部分。Profile指的是针对不同运行环境准备的配置集合，比如profile1可以是测试环境配置，profile2可以是预发布环境配置。

你可能觉得，环境不一样无非就是改个baseURL，这有什么好设计的？实际跑起来你会发现事情没这么简单。测试环境会初始化数据，预发布环境禁止写脏数据，本地环境可能需要mock第三方的验证码服务，而CI环境又要走独立的登录态获取方式。这些差异如果不用profile管理，写死在用例里，那这套e2e基本只能在一个环境上跑，换个环境就全线崩。

所以我在项目里会单独建一个profiles目录，每个profile是一个配置文件，里面定义baseURL、超级管理员账号、数据库清理开关、第三方mock开关、超时时间等。跑测试的时候通过环境变量指定profile，比如E2E_PROFILE=profile1 npx playwright test。这样本地、测试环境、CI共用一套用例，只是加载不同的配置。

3. 手把手搭建一套e2e测试

3.1 环境准备与依赖安装

实操部分我们以Playwright + TypeScript为例，一步一步把项目跑起来。首先准备好Node.js环境，建议使用18以上的稳定版本。然后新建一个目录，初始化项目：

mkdir e2e-demo && cd e2e-demo npm init -y npm install -D @playwright/test @types/node npx playwright install

第一条命令创建目录，第三条命令安装Playwright测试框架本身，第四条命令下载浏览器内核。这里特别注意，npx playwright install下载浏览器的时候，默认会把Chromium、Firefox、WebKit全部下载，大概占几个G的磁盘空间。如果不需要测多浏览器，只需要Chromium的话，可以只跑：

npx playwright install chromium

在团队协作场景里，我建议把是否需要安装哪些浏览器写进README，避免新同事一上来就把磁盘占满。当然，每个人可以按自己的网络环境决定安装方式，这里只说明常规做法。

装完之后手动建一个playwright.config.ts配置文件。这个文件是全项目的总控中心，我的建议是从一开始就认真配置，避免后续反复改：

import { defineConfig, devices } from '@playwright/test'; export default defineConfig({ testDir: './tests', timeout: 60000, retries: 2, workers: 4, use: { baseURL: process.env.E2E_BASE_URL || 'http://localhost:3000', trace: 'retain-on-failure', screenshot: 'only-on-failure', video: 'retain-on-failure', viewport: { width: 1280, height: 720 }, }, projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'] } }, ], });

这里每个字段都有讲究。timeout是每个用例的超时时间，我设置60秒，给慢环境留足余量；retries表示用例失败后自动重试的次数，这个是提升稳定性的关键；workers是并行执行的worker数，设成4意味着4个浏览器实例同时跑，时间直接缩短到四分之一。trace、screenshot、video这三个都是失败时的现场留证，排障时就知道它们有多救命了。

注意：retries不是让你忽略问题，而是帮你区分“偶发失败”和“真实缺陷”。如果一条用例重试两次每次都在同一个地方挂，那必然是真实问题，不要用重试来掩盖。

3.2 第一个e2e用例：登录流程

我习惯用登录流程作为团队的第一个e2e用例。原因很简单，登录是所有业务的地基，而且它涉及前端表单、接口校验、鉴权返回、本地存储写入等多个环节，非常适合用来展示e2e测试的覆盖面。

在tests目录下新建login.spec.ts：

import { test, expect } from '@playwright/test'; test('正常用户登录后跳转到首页', async ({ page }) => { // 1. 打开登录页 await page.goto('/login'); // 2. 输入账号密码 await page.getByLabel('用户名').fill('test_user'); await page.getByLabel('密码').fill('test_pass'); // 3. 点击登录按钮 await page.getByRole('button', { name: '登录' }).click(); // 4. 断言跳转到了首页 await expect(page).toHaveURL('/home'); // 5. 断言首页上有用户昵称 await expect(page.getByText('欢迎回来，测试用户')).toBeVisible(); });

这段代码有几点值得细说。第一，我用的是getByLabel、getByRole、getByText这类基于用户可见文本的定位方式，而不是page.locator('#login-form > input')这种CSS路径。为什么？因为用户是用文本和角色识别界面的，基于用户感知定位的选择器，比依赖DOM结构的定位方式要稳定得多，前端把class名改一下、ul包个div，CSS路径就挂了，而角色定位基本不受影响。

第二，从第1步到第5步，每一步都是在模拟真实用户行为，没有跳过登录接口直接注入登录态。这个用例跑通了，说明前端登录表单、后端鉴权接口、路由守卫、首页信息展示这整条链路都没问题。

写完直接在命令行跑：

npx playwright test tests/login.spec.ts --headed

--headed表示打开图形化浏览器，方便你亲眼看到用例执行过程。第一次跑的时候，你大概率能看到浏览器自动打开、自动填表、自动点击、最后自动断言，整个过程会有一种“这玩意儿比我想象中聪明”的感觉。

3.3 测试数据与Profile配置

如果说前面是给e2e测试打了个地基，那么测试数据管理就是给这栋楼通了水电。我用过最省心的方案是**“前置数据用接口造，业务数据每个用例独立”**。我来解释一下，也请你理解这种取舍。

拿下单流程举例，前置数据包括：一个已注册并激活的用户、一个库存充足的商品、可用的优惠券。这些数据如果都通过页面上一步步点出来，一条用例要花三分钟，而且每一步都可能在项目里埋新雷，不稳定。更合理的做法是，在用例执行前用后端API把这些数据直接创建好。

在Playwright里，我们可以通过request上下文直接调后端接口：

test('用户可以使用优惠券下单', async ({ request, page }) => { // 用接口创建测试用户 const user = await request.post('/api/test/users', { data: { name: 'buyer01', role: 'normal' } }); // 用接口创建商品和优惠券 await request.post('/api/test/products', { data: { id: 'sku-1001', name: '测试商品A', stock: 100 } }); await request.post('/api/test/coupons', { data: { userId: 'buyer01', amount: 10, condition: 100 } }); // 页面上执行真实的下单操作 await page.goto('/products/sku-1001'); await page.getByRole('button', { name: '加入购物车' }).click(); // ... 省略中间结算步骤 await expect(page.getByText('订单提交成功')).toBeVisible(); });

这种做法的好处是，用例聚焦在自己真正想验证的那一段链路，前置准备不依赖UI，因此不会因为前置步骤的变更导致用例大面积崩溃。同时每个测试用例都创建自己的数据，也避免了多个用例共用数据时互相污染的问题。

数据造好之后，就到了profile的用武之地。我在配置里定义了一个E2E_PROFILE环境变量，然后通过下面的方式读取对应配置：

// profiles/profile1.ts export const profile1 = { name: '测试环境', baseURL: 'http://staging.example.com', adminUser: { username: 'admin', password: 'admin123' }, cleanupData: true, mockSms: true, }; // profiles/profile2.ts export const profile2 = { name: '预发布环境', baseURL: 'http://pre.example.com', adminUser: { username: 'admin', password: 'admin456' }, cleanupData: false, mockSms: false, };

然后在playwright.config.ts里，根据process.env.E2E_PROFILE加载对应的配置对象，把baseURL等值注入到use里。这样团队在本地跑测试环境用E2E_PROFILE=profile1，在发版前跑预发布用E2E_PROFILE=profile2，用例代码完全不用动。

你可能好奇为什么预发布会禁用数据清理和mock。因为预发布环境往往是生产数据的脱敏镜像，任何人都不能随便写脏数据，也不应该拦截真实的短信服务。环境不同、约束不同，所以配置必然不同，这就是profile设计的核心动机。

3.4 跑起来：运行、报告与CI集成

本地跑通用例只是第一步，真正的价值在于把e2e测试集成进CI/CD流程，让每次代码合并都自动跑一遍核心链路。我这边用的方案是GitHub Actions，思路在任何CI平台都是通用的。

先写工作流文件.github/workflows/e2e.yml：

name: E2E Tests on: pull_request: branches: [main] jobs: e2e: runs-on: ubuntu-latest services: postgres: image: postgres:14 env: POSTGRES_PASSWORD: postgres ports: - 5432:5432 steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 18 - name: Install dependencies run: npm ci - name: Install Playwright browsers run: npx playwright install --with-deps chromium - name: Start test server run: npm run start:test & - name: Run E2E tests env: E2E_PROFILE: profile1 run: npx playwright test - name: Upload Playwright Report if: always() uses: actions/upload-artifact@v4 with: name: playwright-report path: playwright-report/

这里的几个步骤都有明确目的。npm ci是比npm install更严格的依赖安装方式，能在CI上保证依赖版本完全锁定；npx playwright install --with-deps chromium会在安装浏览器的同时，把浏览器在Linux上运行时需要的系统库一并装上，这一步漏了的话，后面启动浏览器大概率会报缺依赖；起测试服务用后台运行；最后上传报告做成了if: always()，确保即使测试失败，报告也能被保留下来供查阅。

跑完的HTML报告长什么样？它会在一个页面里列出所有通过的用例、失败的用例，以及每个用例的执行耗时。点开失败用例，能看到失败时刻的截图、录屏、控制台日志，还有每一步操作前的页面快照。有了这些东西，绝大多数问题五分钟之内就能定位到具体是哪个环节出了问题。

这里还要提一个成本问题：e2e测试在CI上跑，时间就是金钱。我的建议是先在本地把用例调稳，确认不是确定性失败之后再推到CI。如果一个坏用例每天在CI上耗时一分钟还必挂，那这个坏用例就是团队的负资产。所以CI管道里我会再设一个冒烟集，只跑5条最核心的用例，全量集单独安排到夜间定时跑。冒烟集保证合并代码不被主干故障堵住，全量集负责每天早晨给团队一份健康报告。

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

4.1 用例不稳定，谁才是元凶

做e2e测试，最容易劝退人的就是“昨天能跑，今天挂了，再跑一次又好了”这种玄学问题。别急，不稳定用例十有八九来自这几个原因。

第一个是网络与异步加载。页面上的某个按钮刚出现在DOM里，但实际上还没挂上事件监听，测试就点击了，结果就是事件没触发。Playwright的自动等待能缓解一部分，但如果你用了page.locator().count()或者page.$()这类同步方法，自动等待就失效了。我的经验是，所有操作的定位器前面都别用同步断言，一律用expect配合toBeVisible这类异步断言。

第二个是数据污染。用例A创建了一个订单，用例B跑了同样的流程，发现页面上多了一个之前没见过的订单弹窗，于是断言失败。这种问题在测试环境尤其常见。解决方案就是我前面说的“每个用例独立创建自己的数据”，同时用例结束后做好数据清理，或者在test.beforeEach里调用清理逻辑。

第三个是时间窗口。后端异步任务还没执行完，前端已经渲染出了界面，测试断言的是“渲染出来的界面”，但后续任务会再更新一次界面，导致断言时看到中间态。遇到这种场景，要么在断言前轮询等待最终态，要么让后端为测试环境把异步流程改为同步可配置。

我遇到过最魔幻的一次是，用例在CI上稳定失败，但本地怎么跑都成功。后来发现，本地访问的是我自己的开发机，走的是内网，CI访问的是公网上的测试机，跨公网延迟大，前端超时时间又设得太短。最后在前端框架层面的全局超时配置里，给测试环境单独放宽了阈值。所以排查不稳定问题，先检查是否能稳定复现，再检查环境差异，别上来就改用例逻辑。

4.2 选择器的三个原则

e2e测试界流传一句话：“写用例一门手艺，写选择器是这门手艺的三成功力”。选择器写得好不好，直接决定用例能活多久。我总结了一套自己的选择器优先级原则。

第一优先，用户可见的文本信息。登录按钮就叫“登录”，不要用#login-btn。订单编号的地方就找包含订单号的文本节点，不要用复杂的XPath条件。

第二优先，语义化的ARIA角色与名称。getByRole('button', { name: '提交订单' })、getByRole('link', { name: '我的订单' })这类写法，即使前端从div改成button，从span包一层a标签，依然能准确定位。

第三优先，stable的DOM属性。如果项目里没有语义化属性，就用>const frame = page.frameLocator('iframe[data-testid="pay-frame"]'); await frame.getByRole('button', { name: '确认支付' }).click();

如果不切换到正确的frame，直接page.getByRole去找，永远找不到。这是很多新手解决不了的问题，但用iframe的语义去定位，几乎一次就能搞定。

5. 一点个人体会

做了这么多年测试基础和自动化建设，我越来越觉得e2e测试不只是“写几个用例”那么简单。它更像是一种质量引擎，逼着团队去梳理核心业务链路、规范接口契约、统一交互标识，甚至反向推动开发同学改良代码的可测试性。我一个很直观的感受是，自从核心链路上了e2e以后，线上回归压测的底气明显足了很多，也不再需要发版前拉一堆人手工点半天。

不过我也要泼点冷水。e2e测试不是银弹，它替代不了单元测试的精准定位，也替代不了集成测试的快速反馈。如果你所在的项目连单元测试都没有，那先补金字塔的底层比直接盖塔尖更重要。等底层扎实了，再来引入e2e，你会发现问题被自动挡在一层一层更好的位置。

最后分享一个小习惯。我每次写完新用例，都会再花几分钟问自己一个问题：“如果这个用例现在失败了，我能快速定位出是哪一层出了问题吗？”如果答案是不够清晰，我就会在这个用例里增加更细的断言节点，让失败时的语义更明确。这套习惯帮我省了很多“半夜被叫起来看e2e为什么红”的时间，也推荐你试试。