Vue / 系统课时
单元测试环境
单元测试环境
本课为 Vue 3 + TypeScript 项目建立可直接运行的 Vitest 测试环境。完成后,你可以编写组件单元测试、在命令行持续运行测试,并生成覆盖率报告作为代码质量检查的一部分。
学习目标
- 配置 Vitest、jsdom 和 Vue Test Utils
- 组织测试目录并编写组件测试
- 运行一次性测试与覆盖率检查
选择测试运行方式
Vitest 与 Vite 使用相近的模块解析和插件机制,适合测试 Vue 组件与 TypeScript 代码。组件测试需要 @vue/test-utils 挂载组件,jsdom 则在 Node.js 中提供浏览器常用的 DOM 环境。
开发阶段使用监听模式,文件变化后只重跑相关测试;持续集成应使用一次性运行模式,避免进程持续等待。
安装测试依赖
以下命令在现有 Vue 3 + TypeScript 项目根目录执行。
npm install -D vitest @vue/test-utils jsdom @vitest/coverage-v8预期输出
added <N> packages, and audited <N> packages in <TIME><N> 和 <TIME> 是动态值。安装完成后,测试运行器、组件挂载工具、DOM 模拟环境和 V8 覆盖率提供器都应出现在 devDependencies 中。
创建测试配置
在项目根目录创建 vitest.config.ts。该配置复用 Vue 插件,声明 @ 路径别名,并统一测试环境、文件范围和覆盖率输出目录。
import { fileURLToPath, URL } from 'node:url'
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vitest/config'
export default defineConfig({
plugins: [vue()],
resolve: {
alias: {
'@': fileURLToPath(new URL('./src', import.meta.url))
}
},
test: {
environment: 'jsdom',
globals: true,
setupFiles: ['./src/test/setup.ts'],
include: ['src/**/*.{test,spec}.{ts,tsx}'],
coverage: {
provider: 'v8',
reporter: ['text', 'html'],
reportsDirectory: 'coverage',
include: ['src/**/*.{ts,vue}'],
exclude: ['src/main.ts', 'src/**/*.d.ts', 'src/test/**']
}
}
})在 src/test/setup.ts 中清理测试可能写入的浏览器状态,避免不同用例相互影响。
import { afterEach } from 'vitest'
afterEach(() => {
localStorage.clear()
sessionStorage.clear()
document.body.innerHTML = ''
})测试文件放在源码旁边或统一测试目录都可以,但命名应稳定。本文采用 *.spec.ts,便于根据组件快速定位测试。
编写第一个组件测试
创建 src/components/CounterButton.vue。
<script setup lang="ts">
import { ref } from 'vue'
const count = ref(0)
</script>
<template>
<button type="button" @click="count++">已点击 {{ count }} 次</button>
</template>创建 src/components/CounterButton.spec.ts。测试只验证组件的公开行为,不直接读取内部 ref,这样重构实现时不必同步修改测试。
import { mount } from '@vue/test-utils'
import { describe, expect, it } from 'vitest'
import CounterButton from './CounterButton.vue'
describe('CounterButton', () => {
it('点击后更新可见计数', async () => {
const wrapper = mount(CounterButton)
expect(wrapper.text()).toContain('已点击 0 次')
await wrapper.get('button').trigger('click')
expect(wrapper.text()).toContain('已点击 1 次')
wrapper.unmount()
})
})这个用例包含初始状态、用户操作和结果断言。trigger 返回 Promise,因此必须使用 await,确保 Vue 完成响应式更新后再断言页面文本。
配置脚本并运行
将以下脚本合并到 package.json 的 scripts 对象中。
{
"scripts": {
"test": "vitest",
"test:run": "vitest run",
"test:coverage": "vitest run --coverage"
}
}执行一次性测试。
npm run test:run预期输出
Test Files 1 passed (1)
Tests 1 passed (1)
Duration <TIME>实际输出还会包含 Vitest 版本、文件路径和耗时明细,<TIME> 会因机器性能不同而变化。退出码为 0 表示所有测试通过。
继续生成覆盖率报告。
npm run test:coverage预期输出
Test Files 1 passed (1)
Tests 1 passed (1)
% Coverage report from v8
File | % Stmts | % Branch | % Funcs | % Lines
CounterButton.vue | <PERCENT> | <PERCENT> | <PERCENT> | <PERCENT>覆盖率数值会随编译结果和测试范围变化。命令还会生成 coverage/index.html,可在浏览器中查看逐文件报告;该目录属于生成物,不应提交到代码仓库。
测试边界与质量判断
覆盖率只能说明代码是否被执行,不能证明断言有效。高质量测试应围绕用户可观察行为,例如渲染文本、事件、属性和边界输入,而不是绑定组件内部变量或实现顺序。
一个测试只验证一个明确行为。涉及网络、时间或随机数时,应使用 Vitest 的 mock 能力隔离外部依赖;不要让单元测试访问真实后端,否则会变慢并产生不稳定结果。
本课总结
- Vitest、Vue Test Utils 与 jsdom 组成 Vue 组件单元测试的基础环境
- 测试应通过公开行为验证结果,并在异步更新后再断言
- 一次性测试和覆盖率命令适合作为持续集成质量门禁
下一课预告
下一课将继续完善代码质量流程,把静态检查、单元测试与覆盖率要求接入提交或持续集成阶段。