Cypress应用

实验性功能

如果您想尝试Cypress正在开发的功能，可以使用下面描述的Cypress配置选项为您的项目启用特定的实验性功能。

caution

⚠️ 实验性功能可能会变更或最终被移除，而不会成为核心产品功能。我们推出实验功能的主要目的是在开发过程中收集真实世界的反馈。更多信息请参阅所有Cypress发布阶段的文档。

配置

您可以通过以下Cypress配置选项来启用或禁用实验功能。关于如何向Cypress传递配置，请参阅我们的配置指南。

选项	默认值	描述
experimentalCspAllowList	false	表示在测试运行期间允许的Content-Security-Policy指令。更多信息请参阅Content-Security-Policy。
experimentalFetchPolyfill	false	自动用Cypress可以监视和存根的polyfill替换window.fetch。注意：experimentalFetchPolyfill已在Cypress 6.0.0中弃用，并将在未来版本中移除。建议使用cy.intercept()来拦截fetch请求。
experimentalInteractiveRunEvents	false	允许在交互模式下监听before:run、after:run、before:spec和after:spec事件，这些事件在setupNodeEvents函数中触发。
experimentalMemoryManagement	false	启用基于Chromium浏览器改进的内存管理支持。
experimentalModifyObstructiveThirdPartyCode	false	是否在第三方.js或.html文件中搜索并替换阻碍性代码。注意：设置此标志会移除子资源完整性(SRI)。
experimentalSourceRewriting	false	启用基于AST的JS/HTML重写。这可能会修复现有基于正则表达式的JS/HTML替换算法导致的问题。详情请参见#5273。
experimentalWebKitSupport	false	启用对在WebKit中运行测试的实验性支持。设置后，将检测并启用playwright-webkit的安装。更多信息请参阅启动浏览器。
retries.experimentalStrategy	N/A	根据您的"flake容忍度"应用测试重试策略；选项为detect-flake-but-always-fail或detect-flake-and-pass-on-threshold。详情请参阅实验性重试。
retries.experimentalOptions	N/A	设置重试策略特定的选项，如maxRetries、passesRequired和stopIfAnyPassed。详情请参阅实验性重试。

实验性CSP允许列表

默认情况下，Cypress会在响应发送到浏览器之前剥离所有CSP头信息(Content-Security-Policy和Content-Security-Policy-Report-Only)。experimentalCspAllowList选项允许更精细地控制哪些CSP指令从CSP响应头中被剥离，从而让您可以在启用CSP的情况下测试应用程序。此选项的有效值为false(默认)、true或CSP指令名称数组。

值	示例
false (默认)	experimentalCspAllowList=false
true	experimentalCspAllowList=true
<CspDirectives>[]	experimentalCspAllowList=["default-src","script-src"]

剥离所有CSP头信息

值experimentalCspAllowList=false(默认)将在响应发送到浏览器之前移除所有CSP头信息。如果您的应用程序测试不依赖CSP，应使用此选项。

剥离最小CSP指令

如果您需要在启用CSP的情况下测试应用程序，设置experimentalCspAllowList选项将允许所有CSP头信息发送到浏览器，除了那些可能阻止Cypress正常运行的指令。

以下CSP指令将始终被剥离：

剥离的指令	可允许	原因
frame-ancestors	否	阻止Cypress将测试应用程序加载到iframe中。
navigate-to	否	影响Cypress导航到不同URL的能力。
require-trusted-types-for	否	可能阻止Cypress重写DOM。
sandbox	否	可能限制对脚本和iframe功能的访问。
trusted-types	否	可能导致Cypress注入被标记为不可信。

当experimentalCspAllowList=true时，除了上述指令外，以下指令也会被剥离，但可以配置为允许发送到浏览器：

剥离的指令	可允许	原因
child-src	是	结合其他Cypress选项可能阻止iframe加载。
default-src	是	有条件地阻止Cypress加载和运行脚本。
frame-src	是	结合其他Cypress选项可能阻止iframe加载。
form-action	是	可能阻止Cypress监控表单事件。
script-src	是	有条件地阻止Cypress加载和运行脚本。
script-src-elem	是	有条件地阻止Cypress加载和运行脚本。

允许特定CSP指令

将experimentalCspAllowList选项设置为上述标记为"可允许"的指令名称数组。这将允许指定的CSP指令发送到浏览器。

以下配置将允许default-src、script-src和script-src-elem指令发送到浏览器：

cypress.config.js 文件

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  experimentalCspAllowList: ['default-src', 'script-src', 'script-src-elem'],
})

