如何为Cypress各测试入口拆分独立index.d.ts类型声明文件

核心思路 #

利用TypeScript的模块级全局声明、三斜杠指令引用能力，把原来全局合并的Chainable接口拆分到各测试目录下，通过显式引用控制类型生效范围，避免全局加载所有命令类型。

具体操作步骤 #

• 1. 重构目录结构
     删除原cypress/support/index.d.ts中所有业务自定义命令的声明，在每个测试子目录下新建专属类型文件，调整后结构参考：

cypress/
  integration/
    foo/
      my-foo.spec.ts
      commands.d.ts # foo目录测试专属命令类型
    bar/
      my-bar.spec.ts
      commands.d.ts # bar目录测试专属命令类型
    baz/
      my-baz.spec.ts
      commands.d.ts # baz目录测试专属命令类型
  support/
    # 仅保留全局公共类型、公共命令定义，不再放全量业务命令声明

• 2. 编写分目录类型声明
     每个commands.d.ts仅声明当前目录测试会用到的自定义命令，文件末尾必须加空export {}，标记文件为ES模块，避免被TS自动全局加载。
     以cypress/integration/foo/commands.d.ts为例：

/// <reference types="cypress" />

declare global {
  namespace Cypress {
    interface Chainable<Subject = any> {
      foo_doTheThing(): Chainable<any>;
      foo_doTheOtherThing(): Chainable<any>;
    }
  }
}

export {}

bar、baz目录下的类型文件同理，仅保留对应前缀的命令声明即可。跨目录共用的通用命令，类型单独放在support目录下的公共声明文件中，全局生效。

• 3. 调整tsconfig配置
     修改项目根目录tsconfig.json，收窄默认include范围，不要自动递归加载integration下所有文件的类型：

{
  "compilerOptions": {
    "target": "es6",
    "lib": ["es6", "dom"],
    "types": ["cypress", "node"]
  },
  "include": [
    "cypress/support/**/*.ts"
    // 移除原有"cypress/integration/**/*.ts"配置，避免全局加载所有测试目录的类型
  ]
}

• 4. 测试文件显式引入对应类型
     在每个spec测试文件顶部，通过三斜杠路径引用引入当前目录下的专属类型声明即可：

/// <reference path="./commands.d.ts" />

// 测试代码
describe('foo模块测试', () => {
  it('正常流程校验', () => {
    cy.foo_doTheThing() // 可正常获得类型提示
    cy.bar_myFunc() // TS直接抛错：类型“Chainable<any>”上不存在属性“bar_myFunc”，实现类型隔离
  })
})

补充说明 #

• 自定义命令的JS实现逻辑，可以按目录拆分到support下的独立文件中，如果需要进一步隔离运行时加载的代码，可以在对应spec文件中手动import对应命令实现，不用全量在support/index.js中引入
• 如果使用的是Cypress 10+版本，integration目录调整为e2e目录，方案逻辑完全一致，仅需要替换对应路径即可

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