Skip to main content
Cypress应用

预处理器API

预处理器是负责为浏览器准备 支持文件 或 测试规范文件 的插件。

预处理器可以将文件从其他语言（如CoffeeScript或ClojureScript）或更新版本的JavaScript（如ES2017）转译。

预处理器通常还会监视源文件的更改，重新处理它们，然后通知Cypress重新运行测试。

示例​

我们创建了三个预处理器作为示例供您参考。这些是完全可用的预处理器。

代码中包含了解释如何使用预处理器API的注释。

默认设置​

默认情况下，Cypress已预装了webpack预处理器。

webpack预处理器支持：

  • 通过Babel处理ES2015和JSX
  • TypeScript
  • CoffeeScript 1.x.x
  • 文件监视和缓存
info

您是否想要更改webpack的默认选项？

如果您的项目中已经使用了webpack，可以传入您的webpack配置， 如这里所示。

如果您的项目中没有使用webpack，或者希望保留大部分默认选项，您可以 修改默认选项。 编辑选项允许您执行以下操作：

  • 添加自己的Babel插件
  • 修改TypeScript编译选项
  • 添加对CoffeeScript 2.x.x的支持

使用方法​

caution

⚠️ 这段代码属于 setupNodeEvents 函数的一部分， 因此会在 Node 环境中执行。你不能在此函数中调用 Cypress 或 cy 命令， 但可以直接访问文件系统和操作系统的其他部分。

要使用预处理器，您应该在 setupNodeEvents 函数中绑定到file:preprocessor事件：

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('file:preprocessor', (file) => {
        // ...
      })
    },
  },
})

回调函数应返回以下之一：​

  • 一个promise*，最终解析为构建文件**的路径。
  • 一个promise*，最终拒绝并返回处理过程中发生的错误。
note

* promise应仅在文件完成写入磁盘后解析。promise的解析是一个信号，表示文件已准备好提供给浏览器。

note

** 构建文件是由预处理器创建的文件，最终将提供给浏览器。

note

例如，如果源文件是spec.coffee，预处理器应：

  1. 将CoffeeScript编译为JavaScript spec.js
  2. 将该JavaScript文件写入磁盘（例如：/Users/foo/tmp/spec.js）
  3. 使用该文件的绝对路径解析：/Users/foo/tmp/spec.js
caution

此回调函数可以并且_将会_被多次调用，传入相同的filePath。

每当浏览器请求文件时，都会调用此回调函数。这在每次运行测试时都会发生。

确保不要在每次调用时启动新的监视器。相反，应缓存监视器，并在后续调用时返回一个promise，该promise在文件的最新版本处理完成后解析。

文件对象​

传递给回调函数的file对象具有以下属性：

属性描述
filePath源文件的完整路径。
outputPath建议的预处理文件保存到磁盘的路径。这是源文件的唯一路径。预处理器可以选择将文件写入其他位置，但Cypress自动提供此值作为方便的默认值。
shouldWatch一个布尔值，指示预处理器是否应监视文件更改。

文件事件​

传递给回调函数的file对象是一个 事件发射器。

接收'close'事件​

当运行的测试规范、项目或浏览器在运行测试时关闭时，将发出close事件。预处理器应在此函数中执行任何必要的清理，例如在监视时关闭监视器。

// 示例
const watcher = fs.watch(filePath /* ... */)

file.on('close', () => {
  watcher.close()
})

发送'rerun'事件​

如果监视文件更改，请在文件处理完成后发出rerun，以通知Cypress重新运行测试。

// 示例
fs.watch(filePath, () => {
  file.emit('rerun')
})

源映射​

Cypress 利用源映射(source map)来增强错误显示体验。堆栈跟踪会被转换，从而显示您的源文件而非浏览器加载的生成文件。这同时支持显示代码框架(code frame)。若没有内联源映射(inline source map)，您将无法看到代码框架。

默认情况下，Cypress会在测试规范文件(spec file)中包含内联源映射，因此您能获得最佳的错误显示体验。如果您修改了预处理器，请确保启用内联源映射以获得相同体验。具体示例如下：

如果在自定义预处理器中使用TypeScript，请确保TypeScript编译器生成了源映射。这可以通过在tsconfig.json中将sourceMap选项设为true来实现。不推荐使用inlineSourceMap选项，因为它无法提供准确的代码框架。请参考我们推荐的tsconfig.json配置。

发布​

将预处理器发布到npm，命名约定为cypress-*-preprocessor（例如cypress-clojurescript-preprocessor）。

使用以下npm关键字：

"keywords": [
  "cypress",
  "cypress-plugin",
  "cypress-preprocessor"
]

欢迎将您发布的插件提交到我们的插件列表。

目录