shoehorn类型级单测技巧大全:用Equal、Expect与accept快速验证类型行为

原创2026-11-14 18:22:411,739 阅读

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:把编译期断言变成"看得见"的报错

定义见 tests/test-utils.ts#L1:

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:给编译器一个"目标插槽"

定义见 tests/test-utils.ts#L41:

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 的类型行为全部钉死了,值得逐行对照阅读:

特别留意其中反复出现的 // @ts-expect-error:它负责负面断言——"这里必须报错"。如果哪天类型放宽了、该行不再报错,tsc 反而会提示 Unused '@ts-expect-error' directive。记住这条经验:类型级单测里,正向用例和反向用例要一起钉死,这是新手最容易漏掉的一环。

5. 实战清单:给你的项目加上类型级单测

  1. 准备一个空操作函数 accept<T>(_t: T) 当"插槽",避免污染业务代码;
  2. 判等用 Equal(或 NotEqual),不要用裸的 extends;
  3. 用 Expect<T extends true> 包装断言,让类型错误变成 IDE 里显眼的红色报错;
  4. 用 // @ts-expect-error 钉死"应该失败"的场景,正向反向双保险;
  5. 调试类型推导时,tests/test-utils.ts 里的 IsAny、Debug、MergeInsertions 都是现成的排查工具。

背后的核心类型 NoInfer、PartialDeep 可参考 src/types.ts,库的完整 API 说明见 rEaDMe.md,入口文件为 src/index.ts。

写在最后

shoehorn 本体很小,但它展示了一条通用思路:类型即契约,契约就要被测试。Equal 负责"严格判等",Expect 负责"让断言可见",accept 负责"给编译器立靶子"——三件套配合,就能用编译器当裁判,把 TypeScript 类型行为稳稳地锁在预期之内。下次你的类型库再"感觉不对却查不到"时,不妨给关键行为补上这几行类型级单测。

登录后查看全文
shoehorn