shoehorn类型级单测技巧大全:用Equal、Expect与accept快速验证类型行为
shoehorn类型级单测技巧大全:用Equal、Expect与accept快速验证类型行为
如果你用过 shoehorn——这个让你在 TypeScript 测试里安全传入部分 mock 数据的工具库——可能会好奇:它自己的类型行为是怎么被"单元测试"住的?本文带你拆解 shoehorn 仓库中的三件套 Equal、Expect、accept,用 4 个步骤讲透 TypeScript 类型级单测的核心技巧,帮你把类型错误暴露在编译期,而不是等用户踩坑。
1. 60 秒认识 shoehorn:告别 as 断言的 mock 利器
shoehorn 解决的是一个很痛的测试场景:被测函数要一个大对象参数,而你只关心其中一两个字段。传统写法被迫写 as Request,甚至 as unknown as Request 双重断言——类型安全形同虚设,IDE 补全也全部丢失。
shoehorn 提供三个 API(实现见 src/utils.ts),用类型体操替代粗暴断言:
| API | 作用 | 多余属性 |
|---|---|---|
fromPartial |
传"深度部分"对象,字段名仍受检查 | ❌ 会报错 |
fromAny |
传任意值,仍保留原类型的自动补全 | ✅ 不报错 |
fromExact |
强制传齐全部字段,用于在 partial/exact 间切换 | ❌ 会报错 |
关键点在于:三个函数在运行时几乎什么都不做(直接返回你传入的值),真正的价值全在类型推导层。这就引出了本文主题——类型层的行为,必须用"类型级单测"来守护。
2. 为什么需要"类型级单测"?
运行时的 expect 只能验证值,验证不了类型。对 shoehorn 这类库来说,真正容易回归的恰恰是类型行为,例如:
fromPartial不传进函数参数时,返回值类型是不是unknown?- 显式传类型参数时,深度 partial 是否真的"深"?
fromAny传入完全错误的类型时,是否确实不报错?
这些行为一旦被改动破坏,只会在下游使用者的代码里"隐晦地变红"。把它们固化成仓库内的类型断言用例,每次改动由编译器把关,成本最低、收益最高。shoehorn 用 package.json 中的 lint(即 tsc)脚本来跑这些断言:类型断言失败 = 编译报错,红灯一目了然。
3. 类型断言三件套:Equal、Expect、accept
三个工具全部定义在 tests/test-utils.ts 中,几十个行就能搬去你自己的项目复用。
3.1 Equal:判断两个类型是否"严格相等"
定义见 tests/test-utils.ts#L7-L11:
type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends
<T>() => T extends Y ? 1 : 2
? true
: false;
为什么不用简单的双向 extends 判等?因为双向 extends 会放过一些"形似而神不同"的类型(例如带 undefined 可选属性与完全没有该属性的情况)。Equal 通过比较两个带条件类型的泛型函数,实现了严格的类型相等判断——这是类型级单测里最值得收藏的一招。
3.2 Expect:把编译期断言变成"看得见"的报错
export type Expect<T extends true> = T;
用法就一行:
type test = Expect<Equal<typeof result, unknown>>;
如果 result 的类型和 unknown 不相等,Equal 计算出 false,不满足 T extends true 约束,tsc 直接在这一行报错。它相当于类型世界里的 expect(...).toBe(true)——测试用例写死在代码里,IDE 里就是红色波浪线。
3.3 accept:给编译器一个"目标插槽"
export const accept = <T>(_t: T) => {};
accept 不执行任何逻辑,只负责显式声明类型参数,告诉编译器"这个参数应该是 T"。在 tests/fromPartial.test.ts 中就能看到它的典型用法:
accept<{ foo: string; bar: number }>(
fromPartial({ foo: "bar" }),
);
这行断言的是"fromPartial 允许只传部分字段,且推导出的类型是完整目标类型"。一旦 fromPartial 的类型推导回归,这一行立刻变红。
4. 完整案例:一条断言只需两行
把三件套组合起来,一条标准的类型级测试非常简洁:
const result = fromPartial<{ foo: string; bar: string }>({
foo: "str",
});
type test = Expect<Equal<typeof result, { foo: string; bar: string }>>;
第一行"干活",第二行"验收"。shoehorn 的三个测试文件把三个 API 的类型行为全部钉死了,值得逐行对照阅读:
- tests/fromPartial.test.ts:部分传入、深度 partial、函数类型参数、带调用签名的接口……
- tests/fromAny.test.ts:任意值通过、且不产生多余属性报错
- tests/fromExact.test.ts:缺字段必须报错
特别留意其中反复出现的 // @ts-expect-error:它负责负面断言——"这里必须报错"。如果哪天类型放宽了、该行不再报错,tsc 反而会提示 Unused '@ts-expect-error' directive。记住这条经验:类型级单测里,正向用例和反向用例要一起钉死,这是新手最容易漏掉的一环。
5. 实战清单:给你的项目加上类型级单测
- 准备一个空操作函数
accept<T>(_t: T)当"插槽",避免污染业务代码; - 判等用
Equal(或NotEqual),不要用裸的extends; - 用
Expect<T extends true>包装断言,让类型错误变成 IDE 里显眼的红色报错; - 用
// @ts-expect-error钉死"应该失败"的场景,正向反向双保险; - 调试类型推导时,tests/test-utils.ts 里的
IsAny、Debug、MergeInsertions都是现成的排查工具。
背后的核心类型 NoInfer、PartialDeep 可参考 src/types.ts,库的完整 API 说明见 rEaDMe.md,入口文件为 src/index.ts。
写在最后
shoehorn 本体很小,但它展示了一条通用思路:类型即契约,契约就要被测试。Equal 负责"严格判等",Expect 负责"让断言可见",accept 负责"给编译器立靶子"——三件套配合,就能用编译器当裁判,把 TypeScript 类型行为稳稳地锁在预期之内。下次你的类型库再"感觉不对却查不到"时,不妨给关键行为补上这几行类型级单测。