JavaScript / TypeScript / 系统课时
为测试代码声明类型
为测试代码声明类型
测试文件经常使用 describe、expect、模拟函数和 Node.js API,这些名称并不一定属于生产代码的类型环境。本节以 Vitest 为例建立独立测试类型配置,并用明确的测试数据类型约束夹具和模拟函数。
学习目标
- 为测试文件单独声明测试运行器提供的全局类型
- 让模拟函数和测试数据获得准确的参数、返回值约束
- 避免把测试框架类型污染到生产代码编译范围
为测试环境建立独立配置
不要把测试框架的全局类型直接塞进整个项目的基础 tsconfig.json。更稳妥的做法是创建测试专用配置,继承生产配置,再只对测试目录补充类型。
假设项目使用 Vitest,并且测试运行在 Node.js 环境,先安装对应依赖:
npm install -D vitest @types/node预期结果
命令成功退出;package.json 的 devDependencies 中包含 vitest 与 @types/node。npm install 的下载数量和耗时会随项目依赖树变化,因此不把这些动态日志作为验证条件。随后创建 tsconfig.test.json:
{
"extends": "./tsconfig.json",
"compilerOptions": {
"types": ["vitest/globals", "node"],
"noEmit": true
},
"include": ["src/**/*.ts", "tests/**/*.ts"]
}types 会限制自动加入全局作用域的类型包,因此这里显式加入 Vitest 和 Node.js。生产编译仍使用原来的 tsconfig.json,不会因为测试框架而凭空获得 describe、it 或 vi 等全局名称。
让运行时与类型声明对齐
声明 vitest/globals 只会让 TypeScript 认识全局测试 API;运行时也必须真正提供这些全局变量。项目若选择全局写法,可在 Vitest 配置中同时打开 globals。
import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
globals: true,
environment: "node",
},
});这段配置的生效行为是:Vitest 在 Node.js 测试环境中提供 describe、it、expect、vi 等全局 API,与 tsconfig.test.json 的类型声明保持一致。若团队更偏好显式依赖,也可以关闭 globals,并在每个测试文件中从 vitest 导入这些 API。
验证测试数据与模拟函数
下面的测试文件可直接放到 tests/load-user.test.ts。User 约束测试夹具,vi.fn 的实现参数和返回值也有明确类型,因此错误样例会在测试运行前暴露。
type User = {
id: string;
name: string;
};
function loadUser(id: string, fetcher: (id: string) => User): User {
return fetcher(id);
}
describe("loadUser", () => {
it("returns the user supplied by the fetcher", () => {
const fixture: User = { id: "u-1", name: "Ada" };
const fetcher = vi.fn((id: string): User => ({ ...fixture, id }));
const result = loadUser("u-2", fetcher);
expect(result).toEqual({ id: "u-2", name: "Ada" });
expect(fetcher).toHaveBeenCalledWith("u-2");
});
});先执行测试专用类型检查:
npx tsc -p tsconfig.test.json && echo "test types ok"预期输出
test types ok再运行该测试文件:
npx vitest run tests/load-user.test.ts预期结果
Test Files 1 passed (1)
Tests 1 passed (1)实际输出还会包含测试文件名和 <TIME> 等运行信息。若把 fixture.id 改成数字,或把 fetcher 改成返回字符串,前面的 TypeScript 检查就会先报告类型不匹配。
避免类型污染和过度断言
如果项目使用 Jest,思路相同:测试专用配置加载 jest 与 node 类型,而不是把测试全局声明扩散到生产代码。不要同时无差别加载 Jest 与 Vitest 的全局类型,否则同名 API 可能造成声明冲突或让编辑器提示变得含糊。
测试数据也不应大量使用 as User 强行断言。优先让对象字面量直接接受 User 检查,或用 satisfies User 校验形状。这样生产类型一旦调整,测试夹具会同步暴露缺失字段,而不是把问题拖到运行阶段。