如何正确引用外部JSON文件配置Cypress的testrail参数？

背景 #

我们已在Cypress解决方案中集成cypress-testrail，用于向「可信数据源」上报测试结果。当前存在多TestRail项目的情况，本地启动Cypress前需更新projectId变量；由于尚未进入CI/CD阶段，需降低本地测试人员修改文件的操作门槛。

当前尝试与问题 #

我希望用testrail.json存储各类运行配置项，于是将cypress.env.json中原本可用的testrail配置段移至该文件，并尝试通过$ref引用：

cypress.env.json 内容 #

{
  "testrail": {
    "$ref": "./cypress/support/testrail.json"
  }
}

testrail.json 内容 #

{
  "testrail": {
    "domain": "redacted",
    "username": "redacted",
    "password": "redacted",
    "projectId": "redacted",
    "runName": "redacted",
    "closeRun": false,
    "screenshots": true
  }
}

但系统返回「not configured」提示，想知道要实现配置拆分并正常工作，遗漏了什么？

核心原因与解决方法 #

问题本质是Cypress原生不支持JSON Schema的$ref语法，无法自动解析外部JSON引用。以下是三种可行的实现方案：

方案1：在Cypress配置文件中手动导入 #

修改cypress.config.js（或cypress.config.ts），通过Node.js API读取并合并外部配置：

const fs = require('fs');
const path = require('path');
const { defineConfig } = require('cypress');

// 读取testrail配置文件
const testrailConfig = JSON.parse(
  fs.readFileSync(path.resolve(__dirname, './cypress/support/testrail.json'), 'utf8')
);

module.exports = defineConfig({
  env: {
    // 将配置注入到Cypress环境变量
    testrail: testrailConfig.testrail
  }
});

此方法无需修改cypress.env.json，Cypress启动时会自动加载外部配置。

方案2：调整JSON结构后直接引用 #

将testrail.json的外层嵌套去掉，直接保留配置项：

{
  "domain": "redacted",
  "username": "redacted",
  "password": "redacted",
  "projectId": "redacted",
  "runName": "redacted",
  "closeRun": false,
  "screenshots": true
}

然后在cypress.env.json中直接指定文件路径（Cypress v10+支持此特性）：

{
  "testrail": "./cypress/support/testrail.json"
}

Cypress会自动解析该路径下的JSON文件并加载配置。

方案3：用启动脚本注入配置 #

创建一个启动脚本load-testrail-config.js：

const fs = require('fs');
const path = require('path');
const { execSync } = require('child_process');

// 读取配置并注入环境变量
const testrailConfig = JSON.parse(
  fs.readFileSync(path.resolve(__dirname, './cypress/support/testrail.json'), 'utf8')
);
process.env.CYPRESS_testrail = JSON.stringify(testrailConfig.testrail);

// 启动Cypress
execSync('npx cypress open', { stdio: 'inherit' });

修改package.json的启动脚本：

{
  "scripts": {
    "cypress:open": "node load-testrail-config.js"
  }
}

测试人员只需运行npm run cypress:open即可自动加载配置。

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