Skip to content

Vitest + Playwright 测试体系:组件测试与 E2E 在 CI 中稳定运行 ​

1. 本节目标与验收方式 ​

四条可以用行为验收的目标:

  • 能给定一个断言,判断它应该落在组件测试还是 E2E,并说出理由。
  • 会写 mount 加 slots 的组件测试,且不依赖组件内部状态。
  • 能配置 trace: 'on-first-retry' 与 failOnFlakyTests,让 flake 无法藏在绿灯里。
  • 能诊断一条偶发失败用例,指认它属于六类根因中的哪一类。

验收方式不是自评,是回到自己的仓库跑一遍:现有 E2E 套件里,能找出几条"其实可以在 jsdom 里断言"的用例,把它们下移。

2. 分层在工程链路里的坐标 ​

越往上越便宜也越不真实,越往下越可信也越慢。这个梯度的意义在于:每次想把断言往下挪一层,都要先回答"它到底依赖了什么只有浏览器才有的东西"。

3. 从一个"全绿但没人信"的套件说起 ​

2026 年 4 月接手一个项目,CI 上 47 条 E2E 全绿。第一周我提交了一个改动,把结算页的优惠券入口条件写反了,合并后上线才发现——套件里没有任何一条用例点过那个入口。

再去翻历史构建:过去 30 天有 41 次构建失败,其中 33 次重跑后通过。团队的口头禅是"重跑一次就好"。

这个状态比"测得少"更麻烦:红灯已经失去信息量,连真正抓到 bug 的那 8 次也没人看。所以搭体系的第一目标不是覆盖率,是让每次红灯都指向一个确定原因。下面按层拆。

4. 分层拆解 ​

4.1 边界的定义与反例 ​

分层的判断标准只有一条:这个断言是否依赖真实浏览器行为——布局、滚动、焦点、真实网络、Cookie 策略。

定义:组件测试把组件当成一个有输入输出的函数,输入是 props 与用户交互,输出是渲染结果与事件。

反例:断言 wrapper.vm.internalCounter 等于 3。这个测试看起来在测状态,实际是在测实现;组件内把计数器改名,测试立刻失败,而功能完全正常。团队一旦经历两次这种误报,就会开始绕过测试。

层次工具运行环境覆盖什么单次耗时量级
纯逻辑 / 组合式函数Vitestnode计算、状态机、格式化毫秒
组件渲染与交互Vitest + @vue/test-utilsjsdom / happy-domprops、emits、slots、条件渲染十毫秒
页面级集成Vitest(挂载页面 + 路由 mock)jsdom页面与 store 的协作百毫秒
关键用户路径Playwright真实浏览器登录、下单、支付跳转秒
视觉回归Playwright真实浏览器样式回归、多语言布局秒

一条经验值:E2E 保留 5 到 15 条,多了维护成本指数上升。反过来把该在 E2E 验的东西硬塞进组件测试也是浪费——路由跳转后 URL 是否变化、登录 Cookie 的 SameSite 是否生效、真实滚动容器里的吸顶效果,在 jsdom 里要么测不出,要么测出来不算数。

4.2 Vitest 的双环境配置 ​

test.projects 是 Vitest 3.2 起替代 workspace 的正式配置(workspace 已废弃)。好处是同一进程跑两套环境:组合式函数不需要 DOM,就别让它们进 jsdom 拖慢启动。

ts
// vitest.config.ts —— Vitest 5.1.x
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'vitest/config'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    // 非 Nuxt 项目里 '~' 这类别名要自己声明,否则测试 import 解析失败
    alias: { '~': fileURLToPath(new URL('./app', import.meta.url)) },
  },
  test: {
    projects: [
      { test: { name: 'unit', environment: 'node', include: ['src/**/*.spec.ts'] } },
      {
        test: {
          name: 'component',
          environment: 'jsdom',
          include: ['tests/components/**/*.spec.ts'],
          setupFiles: ['tests/setup.ts'],
        },
      },
    ],
  },
})

environment: 'jsdom' 需要自己装 jsdom 依赖,Vitest 不替你装。漏装时的报错信息很不直观,通常是一句找不到环境的英文提示,第一次遇到会以为是配置写错了。

4.3 mount 的三个实践细节 ​

ts
// tests/components/DataTable.spec.ts —— Vitest 5.1 + @vue/test-utils 2.6
import { h } from 'vue'
import { mount } from '@vue/test-utils'
import { describe, expect, it } from 'vitest'
import DataTable from '~/components/DataTable.vue'

