Vue / 系统课时
编写组件单元测试
编写组件单元测试
本课把查询输入、分页边界和表单提交转化为可重复执行的组件测试。完成后,你将得到一套以组件契约为中心的测试写法,既能验证用户操作,也能检查事件参数和禁用状态。
学习目标
- 使用 Vitest 与 Vue Test Utils 挂载 Vue 3 组件
- 验证输入、事件和分页边界等外部行为
- 用稳定选择器降低测试与页面样式的耦合
先确定组件测试边界
组件单元测试不关心后端接口是否可用,而是验证“给定输入后,组件是否产生正确输出”。输入通常是 props、用户填写和点击;输出通常是渲染结果、按钮状态以及 emit 事件。
本课用一个控制面板同时覆盖三类高频契约:查询框提交关键字、分页到末页后禁止继续前进、表单字段有效后才允许保存。测试只观察公开行为,不直接修改组件内部响应式变量。
准备测试环境
在现有 Vue 3 与 Vite 项目中安装测试依赖:
npm install -D vitest @vue/test-utils jsdom预期结果:
安装完成且命令以退出码 0 结束;package.json 的 devDependencies 中包含 vitest、@vue/test-utils 和 jsdom。在 vite.config.ts 中加入测试环境。以下为片段示例,依赖项目已有的 Vue 插件配置:
import { defineConfig } from 'vitest/config'
import vue from '@vitejs/plugin-vue'
export default defineConfig({
plugins: [vue()],
test: {
environment: 'jsdom',
globals: true,
},
})该配置让测试在模拟浏览器 DOM 的环境中运行;执行后续测试命令即可验证配置是否生效。
编写可测试组件
以下为片段示例。单文件组件通过 data-testid 暴露稳定定位点,不依赖 CSS 类名,因此重构样式不会让测试无故失败。
<script setup lang="ts">
import { ref, watch } from 'vue'
const props = defineProps<{
modelValue: string
page: number
pageCount: number
role: string
}>()
const emit = defineEmits<{
'update:modelValue': [value: string]
query: [keyword: string]
'page-change': [page: number]
save: [payload: { role: string }]
}>()
const keyword = ref(props.modelValue)
const selectedRole = ref(props.role)
watch(() => props.modelValue, value => {
keyword.value = value
})
watch(() => props.role, value => {
selectedRole.value = value
})
function submitQuery() {
emit('update:modelValue', keyword.value)
emit('query', keyword.value.trim())
}
function goNext() {
if (props.page < props.pageCount) {
emit('page-change', props.page + 1)
}
}
function submitForm() {
if (selectedRole.value) {
emit('save', { role: selectedRole.value })
}
}
</script>
<template>
<section>
<input v-model="keyword" data-testid="keyword" />
<button data-testid="query-submit" @click="submitQuery">查询</button>
<button
data-testid="next-page"
:disabled="page >= pageCount"
@click="goNext"
>
下一页
</button>
<form data-testid="role-form" @submit.prevent="submitForm">
<select v-model="selectedRole" data-testid="role">
<option value="">请选择角色</option>
<option value="admin">管理员</option>
<option value="user">普通用户</option>
</select>
<button data-testid="save" :disabled="!selectedRole">保存</button>
</form>
</section>
</template>这是项目文件示例,需保存为 src/components/UserControlPanel.vue。可测试性的关键不是增加测试专用逻辑,而是保持输入、事件和禁用状态清晰可观察。
覆盖输入、事件和边界状态
创建 src/components/__tests__/UserControlPanel.spec.ts。以下为片段示例;每个用例只验证一个行为,失败时能快速定位到查询、分页或表单契约。
import { mount } from '@vue/test-utils'
import { describe, expect, it } from 'vitest'
import UserControlPanel from '../UserControlPanel.vue'
describe('UserControlPanel', () => {
it('提交去除首尾空格后的查询关键字', async () => {
const wrapper = mount(UserControlPanel, {
props: { modelValue: '', page: 1, pageCount: 3, role: '' },
})
await wrapper.get('[data-testid="keyword"]').setValue(' alice ')
await wrapper.get('[data-testid="query-submit"]').trigger('click')
expect(wrapper.emitted('update:modelValue')).toEqual([[' alice ']])
expect(wrapper.emitted('query')).toEqual([['alice']])
})
it('到达末页后禁用下一页且不发送事件', async () => {
const wrapper = mount(UserControlPanel, {
props: { modelValue: '', page: 3, pageCount: 3, role: '' },
})
const nextButton = wrapper.get('[data-testid="next-page"]')
expect(nextButton.attributes('disabled')).toBeDefined()
await nextButton.trigger('click')
expect(wrapper.emitted('page-change')).toBeUndefined()
})
it('角色有效后才提交表单数据', async () => {
const wrapper = mount(UserControlPanel, {
props: { modelValue: '', page: 1, pageCount: 3, role: '' },
})
const saveButton = wrapper.get('[data-testid="save"]')
expect(saveButton.attributes('disabled')).toBeDefined()
await wrapper.get('[data-testid="role"]').setValue('admin')
await wrapper.get('[data-testid="role-form"]').trigger('submit')
expect(wrapper.emitted('save')).toEqual([[{ role: 'admin' }]])
})
})运行指定测试文件:
npx vitest run src/components/__tests__/UserControlPanel.spec.ts预期输出:
✓ src/components/__tests__/UserControlPanel.spec.ts (3 tests)
Test Files 1 passed (1)
Tests 3 passed (3)
Duration <TIME><TIME> 会随机器性能变化。若测试只在整套运行时失败,优先检查是否共享了可变模拟数据、定时器或未清理的全局对象。
避免脆弱测试
不要断言组件内部变量名,也不要用长层级 CSS 选择器定位元素。优先通过可见文本、语义角色或稳定的 data-testid 操作组件,并断言用户能观察到的结果。
边界状态至少包含空值、第一页或末页、禁用按钮以及无效表单。对事件既要检查是否发生,也要检查参数结构,避免“发出了事件但数据错误”仍被判为通过。