cypress.config.ts 文件

import { defineConfig } from 'cypress'

export default defineConfig({
  experimentalCspAllowList: ['default-src', 'script-src', 'script-src-elem'],
})

caution

定义experimentalCspAllowList可能导致Cypress无法对您的应用程序运行测试。如果遇到问题，请减少允许列表中指定的指令以识别导致问题的指令。

已知问题：当使用某些包含哈希算法值的指令与modifyObstructiveCode和/或experimentalSourceRewriting选项时，可能会导致原始哈希指令值与修改后的HTML或JS值不匹配。

实验性Flake检测功能

实验性测试重试

测试重试是Cypress的一项Flake检测功能，允许您重新尝试任何最初失败的测试。失败可能不是"真正的"失败，即flaky。确定这一点的唯一方法是重试测试。

通常，测试重试在第一次通过尝试时停止。任何flaky测试的最终测试结果始终为"通过"，无论之前有多少次尝试失败。以下实验性重试设置让您对重试过程有更多控制。

有两种重试策略：

• detect-flake-and-pass-on-threshold
• detect-flake-but-always-fail

detect-flake-and-pass-on-threshold策略最像当前的重试实现，失败的测试仍有机会通过，但仍检测flake。但这个新的实验性策略还允许您设置通过尝试的阈值以实现通过的最终结果。如果您希望确保flaky测试与失败测试受到同等重视，您会更倾向于使用detect-flake-but-always-fail策略，它确保每个flaky测试仍被标记为失败。

experimentalStrategy: 'detect-flake-and-pass-on-threshold'

在重试中设置experimentalStrategy: 'detect-flake-and-pass-on-threshold'将让您能够设置需要多少次通过尝试才能使测试结果为通过。此策略必须设置两个experimentalOptions：

• maxRetries设置第一次尝试失败后可以发生的最大重试次数
• passesRequired设置最终测试结果为通过所需的通过尝试次数。不能大于maxRetries。
  • passesRequired还决定了重试是否会在达到maxRetries之前停止；如果到目前为止的通过尝试次数满足passesRequired条件，或者如果失败尝试次数超过maxRetries和passesRequired之间的差值（当无法实现通过结果时）。

cypress.config.js 文件

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  retries: {
    experimentalStrategy: 'detect-flake-and-pass-on-threshold',
    experimentalOptions: {
      maxRetries: 2,
      passesRequired: 2,
    },

    // 使用实验性重试时，还必须显式设置openMode和runMode为true或false
    openMode: true,
    runMode: true,
  },
})

cypress.config.ts 文件

import { defineConfig } from 'cypress'

export default defineConfig({
  retries: {
    experimentalStrategy: 'detect-flake-and-pass-on-threshold',
    experimentalOptions: {
      maxRetries: 2,
      passesRequired: 2,
    },

    // 使用实验性重试时，还必须显式设置openMode和runMode为true或false
    openMode: true,
    runMode: true,
  },
})

上述配置的结果示例：

场景1：

• 尝试1: 失败
• 尝试2: 通过
• 尝试3: 失败

重试在尝试3停止，因为maxRetries: 2现已满足，测试的最终结果为失败 且flaky。只有一次尝试通过，但需要两次才能通过。

场景2：

• 尝试1: 失败
• 尝试2: 通过
• 尝试3: 通过

重试再次在尝试3停止，测试为通过 且flaky，因为现在有两次通过尝试。

场景3：

• 尝试1: 失败
• 尝试2: 失败

重试在尝试2停止，测试为失败 ，因为一旦第一次重试失败，就无法再实现通过结果所需的两次通过尝试。也不是flaky，因为没有通过尝试。

experimentalStrategy: 'detect-flake-but-always-fail'

在重试中设置experimentalStrategy: 'detect-flake-but-always-fail'确保任何有失败尝试的测试始终以失败的最终结果结束。此策略必须设置两个experimentalOptions：

• maxRetries设置第一次尝试失败后可以发生的最大重试次数
• stopIfAnyPassed将在有任何通过尝试时在达到maxRetries之前停止重试。
  • stopIfAnyPassed导致重试在检测到任何flake时立即退出（一个在失败后重试的测试只需要通过一次就表现出flaky行为）。但有时可能需要看到更多重试尝试，例如当失败模式也是非确定性的，并且在更多重试中揭示这些不同的错误时，此时stopIfAnyPassed: false可能更可取。

