Cypress - JSON 配置文件

Cypress - 使用 `cypress.config.js` 进行现代配置

Cypress 配置定义了适用于项目内所有测试的全局设置。在现代 Cypress（版本 10 及更高版本）中，这些配置主要通过项目根目录下的 cypress.config.js 或 cypress.config.ts 文件进行管理。这取代了旧的 cypress.json 文件。

当你打开 Cypress 时，Test Runner 的“Settings”（设置）选项卡将显示已解析的配置。在“Project Settings”（项目设置）下（或在旧版 Test Runner 视图中展开“Configuration”），你可以检查所有有效的配置值，包括默认值和你覆盖的值。

这包括关键设置，例如默认超时时间（如 defaultCommandTimeout、pageLoadTimeout）、cy.visit() 和 cy.request() 的 baseUrl、环境变量、文件夹路径等。理解这些设置是构建稳定高效测试环境的关键。

例如，你会清晰地看到 baseUrl、defaultCommandTimeout、fixturesFolder、supportFile 等的路径，所有值都清楚地列出。这种透明性有助于调试配置问题。

覆盖默认配置值

要覆盖 Cypress 的默认配置或设置项目特定配置，你可以在 cypress.config.js（或 .ts）文件中定义它们。此文件导出一个配置对象。

在 `cypress.config.js` 中的实现

以下是如何在 cypress.config.js 中设置 baseUrl 和自定义的 defaultCommandTimeout：

// cypress.config.js
const { defineConfig } = require('cypress');

module.exports = defineConfig({
  defaultCommandTimeout: 5000, // Sets default command timeout to 5 seconds // 设置默认命令超时为 5 秒
  e2e: {
    baseUrl: 'https://www.yourapp.com',
    setupNodeEvents(on, config) {
      // Implement node event listeners here, if any
      // 在这里实现 Node 事件监听器（如果有）
      // This is a good place for tasks like report generation or pre-processing
      // 这是处理报告生成或预处理等任务的好地方
    },
    // specPattern: 'cypress/e2e/**/*.cy.{js,jsx,ts,tsx}' // Default spec pattern // 默认的测试文件模式
  },
});

在此示例中，baseUrl 被设置为 'https://www.yourapp.com' 用于端到端（e2e）测试，并且 defaultCommandTimeout 被全局设置为 5000ms。保存此文件并重新运行 Cypress 后，这些更改将反映在 Test Runner 的配置显示中。

如果你正在使用带有 JSDoc 的 JavaScript 或 TypeScript，使用 defineConfig 可以提供自动补全和类型检查功能，这对于大型项目强烈推荐。

对测试的影响：使用 `baseUrl`

配置了 baseUrl 后，你的测试脚本将更简洁：

describe('My Application Test', () => {
  it('Visits the home page', () => {
    // Cypress automatically prepends the baseUrl
    // Cypress 会自动预置 baseUrl
    cy.visit('/'); // Navigates to https://www.yourapp.com/ // 导航到 https://www.yourapp.com/
    cy.contains('Welcome').should('be.visible');
  });
});

执行结果：

测试日志将显示 cy.visit('/') 成功导航到了 baseUrl 指定的完整 URL。此设置适用于所有测试，由于基础 URL 是集中管理的，因此它们更易于维护。

动态覆盖配置

你可以在不同级别覆盖配置值，从而提供灵活性：

特定测试配置： 在测试文件内使用 Cypress.config('key', 'value') 可以更改后续命令在当前测试或测试套件中的配置。这对于全局设置不太常用，但可能在某些情况下有用。
特定命令选项： 许多 Cypress 命令接受一个选项对象，该对象可以覆盖特定配置，例如仅针对该命令设置 timeout。这是进行局部覆盖的首选方式。

例如，要增加特定 cy.get() 命令的超时时间：

// Override timeout for this specific command
// 覆盖此特定命令的超时时间
cy.get('.very-slow-element', { timeout: 10000 }).should('be.visible');

// Or, for a section of a test (less common for defaultCommandTimeout):
// 或者，针对测试的一部分（对于 defaultCommandTimeout 较少见）：
// Cypress.config('defaultCommandTimeout', 10000); // All subsequent commands use 10s // 所有后续命令使用 10 秒超时
// cy.get('.another-element').click();
// Cypress.config('defaultCommandTimeout', 5000); // Reset if needed // 如有需要，重置回 5 秒

配置优先级：特定命令选项（例如 { timeout: 10000 }）具有最高优先级，其次是通过 Cypress.config() 进行的动态更改，然后是 cypress.config.js 中的值，最后是 Cypress 的内部默认值。

通过 CLI 禁用配置文件加载

你可以使用命令行标志来阻止 Cypress 加载你的 cypress.config.js 文件。这对于调试或使用纯 Cypress 默认设置运行测试非常有用。

假设你的 cypress.config.js 设置了 defaultCommandTimeout: 10000（10 秒）。

// cypress.config.js example content for this scenario
// 此场景下的 cypress.config.js 示例内容
const { defineConfig } = require('cypress');

module.exports = defineConfig({
  defaultCommandTimeout: 10000,
  e2e: {
    // other e2e configurations
    // 其他 e2e 配置
  }
});

要运行 Cypress 而不加载此自定义配置：

npx cypress open --config-file false

运行此命令后，Test Runner 中的“Settings”（设置）选项卡将显示 configFile 为 false。因此，defaultCommandTimeout 将恢复为 Cypress 的内部默认值（例如 4000ms），而不是你的（现已被忽略的）配置文件中设置的 10000ms。

你还可以使用 --config 标志通过 CLI 覆盖特定的配置值，例如 npx cypress run --config viewportWidth=1280,viewportHeight=720。更多详细信息，请在官方文档中搜索“Cypress command line options”。