const rows = [{ id: 'o-1', name: '订单 A' }, { id: 'o-2', name: '订单 B' }]

describe('DataTable', () => {
  it('把 rows 透传给 cell 插槽', () => {
    const wrapper = mount(DataTable, {
      props: { rows },
      // 作用域插槽用函数式写法,参数类型可直接标注
      slots: {
        cell: ({ row }: { row: { name: string } }) => h('span', { class: 'name' }, row.name),
      },
    })
    // 预期输出:['订单 A', '订单 B']
    expect(wrapper.findAll('.name').map((n) => n.text())).toEqual(['订单 A', '订单 B'])
  })

  it('点击删除时抛出 remove 事件并带上 id', async () => {
    const wrapper = mount(DataTable, { props: { rows } })
    await wrapper.findAll('button')[0]!.trigger('click')
    // 预期输出:[['o-1']] —— 参数数组的数组
    expect(wrapper.emitted('remove')).toEqual([['o-1']])
  })
})

三个细节

trigger 必须 await,否则 Vue 的异步更新队列还没 flush,断言会随机失败。emitted('remove') 返回"参数数组的数组",写成 [['o-1']] 才能精确断言参数。依赖路由或全局组件的用 global.stubs / global.plugins 显式注入,别指望 mount 自动带上应用全部插件——那样组件测试就变成半个 E2E 了。

shallowMount 与 mount 的选择常被搞反:shallowMount 把子组件替换成 stub,隔离干净但会掩盖"父组件把 props 传错"的问题。默认用 mount,只在子组件很重(图表、富文本编辑器)时用 global.stubs 精确替换那一个依赖。

vi.mock 会被提升到文件顶部,工厂函数里不能引用外部变量,要用 vi.hoisted 提上去:

ts
const api = vi.hoisted(() => ({ fetchOrders: vi.fn() }))
vi.mock('~/api/orders', () => api)

定时器逻辑(轮询、防抖)用 vi.useFakeTimers() 配 await vi.advanceTimersByTimeAsync(1000),不要用真实 setTimeout 等一秒。

4.4 Playwright 侧的两项配置 ​

ts
// playwright.config.ts —— @playwright/test 1.65.x
import { defineConfig, devices } from '@playwright/test'

export default defineConfig({
  testDir: './e2e',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  failOnFlakyTests: !!process.env.CI, // 重试后才过的用例,CI 里依然判红
  reporter: process.env.CI ? [['blob'], ['github']] : 'list',
  use: {
    baseURL: 'http://127.0.0.1:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
  projects: [
    { name: 'setup', testMatch: /auth\.setup\.ts/ },
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'], storageState: 'e2e/.auth/user.json' },
      dependencies: ['setup'],
    },
  ],
})

failOnFlakyTests 是整套配置里最值得打开的一项。默认情况下"重试后通过"记为通过,flake 就永远藏在绿灯里;打开它,一次 flake 就变成一次失败,逼团队去修。setup 项目登录一次把 storageState 写盘,业务用例直接复用,不必每条都点一遍登录表单。

网络拦截要克制:第三方统计、推荐位、客服 SDK 用 page.route 固定响应是合理的;但不要拦截自家业务接口,否则你测的是"一组假数据能不能渲染",跨端联调的问题一个也发现不了。定位器优先 getByRole / getByLabel / getByText,CSS 选择器与 data-testid 都是退路。

4.5 flake 的六类根因 ​

现象根因修法
偶发"元素不存在"固定 sleep 或立即断言换 web-first 断言,自动等待
只在 CI 失败本地有缓存或旧数据用例自建数据,不依赖既有记录
并发互相干扰共享账号、租户、库存随机后缀建独立数据,用 API 预置
时间相关断言飘时区、Date.now()、跨天固定 timezoneId,或注入时间
动画导致点击落空过渡未结束关动画,或断言可交互再点
重试才通过真实竞态这是产品 bug,先修产品

诊断手段比修法更重要:--repeat-each=10 把偶发放大成必现,--last-failed 只跑上次失败的用例,录下的 trace 用 npx playwright show-trace 打开能看到每步 DOM 快照与网络瀑布。

不要这样解决 flake

不要用"加长超时"处理 flake。它只是把一个会飘的断言变成一次更久的等待,跑批时间变长,根因仍在。CI 上重试次数大于 0 却从不看 flake 统计,等于把红灯吞掉。

5. 上机:把一条 flake 复现出来 ​