cypress.config.js 文件

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  retries: {
    experimentalStrategy: 'detect-flake-but-always-fail',
    experimentalOptions: {
      maxRetries: 2,
      stopIfAnyPassed: true,
    },

    // 使用实验性重试时，还必须显式设置openMode和runMode为true或false
    openMode: true,
    runMode: true,
  },
})

cypress.config.ts 文件

import { defineConfig } from 'cypress'

export default defineConfig({
  retries: {
    experimentalStrategy: 'detect-flake-but-always-fail',
    experimentalOptions: {
      maxRetries: 2,
      stopIfAnyPassed: true,
    },

    // 使用实验性重试时，还必须显式设置openMode和runMode为true或false
    openMode: true,
    runMode: true,
  },
})

上述配置的结果示例：

场景1：

• 尝试1: 失败
• 尝试2: 失败
• 尝试3: 失败

重试在尝试3停止，因为maxRetries: 2现已满足，测试为失败 ，但也不是flaky。

场景2：

• 尝试1: 失败
• 尝试2: 通过

由于通过尝试，重试在第一次重试时停止。测试为失败 且flaky。如果stopIfAnyPassed为false，则重试会再进行一次。

caution

注意： 实验性重试只能在全局级别配置，不能针对单个测试，而非实验性retries可以针对单个测试配置。如果在使用全局实验性重试时针对特定测试配置重试，则该测试的retries配置将覆盖实验性重试并忽略它。

此外，在使用实验性重试时，不能在全局级别为openMode或runMode设置数值。您可以为每个设置true或false。

info

如果您对实验性重试功能有任何反馈，请使用此表单。

测试类型特定的实验功能

您可以通过在Cypress配置中创建e2e和component对象来为端到端测试或组件测试提供配置选项。

端到端测试

以下实验功能可以在e2e配置对象中指定：

选项	默认值	描述
experimentalStudio	false	通过像最终用户一样与您的应用程序交互，直接生成并保存命令到您的测试套件中。
experimentalRunAllSpecs	false	启用"运行所有Specs"UI功能，允许顺序执行多个specs。
experimentalOriginDependencies	false	在cy.origin中启用Cypress.require支持。

组件测试

以下实验功能可以在component配置对象中指定：

选项	默认值	描述
experimentalSingleTabRunMode	false	在单个标签页中运行所有specs，而不是为每个spec创建新标签页。这可以提高运行模式性能，但在大型测试套件上可能影响spec隔离和可靠性。

历史记录

版本	变更
14.0.0	移除了experimentalJustInTimeCompile和experimentalSkipDomainInjection并使其成为默认行为。
13.14.0	添加了通过experimentalJustInTimeCompile配置组件测试的实验性即时(JIT)编译支持。
13.4.0	添加了通过retries.experimentalStrategy和retries.experimentalOptions配置实验性Flake检测策略的支持。
12.6.0	移除了require/import并为experimentalOriginDependencies添加了Cypress.require。
12.4.0	添加了experimentalSkipDomainInjection和experimentalMemoryManagement。
12.0.0	移除了experimentalSessionAndOrigin并使其成为默认行为。添加了experimentalOriginDependencies。
11.2.0	添加了experimentalRunAllSpecs。
10.8.0	添加了experimentalWebKitSupport。
10.6.0	添加了对experimentalSingleTabRunMode的支持。
10.4.0	添加了对experimentalModifyObstructiveThirdPartyCode的支持。
9.6.0	添加了对experimentalSessionAndOrigin的支持并移除了experimentalSessionSupport。
8.2.0	添加了对experimentalSessionSupport的支持。
7.1.0	添加了对experimentalInteractiveRunEvents的支持。
7.0.0	移除了experimentalComponentTesting并使其成为默认行为。
6.7.0	移除了experimentalRunEvents并使其成为默认行为。
6.3.0	添加了对experimentalStudio的支持。
6.2.0	添加了对experimentalRunEvents的支持。
6.0.0	移除了experimentalNetworkStubbing并在使用cy.intercept()时使其成为默认行为。
6.0.0	弃用了experimentalFetchPolyfill。
5.2.0	移除了experimentalShadowDomSupport并使其成为默认行为。
5.1.0	添加了对experimentalNetworkStubbing的支持。
5.0.0	移除了experimentalGetCookiesSameSite并使其成为默认行为。
4.9.0	添加了对experimentalFetchPolyfill的支持。
4.8.0	添加了对experimentalShadowDomSupport的支持。
4.6.0	添加了对experimentalSourceRewriting的支持。
4.5.0	添加了对experimentalComponentTesting的支持。
4.3.0	添加了对experimentalGetCookiesSameSite的支持。