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。这个测试看起来在测状态,实际是在测实现;组件内把计数器改名,测试立刻失败,而功能完全正常。团队一旦经历两次这种误报,就会开始绕过测试。
| 层次 | 工具 | 运行环境 | 覆盖什么 | 单次耗时量级 |
|---|---|---|---|---|
| 纯逻辑 / 组合式函数 | Vitest | node | 计算、状态机、格式化 | 毫秒 |
| 组件渲染与交互 | Vitest + @vue/test-utils | jsdom / happy-dom | props、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 拖慢启动。
// 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 的三个实践细节
// 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 提上去:
const api = vi.hoisted(() => ({ fetchOrders: vi.fn() }))
vi.mock('~/api/orders', () => api)定时器逻辑(轮询、防抖)用 vi.useFakeTimers() 配 await vi.advanceTimersByTimeAsync(1000),不要用真实 setTimeout 等一秒。
4.4 Playwright 侧的两项配置
// 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 复现出来
# 预期输出:10 次里至少 1 次失败,且失败点相同
pnpm exec playwright test e2e/coupon.spec.ts --repeat-each=10# 预期输出:只在失败用例上重跑,秒级返回
pnpm exec playwright test --last-failedCI 上是"分片后合并",三个分片各出 blob 报告,再由汇总 Job 合并成一份 HTML。否则你会得到三份互不相干的失败列表,定位成本翻倍。
# .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 存盘复用 |
| flake | flaky 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 时间。等样式改动频繁且回归成本真的出现,再上。