用小型 TypeScript Program 测试类型感知规则
有条 ESLint 规则要判断一个状态是否只有两个可能值。条件表达式看起来一模一样,status 的类型是 'ready' | 'error' 时,可以用对象把两个状态都列出来。类型多了一个 'pending' 时,原来的三元表达式仍然合理。单测要用同一段条件表达式覆盖这两种结果。
这条规则的类型用例单跑能通过,但全套并行时超过了 5 秒。同一批里还有一个超时的用例,它要区分数组的数值求和、字符串拼接和对象自定义的 reduce 方法。两个用例都很短,耗时主要发生在给这段代码准备 TypeScript 项目的阶段。
规则需要查到表达式的实际类型
ESLint 遍历语法树时可以看到条件表达式和标识符。如果规则想知道 status 能取哪些值,就要向 TypeScript 的类型检查器查询。Program 是 TypeScript 对一组源文件及其编译选项的表示。它也包含通过引用和导入加载的声明,以及配置选择的标准库。通过 Program 可以取得 TypeChecker,再查询指定节点的类型。这两个对象的用法见 TypeScript Compiler API 的类型检查器示例。
@typescript-eslint/parser 提供给 ESLint 可遍历的语法树。在启用类型信息时,parser services 还会提供 Program,并把 ESLint 节点映射回 TypeScript 节点。Program 可以由 projectService 根据项目配置建立,也可以由测试事先创建后通过 parserOptions.programs 传入。两条路径都能让规则向真实的类型检查器提问,接口见 programs 文档。
一段测试代码也可能加载整个类型环境
原来的单测把内联代码交给项目服务,并通过 allowDefaultProject 允许这些虚拟文件使用默认项目。上游的 RuleTester 指南也使用这个选项来演示内联用例。它让尚未被 tsconfig.json 纳入的少量文件获得类型信息,每个通过这条路径取得类型信息的文件都可能带来额外开销。适用场景和限制见 allowDefaultProject 选项说明。
我用同一个只声明 number[] 的虚拟文件,分别跑了原来的配置和自建的 Program。以下是用 TypeScript 6.0.3、@typescript-eslint/parser 8.72.1 测到的 program.getSourceFiles() 结果。
| Program 的来源 | 加载的源文件 | 其中属于 @types/node 的文件 |
|---|---|---|
| 项目服务的默认项目 | 188 | 83 |
| 只加入该用例和基础标准库 | 4 | 0 |
两次查询都得到了 number[]。这个用例只需要标准库里的数组声明。缩小 Program 后,原先超时的两个用例分别耗时约 0.1 秒,全套测试也在默认并行度下通过。
测试自己提供 Program 时,文件名和源码要对齐
我把创建 Program 的部分提成一个测试工具,接收文件名到源码的映射。它用 ts.createCompilerHost() 建立宿主,遇到测试文件时返回内存里的源码,读取标准库时继续走 TypeScript 默认的文件读取。最后把用例文件名作为根文件传给 ts.createProgram()。
编译选项可以从用例的类型需求倒推。这里用 lib.es5.d.ts 提供数组等基础类型,用 types: [] 关闭自动加载的 @types 包。多个独立用例都声明了名为 status 的变量,所以我用 moduleDetection: ts.ModuleDetectionKind.Force 隔离它们的顶层声明。如果测试关心的是脚本全局作用域或声明合并,就应该显式构造那个环境。
下面是接入 ESLint RuleTester 的部分。小型 Program 的工具和规则都由测试文件导入。
const filename = 'binary-status.ts';
const code = "declare const status: 'ready' | 'error'; const label = status === 'ready' ? 'Ready' : 'Error';";
const program = createTypeScriptTestProgram({ [filename]: code });
const tester = new RuleTester({
languageOptions: {
parser: tsParser,
parserOptions: { programs: [program] },
},
});
tester.run('ts-prefer-keyed-object-map', rule, {
invalid: [{ code, errors: [{ messageId: 'preferTypedBinaryMap' }], filename }],
valid: [],
});
Program 里的源文件和 RuleTester 的 filename 必须对应到同一路径,code 也要来自同一份输入。否则 parser 查到的可能是另一份文本的节点,或者根本找不到这个文件。实际用例还加入了三值联合类型来验证放过条件。几个互相独立的片段可以共用一个 Program,各自用唯一文件名。规则带自动修复时,验证修复后的文本也要核对类型信息来自哪一份源码。
用真实项目 fixture 验证接入行为
有些用例的输入就是一个项目。例如规则要追踪另一个文件导出的类型、识别路径别名、读到合并后的声明,或验证 Vue、Astro 脚本能否接上正确的 parser。此时用实际文件和独立的 tsconfig.json 准备 fixture,再通过 projectService 跑测试,可以覆盖项目发现和模块解析。上游也把规则测试的根目录指向专门的 fixture,并默认使用项目服务,具体见 typescript-eslint v8.72.1 的测试入口。
把这两类测试都接在同一个 pnpm test 后面即可。内联类型单测复用小型 Program,项目接入的测试保留真实 fixture。遇到测试并行超时,先分别跑单个用例和整套测试,再对比 getSourceFiles() 列出的文件。这样可以看出该缩小类型环境,还是继续查规则本身的执行时间。