Cypress应用

仅限端到端测试

Cypress.require

Cypress.require 允许在 cy.origin() 回调函数中使用依赖项。它用于引入模块，例如 npm 包和其他本地文件。

其功能与在浏览器目标代码中使用 CommonJS require() 相同。

语法

caution

在 cy.origin() 回调中使用 Cypress.require() 需要在 Cypress 配置中启用 experimentalOriginDependencies 选项。

Cypress.require('moduleNameOrPath')

用法

正确用法

cy.origin('cypress.io', () => {
  const _ = Cypress.require('lodash')
  const utils = Cypress.require('./utils')

  // ... 使用 lodash 和 utils ...
})

错误用法

// `Cypress.require()` 不能在 `cy.origin()` 回调外使用。
// 应改用 CommonJS `require()`
const _ = Cypress.require('lodash')

cy.origin('cypress.io', async () => {
  // `require()` 和 `import()` 不能在 `cy.origin()` 回调内使用。
  // 应改用 `Cypress.require()`
  const _ = require('lodash')
  const utils = await import('./utils')
})

// `Cypress.require` 必须传入静态字符串；动态值无法正确导入。
cy.origin('cypress.io', { args: { lodash: 'lodash' } }, ({ lodash }) => {
  const _ = Cypress.require(lodash)
})

更多用法示例请参阅 cy.origin() 依赖项 / 共享代码。

TypeScript

有几种方法可以推断所需依赖项的类型。

类型断言

cy.origin('cypress.io', async () => {
  const _ = Cypress.require('lodash') as typeof import('lodash')

  // lodash 方法具有正确的类型
  _.map([1, 2, 3], (num: number) => {
    // ...
  })
})

泛型

import type { LoDashStatic } from 'lodash'

cy.origin('cypress.io', async () => {
  const _ = Cypress.require < LoDashStatic > 'lodash'

  // lodash 方法具有正确的类型
  _.map([1, 2, 3], (num: number) => {
    // ...
  })
})

限制 / 要求

• Cypress.require 仅在 cy.origin() 回调函数内调用时有效。在其他地方使用会报错。
• 仅支持以下文件扩展名的依赖项（直接或间接引入）：
  • .js
  • .jsx
  • .ts
  • .tsx
  • .mjs
  • .json
  • .coffee
• Cypress.require('dependency-name') 必须在一行中作为连续字符串，且依赖项不能动态定义：

// ✅ 正确
Cypress.require('lodash')

// ❌ 错误
const { require } = Cypress
require('lodash')

// ❌ 错误
Cypress
.require('lodash')

// ❌ 错误
Cypress . require('lodash')

// ❌ 错误
Cypress.require(
  'lodash'
)

// ❌ 错误
const lodashPkgName = 'lodash'
Cypress.require(lodashPkgName)

为什么不用 require 或 import？

Cypress 在浏览器中运行测试代码，因此任何依赖项都必须在运行前与测试代码一起打包。对于大多数测试代码，这是通过 预处理器 完成的。然而，由于 cy.origin() 的工作方式，传递给它的回调会从其定义的测试代码中提取出来，并在不同的上下文中运行。这也使其与测试代码包中包含的任何依赖项分离。

为了解决这个问题，我们在运行时将所有 Cypress.require 实例替换为 require，并仅将回调及其所需的任何依赖项打包。

在测试代码中使用 Cypress.require 而不是 require 或 import 可以防止回调所需的依赖项与其余测试代码一起打包。我们无法将这些依赖项与回调一起带到其运行的地方，因此在原始预处理中将其打包会浪费执行时间和内存。只有在预处理回调本身时，才会将依赖项与需要它们的代码一起打包。

此外，我们之前尝试过允许使用 require 和 import 的解决方案，但发现它不仅会影响使用它们的规范文件（在 cy.origin() 回调内），甚至会影响不使用它们的规范文件。该解决方案还依赖于预处理器，并且仅适用于 webpack 预处理器。使用 Cypress.require 则不依赖于预处理器。

历史

版本	变更
12.6.0	添加 Cypress.require 并移除对 CommonJS require() 和 ES 模块 import() 的支持
10.11.0	移除 Cypress.require，改用 CommonJS require() 和 ES 模块 import()
10.7.0	添加 Cypress.require

另请参阅

• cy.origin()