bash
# 预期输出:10 次里至少 1 次失败,且失败点相同
pnpm exec playwright test e2e/coupon.spec.ts --repeat-each=10
bash
# 预期输出:只在失败用例上重跑,秒级返回
pnpm exec playwright test --last-failed

CI 上是"分片后合并",三个分片各出 blob 报告,再由汇总 Job 合并成一份 HTML。否则你会得到三份互不相干的失败列表,定位成本翻倍。

yaml
# .github/workflows/test.yml 片段 —— Playwright 1.65 / Vitest 5.1
jobs:
  e2e:
    strategy: { fail-fast: false, matrix: { shard: [1, 2, 3] } }
    steps:
      - uses: actions/cache@v4
        with:
          path: ~/.cache/ms-playwright
          key: pw-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
      - run: pnpm exec playwright install --with-deps chromium
      - run: pnpm exec playwright test --shard=${{ matrix.shard }}/3
      - uses: actions/upload-artifact@v4
        if: always()
        with: { name: 'blob-${{ matrix.shard }}', path: blob-report }
  merge:
    needs: [e2e]
    if: always()
    steps:
      - run: pnpm exec playwright merge-reports --reporter=html ./all-reports

浏览器缓存的 key 必须带 lockfile 哈希。Playwright 升级后旧内核还在缓存里,会出现"本地能跑、CI 报选择器不存在"的诡异问题。Linux runner 上 --with-deps 仍需安装系统依赖,缓存只省下载时间。

6. 三个被验证过的误解 ​

第一,很多人以为重试能提高稳定性,实际上它降低的是可信度。 重试后通过被记为通过时,flake 与真实失败混在一起,团队学会重跑,所有红灯失效。正确顺序是先把 flake 修掉,再保留 1 到 2 次重试作为网络抖动的缓冲。

第二,很多人以为 E2E 越多越安全,实际上超过 20 条就是在给自己排维护班。 每条 E2E 都要维护数据、等待策略、定位器,而它抓到的多数问题在组件测试层就能抓到,且失败信息更具体。判断方法是看失败时的日志:如果 E2E 报的是"页面上没这个按钮",而组件测试能报"props 传错了",说明这条断言下移更划算。

第三,很多人以为拦截接口能让测试更快更稳,实际上它让测试失去了对象。 把自家业务接口全拦掉之后,跨端字段名不一致、分页参数错位这类问题一条都发现不了。第三方依赖拦截是合理的,自家接口拦截等于在测 mock。

一处只有真正调过 CI 的人才知道的细节

failOnFlakyTests 打开的第一周,构建失败率会从 2% 跳到 15% 左右——这不是变差了,是原本被吞掉的 flake 全部显形。我们是靠这一波失败清单在两周内修掉了 23 条用例。如果团队没有心理准备,这项配置会在第一次全员会上被要求关掉,所以上线前要先沟通口径。

7. 把结论搬回你的仓库 ​

7.1 取现有 E2E 套件里耗时最长的一条,判断它是否依赖真实浏览器行为。若否,写出组件测试版本的 mount 调用。

7.2 你的 CI 有 3 个分片,单分片耗时分别为 4 分、4 分、9 分。请给出调整方案,并说明为什么"把分片数提到 6"可能反而更慢。

7.3 一条用例在本地连续 20 次通过,在 CI 上每 5 次失败 1 次。请写出你的诊断顺序,并说明第一个要看的证据是什么。

8. 名词对照 ​

名词英文一句话解释
组件测试component test挂载单个组件、断言对外契约的测试
视觉回归visual regression比对截图以发现样式变化
Web-first 断言web-first assertion自带自动等待与重试的断言写法
状态复用storageState把登录后的 Cookie 与 localStorage 存盘复用
flakeflaky test同一代码多次运行结果不一致的用例
分片sharding把用例集合切成若干份并行执行
报告合并merge-reports把多分片的 blob 报告合成一份 HTML

截至 2026 年 11 月,本文版本基线为 Vitest 5.1.0、@vue/test-utils 2.6.0、@playwright/test 1.65.1、Vue 3.5.45,均为 npm 上的 latest。projects 与 typecheck 的字段以 Vitest 配置参考 为准,failOnFlakyTests 与分片合并以 Playwright 测试配置 和 merge-reports 为准。

最后一条判断:不建议在项目初期就上视觉回归。它需要稳定的渲染环境(字体、内核、设备像素比),环境不稳时截图差异会全是噪声,最后团队只能把它设成不阻断合并——那时它既不保护你,也不提醒你,只是多占一份 CI 时间。等样式改动频繁且回归成本真的出现,再上。