跳到正文

用小型 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 文档。

内联测试与项目 fixture 通过不同方式建立 Program,最后都由 parser services 把类型信息提供给规则

一段测试代码也可能加载整个类型环境

原来的单测把内联代码交给项目服务,并通过 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() 列出的文件。这样可以看出该缩小类型环境,还是继续查规则本身的执行时间。