Vitest 类型测试实战:用 expectTypeOf 与 assertType 编写零运行时开销的类型断言

原创2026-10-11 20:49:121,840 阅读
文章标签:AI 技能开发工具

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 位置,默认从项目根目录解析

两个实用提示:

  1. enabled: true 与 only: true 组合是纯类型检查的推荐形态:此时 .test-d.ts 文件不会被当作运行时测试执行,既规避了「类型测试文件里写了运行时逻辑」的误执行风险,也避免了无谓的进程开销;
  2. 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 项目的类型正确性具备与运行时行为同等的可验证性。

登录后查看全文
skills