Vue / 系统课时

单元测试环境

单元测试环境

本课为 Vue 3 + TypeScript 项目建立可直接运行的 Vitest 测试环境。完成后,你可以编写组件单元测试、在命令行持续运行测试,并生成覆盖率报告作为代码质量检查的一部分。

学习目标

  • 配置 Vitest、jsdom 和 Vue Test Utils
  • 组织测试目录并编写组件测试
  • 运行一次性测试与覆盖率检查

选择测试运行方式

Vitest 与 Vite 使用相近的模块解析和插件机制,适合测试 Vue 组件与 TypeScript 代码。组件测试需要 @vue/test-utils 挂载组件,jsdom 则在 Node.js 中提供浏览器常用的 DOM 环境。

开发阶段使用监听模式,文件变化后只重跑相关测试;持续集成应使用一次性运行模式,避免进程持续等待。

安装测试依赖

以下命令在现有 Vue 3 + TypeScript 项目根目录执行。

bash
npm install -D vitest @vue/test-utils jsdom @vitest/coverage-v8

预期输出

text
added <N> packages, and audited <N> packages in <TIME>

<N> 和 <TIME> 是动态值。安装完成后,测试运行器、组件挂载工具、DOM 模拟环境和 V8 覆盖率提供器都应出现在 devDependencies 中。

创建测试配置

在项目根目录创建 vitest.config.ts。该配置复用 Vue 插件,声明 @ 路径别名,并统一测试环境、文件范围和覆盖率输出目录。

ts
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 中清理测试可能写入的浏览器状态,避免不同用例相互影响。

ts
import { afterEach } from 'vitest'

afterEach(() => {
  localStorage.clear()
  sessionStorage.clear()
  document.body.innerHTML = ''
})

测试文件放在源码旁边或统一测试目录都可以,但命名应稳定。本文采用 *.spec.ts,便于根据组件快速定位测试。

编写第一个组件测试

创建 src/components/CounterButton.vue。

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,这样重构实现时不必同步修改测试。

ts
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 对象中。

json
{
  "scripts": {
    "test": "vitest",
    "test:run": "vitest run",
    "test:coverage": "vitest run --coverage"
  }
}

执行一次性测试。

bash
npm run test:run

预期输出

text
Test Files  1 passed (1)
Tests       1 passed (1)
Duration    <TIME>

实际输出还会包含 Vitest 版本、文件路径和耗时明细,<TIME> 会因机器性能不同而变化。退出码为 0 表示所有测试通过。

继续生成覆盖率报告。

bash
npm run test:coverage

预期输出

text
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 组件单元测试的基础环境
  • 测试应通过公开行为验证结果,并在异步更新后再断言
  • 一次性测试和覆盖率命令适合作为持续集成质量门禁

下一课预告

下一课将继续完善代码质量流程,把静态检查、单元测试与覆盖率要求接入提交或持续集成阶段。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

单元测试环境

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通