测试类型

示例项目

GitHub - 在线运行

Vitest 允许你使用 expectTypeOf 或 assertType 语法来编写类型测试。默认情况下，*.test-d.ts 文件中的所有测试都被视为类型测试，但你可以通过 typecheck.include 配置选项进行调整。

在底层，Vitest 会根据你的配置调用 tsc 或 vue-tsc 并解析其结果。如果 Vitest 发现源代码中存在类型错误，它也会将其打印出来。你可以通过 typecheck.ignoreSourceErrors 配置选项禁用此行为。

请记住，Vitest 不会运行这些文件，它们仅由编译器进行静态分析。这意味着，如果你使用动态名称或 test.each 或 test.for，测试名称不会被评估——它们会原样显示。

WARNING

在 Vitest 2.1 之前，typecheck.include 会覆盖 include 模式，导致运行时测试实际上并未运行，而仅进行了类型检查。

从 Vitest 2.1 开始，如果你的 include 和 typecheck.include 模式存在重叠，Vitest 会将类型测试和运行时测试作为单独的条目进行报告。

CLI 标志也支持类型检查，例如 --allowOnly 和 -t。

import { assertType, expectTypeOf } from 'vitest';
import { mount } from './mount.js';

test('my types work properly', () => {
  expectTypeOf(mount).toBeFunction();
  expectTypeOf(mount).parameter(0).toMatchTypeOf<{ name: string }>();

  // @ts-expect-error name is a string
  assertType(mount({ name: 42 }));
});

测试文件中触发的任何类型错误都将被视为测试失败，因此你可以利用各种类型技巧来测试项目的类型。

你可以在 API 部分 查看所有可用的匹配器列表。

阅读错误

如果你正在使用 expectTypeOf API，请参考 expect-type 文档中的错误消息说明。

当类型不匹配时，.toEqualTypeOf 和 .toMatchTypeOf 会使用特殊的辅助类型来生成尽可能有用的错误消息。但理解它们可能需要一些细致的考量。由于断言是“链式”编写的，失败应该发生在“预期”类型上，而不是“实际”类型上（expect<Actual>().toEqualTypeOf<Expected>()）。这意味着类型错误可能会有些令人困惑——因此该库会生成一个 MismatchInfo 类型，试图明确期望。例如：

expectTypeOf({ a: 1 }).toEqualTypeOf<{ a: string }>();

这个断言会失败，因为 {a: 1} 的类型是 {a: number}，而不是 {a: string}。在这种情况下，错误消息将类似于：

test/test.ts:999:999 - error TS2344: Type '{ a: string; }' does not satisfy the constraint '{ a: \\"Expected: string, Actual: number\\"; }'.
  Types of property 'a' are incompatible.
    Type 'string' is not assignable to type '\\"Expected: string, Actual: number\\"'.

999 expectTypeOf({a: 1}).toEqualTypeOf<{a: string}>()

请注意，报告的类型约束是人类可读的消息，它指明了“预期”和“实际”类型。与其逐字理解“Types of property 'a' are incompatible // Type 'string' is not assignable to type "Expected: string, Actual: number"”这句话，不如直接查看属性名（'a'）和消息：Expected: string, Actual: number。这在大多数情况下会告诉你问题所在。极其复杂的类型调试起来当然更费力，并且可能需要一些实验。如果错误消息实际上具有误导性，请提出问题。

toBe... 方法（如 toBeString、toBeNumber、toBeVoid 等）在被测试的 Actual 类型不匹配时，会因为解析为不可调用类型而失败。例如，像 expectTypeOf(1).toBeString() 这样的断言的失败将类似于：

test/test.ts:999:999 - error TS2349: This expression is not callable.
  Type 'ExpectString<number>' has no call signatures.

999 expectTypeOf(1).toBeString()
                    ~~~~~~~~~~

This expression is not callable 部分帮助不大——有意义的错误是下一行，Type 'ExpectString<number>' has no call signatures。这本质上意味着你传入了一个数字，但断言它应该是一个字符串。

如果 TypeScript 增加了对 "throw" 类型 的支持，这些错误消息将得到显著改善。在此之前，它们将需要一番琢磨。

具体“预期”对象与类型参数

像这样的断言的错误消息：

expectTypeOf({ a: 1 }).toEqualTypeOf({ a: '' });

将不如这种断言的错误消息有用：

expectTypeOf({ a: 1 }).toEqualTypeOf<{ a: string }>();

这是因为 TypeScript 编译器需要为 .toEqualTypeOf({a: ''}) 样式推断类型参数，而这个库只能通过将其与泛型 Mismatch 类型进行比较来标记失败。因此，如果可能，请为 .toEqualTypeOf 和 toMatchTypeOf 使用类型参数，而不是具体类型。如果比较两个具体类型更便捷，你可以使用 typeof：

const one = valueFromFunctionOne({ some: { complex: inputs } });
const two = valueFromFunctionTwo({ some: { other: inputs } });

expectTypeOf(one).toEqualTypeof<typeof two>();

如果你觉得使用 expectTypeOf API 并找出错误很困难，你总是可以使用更简单的 assertType API：

const answer = 42;

assertType<number>(answer);
// @ts-expect-error answer is not a string
assertType<string>(answer);

TIP

当使用 @ts-expect-error 语法时，你可能需要确保没有拼写错误。你可以通过将类型文件包含在 test.include 配置选项中来实现，这样 Vitest 也会实际 运行 这些测试，并在 ReferenceError 时失败。

这个测试会通过，因为它期望一个错误，但“answer”这个词有拼写错误，所以这是一个误报错误：

// @ts-expect-error answer is not a string
assertType<string>(answr); //

运行类型检查

要启用类型检查，只需在 package.json 中的 Vitest 命令添加 --typecheck 标志：

{
  "scripts": {
    "test": "vitest --typecheck"
  }
}

现在可以运行类型检查：

npm

npm run test

yarn

yarn test

pnpm

pnpm run test

bun

bun test

Vitest 根据你的配置使用 tsc --noEmit 或 vue-tsc --noEmit，因此你可以从你的构建流程中移除这些脚本。