Stencil构建报Jest Matchers接口错误扩展类型不兼容错误

问题现象 #

构建Stencil组件库开发服务时，转译阶段完成后触发TypeScript校验失败，构建中断进入文件监听状态，抛出的错误日志如下：

stencil-library:dev: > stencil build --dev --watch --serve
stencil-library:dev:
stencil-library:dev: [09:03.6]  @stencil/core
stencil-library:dev: [09:03.8]  v2.16.1 🎻
stencil-library:dev: [09:06.4]  build, stencil-demo, dev mode, started ...
stencil-library:dev: [09:06.4]  transpile started ...
stencil-library:dev: [09:09.8]  transpile finished in 3.37 s
stencil-library:dev: [09:10.1]  build, stencil-demo, dev mode, started ...
stencil-library:dev: [09:10.1]  transpile started ...
stencil-library:dev: [09:13.4]  transpile finished in 3.23 s
stencil-library:dev:
stencil-library:dev: [ ERROR ]  TypeScript: ../../node_modules/@types/jest/index.d.ts:691:15
stencil-library:dev:            Interface 'Matchers<R, T>' incorrectly extends interface
stencil-library:dev:            'TestingLibraryMatchers<(str: string) => any, R>'.The types returned
stencil-library:dev:            by 'toHaveAttribute(...)' are incompatible between these types.Type
stencil-library:dev:            'void' is not assignable to type 'R'.'R' could be instantiated with
stencil-library:dev:            an arbitrary type which could be unrelated to 'void'.
stencil-library:dev:
stencil-library:dev:     L690:  // should be R extends void|Promise<void> but getting dtslint error
stencil-library:dev:     L691:  interface Matchers<R, T = {}> {
stencil-library:dev:     L692:      /**
stencil-library:dev:
stencil-library:dev: [09:13.4]  build failed, watching for changes... in 3.25

报错核心为node_modules中@types/jest类型定义文件的Matchers<R, T>接口扩展TestingLibraryMatchers<(str: string) => any, R>接口时类型不兼容，toHaveAttribute方法返回值类型void无法赋值给泛型参数R。

复现步骤 #

执行以下命令即可复现问题：

npm install
# 启动stencil-library开发服务，默认浏览器访问地址为http://localhost:3333
npm run dev

问题原因 #

这是测试依赖版本不兼容触发的第三方类型冲突：

• 项目同时引入了@types/jest和@testing-library/jest-dom两个测试相关的类型依赖，二者安装的版本号不匹配
• 不兼容版本下，@types/jest定义的Jest匹配器接口Matchers<R, T>在继承@testing-library/jest-dom提供的TestingLibraryMatchers接口时，toHaveAttribute等自定义匹配器的返回值类型定义不一致：旧版@types/jest标注匹配器返回值为void，但新版TestingLibraryMatchers要求返回值兼容泛型参数R，直接触发TS接口继承错误
• Stencil构建时默认会对项目加载的所有TS类型文件做校验，包括node_modules下未被业务代码引用的测试类型文件，因此即使开发模式下没有运行测试，也会被这个第三方类型错误阻断构建流程

解决方案 #

通过以下任意一种方案即可修复：

• 锁定兼容的依赖版本
  将@types/jest降级到和现有@testing-library/jest-dom版本兼容的v27稳定版，执行安装命令：

  npm install -D @types/jest@27.5.2
  

  安装完成后删除node_modules目录和依赖锁文件，重新执行npm install后重启开发服务即可。
• 跳过第三方库类型校验
  在项目根目录的tsconfig.json中开启skipLibCheck配置，跳过node_modules下所有第三方类型文件的校验，该配置不会影响业务代码的类型检查，是这类第三方类型冲突的通用处理方案：

  {
    "compilerOptions": {
      "skipLibCheck": true
      // 其余原有配置保持不变
    }
  }
  

  保存配置后重启开发服务即可生效。
• 全量升级测试相关依赖
  将@stencil/core、jest、@types/jest、@testing-library/jest-dom全部升级到最新稳定版，新版本依赖已经修复了这个类型定义兼容问题，升级后重新安装依赖即可。

内容的提问来源于stack exchange，提问作者Naresh