Vitest 类型测试实战:用 expectTypeOf 与 assertType 编写零运行时开销的类型断言
Vitest 类型测试实战:用 expectTypeOf 与 assertType 编写零运行时开销的类型断言
本指南围绕 Vitest 的类型测试(Type Testing)能力展开,核心目标是在不执行任何运行时逻辑的前提下,直接对 TypeScript 类型进行编译期断言,把「类型正确性」纳入自动化测试体系。读完本文,你将掌握 .test-d.ts 文件的编写规范、typecheck 配置项的完整用法、expectTypeOf 与 assertType 两大 API 的全部匹配器形态,以及如何与现有单元测试、CI 流程无缝集成。该技能文档基于 Vitest 5.0.1 生成(见 skills/vitest/SKILL.md),文中所有命令与配置均以此版本为基准。
一、为什么需要「类型测试」
常规单元测试解决的是「运行行为是否正确」:调用函数、断言返回值、验证副作用。但 TypeScript 项目的另一类正确性——「类型是否正确」——却常常游离在测试体系之外,仅靠 tsc 全量编译或编辑器提示来兜底。
类型测试的价值恰恰在于填补这个空白:
- 零运行时开销:类型断言由编译器(
tsc/vue-tsc)在编译期完成,产物中不产生任何测试代码,不影响生产包体积与运行性能; - 锁定 API 契约:当某个函数改变了返回类型、某个接口增加了必填字段,类型测试能在不运行任何代码的情况下第一时间暴露破坏性变更;
- 驱动泛型与重载设计:泛型函数、条件类型、品牌类型(branded type)等高级类型特性难以用运行时测试验证,却非常适合用类型断言直接描述预期。
在 Vitest 中,类型测试通过 typecheck 配置开启,使用 .test-d.ts 扩展名区分于普通测试文件,由 expectTypeOf 与 assertType 两个内置 API 完成断言。
二、开启 typecheck:配置详解
类型测试默认是关闭的,需要在配置文件的 test.typecheck 节点下显式启用。配置既可以直接写在 vitest.config.ts,也可以放在与 Vite 共享的 vite.config.ts 的 test 字段中(参考 skills/vitest/references/core-config.md 中的配置约定):
// vitest.config.ts
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
typecheck: {
enabled: true,
// 仅做类型检查,不运行其中的 runtime 测试代码
only: false,
// 检查器:'tsc' 或 'vue-tsc'
checker: 'tsc',
// 参与类型检查的文件匹配模式
include: ['**/*.test-d.ts'],
// 使用的 tsconfig 路径
tsconfig: './tsconfig.json',
},
},
})
各配置项说明:
| 配置项 | 取值 | 作用 |
|---|---|---|
enabled |
true / false(默认 false) |
总开关,开启后才允许运行类型测试 |
only |
true / false(默认 false) |
为 true 时仅执行类型检查,跳过文件内的 runtime 测试;适合把类型测试与单元测试彻底分离的场景 |
checker |
'tsc' / 'vue-tsc' |
选择类型检查引擎。Vue 项目中使用 vue-tsc 才能正确解析 .vue 单文件组件的类型;纯 TS 项目使用 tsc 即可 |
include |
glob 数组 | 声明哪些文件算作类型测试文件,默认即为 ['**/*.test-d.ts'] |
tsconfig |
路径字符串 | 指定类型检查使用的 tsconfig.json 位置,默认从项目根目录解析 |
两个实用提示:
enabled: true与only: true组合是纯类型检查的推荐形态:此时.test-d.ts文件不会被当作运行时测试执行,既规避了「类型测试文件里写了运行时逻辑」的误执行风险,也避免了无谓的进程开销;tsconfig与include的边界关系:tsconfig.json中的include/exclude同样约束类型检查的扫描范围,配置typecheck.include时建议与tsconfig的工程范围保持一致,避免检查到无关目录拖慢速度。
三、第一个类型测试文件:.test-d.ts 约定
类型测试文件使用 .test-d.ts 扩展名(d 即 declaration / type definition),这是 Vitest 识别「这是类型测试」的默认依据,也与 typecheck.include 的默认值 ['**/*.test-d.ts'] 对应。
// math.test-d.ts
import { expectTypeOf } from 'vitest'
import { add } from './math'
test('add returns number', () => {
expectTypeOf(add).returns.toBeNumber()
})
说明:
import { expectTypeOf } from 'vitest'与运行时测试共用同一个vitest包,无需额外安装类型测试专用依赖;test()在这里只起到「组织断言块」的作用,内部断言完全由编译器执行;expectTypeOf(add)先拿到函数类型,.returns取到返回值类型,.toBeNumber()断言其是number。
四、expectTypeOf API 全览
expectTypeOf 是类型测试的核心 API,用于对「类型」做断言(区别于下文对「值」做断言的 assertType)。它通过链式调用组织出一套类型 DSL。
4.1 基础类型断言
直接以泛型参数形式传入目标类型,再调用对应的 toBeXxx 匹配器:
import { expectTypeOf } from 'vitest'
// 基础类型检查
expectTypeOf<string>().toBeString()
expectTypeOf<number>().toBeNumber()
expectTypeOf<boolean>().toBeBoolean()
expectTypeOf<null>().toBeNull()
expectTypeOf<undefined>().toBeUndefined()
expectTypeOf<void>().toBeVoid()
expectTypeOf<never>().toBeNever()
expectTypeOf<any>().toBeAny()
expectTypeOf<unknown>().toBeUnknown()
expectTypeOf<object>().toBeObject()
expectTypeOf<Function>().toBeFunction()
expectTypeOf<[]>().toBeArray()
expectTypeOf<symbol>().toBeSymbol()
这套匹配器覆盖了 TypeScript 的核心类型体系:基础原始类型(string / number / boolean / symbol / null / undefined)、特殊类型(void / never / any / unknown / object / Function)以及数组。每种断言失败时都会给出可读的编译错误信息,指出「期望类型」与「实际类型」的差异。
4.2 值类型检查
expectTypeOf 同样接收值作为参数,直接从值的字面量推断类型:
const value = 'hello'
expectTypeOf(value).toBeString()
const obj = { name: 'test', count: 42 }
expectTypeOf(obj).toExtend<{ name: string }>()
expectTypeOf(obj).toHaveProperty('name')
这里展示了两种与「值」相关的常见断言:
toExtend<{ name: string }>():断言obj的类型是{ name: string }的子集(即obj可以赋值给该类型);toHaveProperty('name'):断言类型上存在名为name的属性。
4.3 函数类型:parameters / returns / parameter(n)
函数类型是类型测试的重点场景,expectTypeOf 提供了对函数签名的三个维度的访问器——.parameters(参数元组)、.returns(返回值)与 .parameter(n)(第 n 个参数):
function greet(name: string): string {
return `Hello, ${name}`
}
expectTypeOf(greet).toBeFunction()
expectTypeOf(greet).parameters.toEqualTypeOf<[string]>()
expectTypeOf(greet).returns.toBeString()
// 参数逐一检查
expectTypeOf(greet).parameter(0).toBeString()
.parameters返回参数类型元组,可用toEqualTypeOf<[string]>()做精确比对;.returns返回返回值类型,可直接套用toBeString()等基础匹配器;.parameter(0)按索引访问单个参数,适合对多参数函数逐位校验。
4.4 对象类型:toHaveProperty 与 toExtend
对接口(interface)与对象字面量的断言,围绕「属性存在性」与「形状兼容性」两个维度展开:
interface User {
id: number
name: string
email?: string
}
expectTypeOf<User>().toHaveProperty('id')
expectTypeOf<User>().toHaveProperty('name').toBeString()
// 检查形状
expectTypeOf({ id: 1, name: 'test' }).toExtend<User>()
值得注意的细节:
toHaveProperty('name').toBeString()是链式写法:先断言属性存在,再对其类型继续断言;email?: string是可选属性,不影响{ id: 1, name: 'test' }对User的扩展性(子集匹配);若写成toEqualTypeOf精确匹配,则必须带上email字段——这正是「子集匹配」与「精确匹配」的核心差异,见下一节。
五、相等 vs 匹配:toEqualTypeOf 与 toExtend
类型断言中「完全相同」与「兼容/子集」是两个极易混淆的语义,Vitest 用两个匹配器明确区分:
interface A { x: number }
interface B { x: number; y: string }
// toExtend - 子集匹配(替代已弃用的 toMatchTypeOf)
expectTypeOf<B>().toExtend<A>() // B extends A,成立
// toEqualTypeOf - 精确匹配
expectTypeOf<A>().not.toEqualTypeOf<B>() // 两者不相同
expectTypeOf<A>().toEqualTypeOf<{ x: number }>() // 结构完全一致,成立
关键结论(来自关联文档 skills/vitest/references/advanced-type-testing.md):
toMatchTypeOf已被弃用(expect-type v1.2+ 起),子集匹配统一改用toExtend;toExtend<T>()断言当前类型可以赋值给T,即T是当前类型的父集——适合「实现类满足接口契约」「返回值兼容某个形状」这类宽松断言;toEqualTypeOf<T>()断言两个类型完全相等(结构级相等),适合锁定精确的 API 形状;配合.not前缀(如expectTypeOf<A>().not.toEqualTypeOf<B>())可反向断言「两者必须不同」。
实际选型建议:公共 API 的返回类型用 toEqualTypeOf 锁定精确契约,内部实现与兼容性检查用 toExtend 保留演进空间。
六、进阶类型场景
6.1 品牌类型(Branded Types)
品牌类型(nominal typing 的 TS 惯用实现)用交叉类型叠加一个不可见的品牌字段来区分「结构相同但语义不同」的类型。类型测试是验证品牌类型不被混淆的最直接手段:
type UserId = number & { __brand: 'UserId' }
type PostId = number & { __brand: 'PostId' }
expectTypeOf<UserId>().not.toEqualTypeOf<PostId>()
expectTypeOf<UserId>().not.toEqualTypeOf<number>()
- 尽管
UserId与PostId底层都是number,但品牌字段使其结构不同,toEqualTypeOf能够识别出差异; not.toEqualTypeOf<number>()进一步确认品牌类型与裸number不相等——这正是品牌类型存在的意义。
6.2 泛型类型
泛型函数在不同实例化下的返回类型,可以用 .returns 逐个实例化断言:
function identity<T>(value: T): T {
return value
}
expectTypeOf(identity<string>).returns.toBeString()
expectTypeOf(identity<number>).returns.toBeNumber()
对每个泛型实例分别断言,等价于为泛型签名补充了「实例化矩阵」级别的类型契约,能有效捕获泛型实现中类型收窄丢失的问题。
6.3 可空类型(Nullable Types)
联合了 null / undefined 的类型用专门的匹配器验证:
type MaybeString = string | null | undefined
expectTypeOf<MaybeString>().toBeNullable()
expectTypeOf<string>().not.toBeNullable()
toBeNullable()断言类型包含null或undefined成员;not.toBeNullable()反向断言类型不含空值,常用于校验「可空值已被收窄」的防护逻辑。
七、assertType:对「值」做编译期断言
与 expectTypeOf 面向「类型」不同,assertType<T>(value) 面向「值」:在编译期断言该值可以赋值给 T,且不产生任何运行时断言代码(运行时无 assert 调用,纯编译期检查):
import { assertType } from 'vitest'
function getUser(): User | null {
return { id: 1, name: 'test' }
}
test('returns user', () => {
const result = getUser()
// @ts-expect-error - 应该类型检查失败
assertType<string>(result)
// 正确类型
assertType<User | null>(result)
})
使用要点:
assertType<User | null>(result)断言result的类型可以赋值给User | null;- 当断言错误时(例如把
User | null传给assertType<string>),编译期直接报错,但不会像expect()那样抛出运行时异常; - 因此它适合「只想在类型层面对值做闸门、无需运行时行为」的场景,常与
@ts-expect-error配合使用(见下节)。
八、用 @ts-expect-error 验证「类型错误」
类型测试的另一大用途是验证某段代码确实会产生类型错误——即把「编译器应该拒绝」作为预期行为固化下来:
test('rejects wrong types', () => {
function requireString(s: string) {}
// @ts-expect-error - number 不能赋值给 string
requireString(123)
})
@ts-expect-error声明「下一行必然存在类型错误」;若下一行实际没有错误,编译器反而会因「多余的 expect-error 注释」而报错——这构成双向约束;- 常用场景:验证类型守卫、重载函数、条件类型在错误输入下确实被拒绝,防止「类型过宽导致错误输入被意外放行」的回归;
- 在
.test-d.ts文件中使用它,与普通 TS 文件语义完全一致,无需额外配置。
九、运行类型测试:CLI 命令
类型测试开启后,通过 CLI 即可运行,命令形式与普通测试互补(完整 CLI 语义参考 skills/vitest/references/core-cli.md):
# 运行类型测试
vitest typecheck
# 与单元测试一起运行
vitest --typecheck
# 仅运行类型测试
vitest --typecheck.only
三种形态的区别:
| 命令 | 行为 |
|---|---|
vitest typecheck |
专用于类型测试的入口,只处理 .test-d.ts 等类型测试文件 |
vitest --typecheck |
在常规测试运行中同时启用类型检查,单元测试与类型测试一并执行 |
vitest --typecheck.only |
等价于配置中 typecheck.only: true,本次运行只做类型检查 |
接入 package.json 脚本时建议按 CI 与本地区分:
{
"scripts": {
"test:type": "vitest typecheck",
"test:all": "vitest --typecheck"
}
}
vitest typecheck 命令同样支持 -t(按名称过滤)、--dir(限定目录)等通用过滤参数,可参考 skills/vitest/references/core-cli.md 中的过滤选项组合使用。
十、混合测试文件:运行时测试与类型测试共存
类型测试不要求与单元测试物理隔离。同一个文件中可以同时组织 runtime 断言与类型断言,让「一个功能」的两种正确性测试内聚在一起:
// user.test.ts
import { describe, expect, expectTypeOf, test } from 'vitest'
import { createUser } from './user'
describe('createUser', () => {
test('runtime: creates user', () => {
const user = createUser('John')
expect(user.name).toBe('John')
})
test('types: returns User type', () => {
expectTypeOf(createUser).returns.toExtend<{ name: string }>()
})
})
- 文件扩展名仍是常规的
.test.ts,但内部混用expect()(运行时)与expectTypeOf(编译期); - 这种形态下建议在配置中将
typecheck.include同时纳入常规测试文件,或直接用vitest --typecheck运行,保证两类断言都被检查; - 若希望彻底分离「类型测试」与「运行时测试」,则回到
.test-d.ts扩展名 +typecheck.only: true的方案。
十一、最佳实践与关键要点
综合关联文档 skills/vitest/references/advanced-type-testing.md 与 Vitest 配置/CLI 约定,形成以下可落地的实践清单:
- 用
.test-d.ts声明类型测试文件,与运行时测试文件在扩展名层面即完成隔离,避免被普通vitest run误执行; expectTypeOf负责类型断言:基础类型用toBeXxx,函数用.parameters/.returns/.parameter(n),对象用toHaveProperty/toExtend;- 子集匹配统一用
toExtend(toMatchTypeOf自 expect-type v1.2+ 起弃用),精确匹配用toEqualTypeOf,并用.not前缀表达反向约束; @ts-expect-error固话「应当报错」的类型行为,双向约束错误边界;assertType只做编译期赋值检查,适合值级别的类型闸门,无运行时开销;- 运行入口:
vitest typecheck单独跑类型测试,vitest --typecheck与单元测试合并执行,vitest --typecheck.only强制只做类型检查; - 配置层面:在
vitest.config.ts/vite.config.ts的test.typecheck节点开启enabled,按需设置checker: 'vue-tsc'(Vue 项目)、only: true(纯类型检查)与tsconfig路径; - CI 落地:将
vitest typecheck或vitest --typecheck纳入流水线脚本,与vitest run(单元测试)并列执行,让类型契约与运行时行为同时成为回归防线。
至此,你可以将类型测试作为 Vitest 测试体系的一等公民:既能在不运行任何代码的前提下锁定 API 类型契约,也能通过 expectTypeOf / assertType / @ts-expect-error 覆盖泛型、品牌类型、可空类型等纯类型层面的复杂场景,让 TypeScript 项目的类型正确性具备与运行时行为同等的可验证性。