Cypress应用

浏览器启动事件

在 Cypress 启动浏览器之前，您可以通过 setupNodeEvents 函数修改浏览器偏好设置、安装扩展、添加或移除命令行参数，以及调整其他选项。

语法

caution

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

cypress.config.js 文件
cypress.config.ts 文件

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser = {}, launchOptions) => {
        /* ... */
      })
    },
  },
})

import { defineConfig } from 'cypress'

export default defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser = {}, launchOptions) => {
        /* ... */
      })
    },
  },
})

browser (object)

描述正在启动的浏览器对象，包含以下属性：

属性	类型	描述
`name`	`string`	机器友好名称，如 `chrome`、`electron`、`edge` 或 `firefox`。
`family`	`string`	使用的渲染引擎。`chromium` 或 `firefox`。
`channel`	`string`	浏览器发布渠道，如 `stable`、`dev` 或 `canary`。
`displayName`	`string`	人类可读的浏览器显示名称。
`version`	`string`	完整版本号。
`path`	`string`	浏览器在磁盘上的路径。Electron 为空。
`info`	`string`	(可选) 浏览器的额外信息（用于浏览器选择器显示）
`majorVersion`	`number`	浏览器的主版本号。
`isHeadless`	`boolean`	浏览器是否以无头模式运行。
`isHeaded`	`boolean`	浏览器是否以有界面模式运行。

launchOptions (object)

可修改的浏览器启动选项对象，包含以下属性：

属性	类型	描述
`preferences`	`object`	描述浏览器偏好的对象。不同浏览器间有差异。详见修改浏览器偏好设置。
`args`	`string[]`	启动浏览器时作为命令行参数传递的字符串数组。对 Electron 无效。详见修改浏览器启动参数。
`extensions`	`string[]`	包含未打包 WebExtensions 的文件夹路径数组，这些扩展将在浏览器启动前加载。详见添加浏览器扩展。
`env`	`object`	传递给启动浏览器的环境变量对象。详见配置浏览器环境。

使用方式

通过 setupNodeEvents 函数，您可以监听 before:browser:launch 事件并修改 Cypress 启动浏览器的方式（例如修改参数、用户偏好和扩展）。

该事件会提供 browser 对象（包含浏览器信息）和 launchOptions 对象（允许修改浏览器启动方式）。

返回的 launchOptions 对象将成为浏览器的新启动选项。

修改浏览器启动参数

当前支持浏览器的可用参数：

默认打开开发者工具

cypress.config.js 文件
cypress.config.ts 文件

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser = {}, launchOptions) => {
        // `args` 是启动浏览器时将传递的所有参数数组
        console.log(launchOptions.args) // 打印所有当前参数

        if (browser.family === 'chromium' && browser.name !== 'electron') {
          // 自动打开开发者工具
          launchOptions.args.push('--auto-open-devtools-for-tabs')
        }

        if (browser.family === 'firefox') {
          // 自动打开开发者工具
          launchOptions.args.push('-devtools')
        }

        if (browser.name === 'electron') {
          // 自动打开开发者工具
          launchOptions.preferences.devTools = true
        }

        // 返回的内容将成为新的 launchOptions
        return launchOptions
      })
    },
  },
})

import { defineConfig } from 'cypress'

export default defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser = {}, launchOptions) => {
        // `args` 是启动浏览器时将传递的所有参数数组
        console.log(launchOptions.args) // 打印所有当前参数

        if (browser.family === 'chromium' && browser.name !== 'electron') {
          // 自动打开开发者工具
          launchOptions.args.push('--auto-open-devtools-for-tabs')
        }

        if (browser.family === 'firefox') {
          // 自动打开开发者工具
          launchOptions.args.push('-devtools')
        }

        if (browser.name === 'electron') {
          // 自动打开开发者工具
          launchOptions.preferences.devTools = true
        }

        // 返回的内容将成为新的 launchOptions
        return launchOptions
      })
    },
  },
})

添加浏览器扩展

限制：

无头 Chrome 不支持加载扩展。
标准 Chrome 等 Chrome 品牌浏览器 137 及以上版本由于 Chrome 移除了 --load-extension 标志，不再支持通过此 API 加载扩展。建议使用 Chrome for Testing 或 Chromium。参见 Cypress Docker 镜像示例：Chrome for Testing 和 Chromium。
Electron 目前仅支持 Chrome 开发者工具扩展。

cypress.config.js 文件
cypress.config.ts 文件

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser, launchOptions) => {
        // 提供未打包扩展文件夹的绝对路径
        launchOptions.extensions.push('Users/jane/path/to/extension')

        return launchOptions
      })
    },
  },
})

import { defineConfig } from 'cypress'

export default defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser, launchOptions) => {
        // 提供未打包扩展文件夹的绝对路径
        launchOptions.extensions.push('Users/jane/path/to/extension')

        return launchOptions
      })
    },
  },
})

配置浏览器环境

caution

此选项不支持 Electron 目标。

cypress.config.js 文件
cypress.config.ts 文件

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser, launchOptions) => {
        launchOptions.env.CUSTOM_ENV_VALUE = '1'

        return launchOptions
      })
    },
  },
})

import { defineConfig } from 'cypress'

export default defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser, launchOptions) => {
        launchOptions.env.CUSTOM_ENV_VALUE = '1'

        return launchOptions
      })
    },
  },
})

修改浏览器偏好设置

当前支持浏览器的可用偏好设置：

基于 Chromium 的浏览器
Electron
Firefox：在 Firefox 浏览器中访问 about:config URL 查看所有可用偏好设置。

info

如果想完全忽略 Chrome 偏好设置，可以在运行 Cypress 时设置 IGNORE_CHROME_PREFERENCES 环境变量。

cypress.config.js 文件
cypress.config.ts 文件

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser, launchOptions) => {
        if (browser.family === 'chromium' && browser.name !== 'electron') {
          // 在 Chromium 中，偏好设置可以存在于 Local State、Preferences 或 Secure Preferences 中
          // 通过 launchOptions.preferences，可以访问 `localState`、`default` 和 `secureDefault`

          // 例如，在 Preferences 中设置 `somePreference: true`：
          launchOptions.preferences.default['preference'] = true

          return launchOptions
        }

        if (browser.family === 'firefox') {
          // launchOptions.preferences 是偏好名称到值的映射
          launchOptions.preferences['some.preference'] = true

          return launchOptions
        }

        if (browser.name === 'electron') {
          // launchOptions.preferences 是一个 `BrowserWindow` `options` 对象
          launchOptions.preferences.darkTheme = true

          return launchOptions
        }
      })
    },
  },
})

import { defineConfig } from 'cypress'

export default defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser, launchOptions) => {
        if (browser.family === 'chromium' && browser.name !== 'electron') {
          // 在 Chromium 中，偏好设置可以存在于 Local State、Preferences 或 Secure Preferences 中
          // 通过 launchOptions.preferences，可以访问 `localState`、`default` 和 `secureDefault`

          // 例如，在 Preferences 中设置 `somePreference: true`：
          launchOptions.preferences.default['preference'] = true

          return launchOptions
        }

        if (browser.family === 'firefox') {
          // launchOptions.preferences 是偏好名称到值的映射
          launchOptions.preferences['some.preference'] = true

          return launchOptions
        }

        if (browser.name === 'electron') {
          // launchOptions.preferences 是一个 `BrowserWindow` `options` 对象
          launchOptions.preferences.darkTheme = true

          return launchOptions
        }
      })
    },
  },
})

修改 Electron 应用开关

Cypress Launchpad 是一个 Electron 应用程序，其行为（以及内置 Electron 浏览器的行为）可以通过命令行开关进行自定义。支持的开关取决于 Electron 版本，参见 Electron 文档。

您可以使用 ELECTRON_EXTRA_LAUNCH_ARGS 环境变量传递 Electron 特定的启动参数。例如，要禁用 HTTP 浏览器缓存并忽略证书错误，可以像下面这样在运行 Cypress 前设置环境变量：

Linux/OSX

export ELECTRON_EXTRA_LAUNCH_ARGS=--disable-http-cache --lang=es

Windows

set ELECTRON_EXTRA_LAUNCH_ARGS=--disable-http-cache --lang=es

Cypress 已经在内部设置了一些 Electron 命令行开关。参见文件 packages/server/lib/environment.js。目前无法在 Electron 启动后查看所有已设置的开关。

查看所有 Chrome 浏览器开关

如果使用基于 Chromium 的浏览器运行 Cypress 测试，可以通过打开新标签页并输入 chrome://version URL 查看所有当前设置的命令行开关和浏览器版本信息。

示例

设置无头模式下的屏幕尺寸

当浏览器以无头模式运行时，没有物理显示器。您可以像下面这样覆盖默认的 1280x720 屏幕尺寸。这将影响运行期间截取的屏幕截图和视频的大小。

caution

此设置更改屏幕的显示尺寸，不影响 Cypress 配置中设置的 viewportWidth 和 viewportHeight。viewportWidth 和 viewportHeight 仅影响 Cypress 测试运行器中显示的应用程序大小。详情请阅读博客文章生成高分辨率视频和屏幕截图。

cypress.config.js 文件
cypress.config.ts 文件

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser, launchOptions) => {
        if (browser.name === 'chrome' && browser.isHeadless) {
          // 非视网膜屏幕上的全页截图尺寸为 1400x1200
          // 视网膜屏幕上为 2800x2400
          launchOptions.args.push('--window-size=1400,1200')

          // 强制屏幕为非视网膜 (1400x1200 尺寸)
          launchOptions.args.push('--force-device-scale-factor=1')

          // 强制屏幕为视网膜 (2800x2400 尺寸)
          // launchOptions.args.push('--force-device-scale-factor=2')
        }

        if (browser.name === 'electron' && browser.isHeadless) {
          // 全页截图尺寸为 1400x1200
          launchOptions.preferences.width = 1400
          launchOptions.preferences.height = 1200
        }

        if (browser.name === 'firefox' && browser.isHeadless) {
          // 菜单栏会占用屏幕高度
          // 因此全页截图尺寸为 1400x1126
          launchOptions.args.push('--width=1400')
          launchOptions.args.push('--height=1200')
        }

        return launchOptions
      })
    },
  },
})

import { defineConfig } from 'cypress'

export default defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser, launchOptions) => {
        if (browser.name === 'chrome' && browser.isHeadless) {
          // 非视网膜屏幕上的全页截图尺寸为 1400x1200
          // 视网膜屏幕上为 2800x2400
          launchOptions.args.push('--window-size=1400,1200')

          // 强制屏幕为非视网膜 (1400x1200 尺寸)
          launchOptions.args.push('--force-device-scale-factor=1')

          // 强制屏幕为视网膜 (2800x2400 尺寸)
          // launchOptions.args.push('--force-device-scale-factor=2')
        }

        if (browser.name === 'electron' && browser.isHeadless) {
          // 全页截图尺寸为 1400x1200
          launchOptions.preferences.width = 1400
          launchOptions.preferences.height = 1200
        }

        if (browser.name === 'firefox' && browser.isHeadless) {
          // 菜单栏会占用屏幕高度
          // 因此全页截图尺寸为 1400x1126
          launchOptions.args.push('--width=1400')
          launchOptions.args.push('--height=1200')
        }

        return launchOptions
      })
    },
  },
})

覆盖设备像素比

cypress.config.js 文件
cypress.config.ts 文件

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser, launchOptions) => {
        if (browser.name === 'chrome' && browser.isHeadless) {
          // 在 Chrome 无头浏览器运行时强制屏幕表现为视网膜
          // (默认尺寸为 2560x1440)
          launchOptions.args.push('--force-device-scale-factor=2')
        }

        return launchOptions
      })
    },
  },
})

import { defineConfig } from 'cypress'

export default defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser, launchOptions) => {
        if (browser.name === 'chrome' && browser.isHeadless) {
          // 在 Chrome 无头浏览器运行时强制屏幕表现为视网膜
          // (默认尺寸为 2560x1440)
          launchOptions.args.push('--force-device-scale-factor=2')
        }

        return launchOptions
      })
    },
  },
})

以全屏模式启动

cypress.config.js 文件
cypress.config.ts 文件

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser = {}, launchOptions) => {
        if (browser.family === 'chromium' && browser.name !== 'electron') {
          launchOptions.args.push('--start-fullscreen')

          return launchOptions
        }

        if (browser.name === 'electron') {
          launchOptions.preferences.fullscreen = true

          return launchOptions
        }
      })
    },
  },
})

import { defineConfig } from 'cypress'

export default defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser = {}, launchOptions) => {
        if (browser.family === 'chromium' && browser.name !== 'electron') {
          launchOptions.args.push('--start-fullscreen')

          return launchOptions
        }

        if (browser.name === 'electron') {
          launchOptions.preferences.fullscreen = true

          return launchOptions
        }
      })
    },
  },
})

使用假视频测试摄像头功能

默认情况下，Cypress 会传递 Chrome 命令行开关以启用媒体流的假视频。这是为了在没有必要硬件的情况下更好地测试摄像头功能。

但是，您可以通过传递指向视频文件的 Chrome 命令行开关来发送自己的视频文件进行测试。

cypress.config.js 文件
cypress.config.ts 文件

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser = {}, launchOptions) => {
        if (browser.family === 'chromium' && browser.name !== 'electron') {
          // Mac/Linux
          launchOptions.args.push(
            '--use-file-for-fake-video-capture=cypress/fixtures/my-video.y4m'
          )

          // Windows
          // launchOptions.args.push('--use-file-for-fake-video-capture=c:\\path\\to\\video\\my-video.y4m')
        }

        return launchOptions
      })
    },
  },
})

import { defineConfig } from 'cypress'

export default defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser = {}, launchOptions) => {
        if (browser.family === 'chromium' && browser.name !== 'electron') {
          // Mac/Linux
          launchOptions.args.push(
            '--use-file-for-fake-video-capture=cypress/fixtures/my-video.y4m'
          )

          // Windows
          // launchOptions.args.push('--use-file-for-fake-video-capture=c:\\path\\to\\video\\my-video.y4m')
        }

        return launchOptions
      })
    },
  },
})

支持独特的文件下载 MIME 类型

Cypress 支持测试文件下载时的多种 MIME 类型，但如果遇到独特类型，您可以添加支持。

cypress.config.js 文件
cypress.config.ts 文件

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser, options) => {
        // 只有 Firefox 需要列出所有 MIME 类型
        if (browser.family === 'firefox') {
          const existingMimeTypes =
            options.preferences['browser.helperApps.neverAsk.saveToDisk']
          const myMimeType = 'my/mimetype'

          // 防止浏览器下载提示
          options.preferences['browser.helperApps.neverAsk.saveToDisk'] =
            `${existingMimeTypes},${myMimeType}`

          return options
        }
      })
    },
  },
})

import { defineConfig } from 'cypress'

export default defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser, options) => {
        // 只有 Firefox 需要列出所有 MIME 类型
        if (browser.family === 'firefox') {
          const existingMimeTypes =
            options.preferences['browser.helperApps.neverAsk.saveToDisk']
          const myMimeType = 'my/mimetype'

          // 防止浏览器下载提示
          options.preferences['browser.helperApps.neverAsk.saveToDisk'] =
            `${existingMimeTypes},${myMimeType}`

          return options
        }
      })
    },
  },
})

info

查看我们的示例配方，了解如何下载和验证 CSV 和 Excel 文件。

设置 Firefox 标志

如果需要设置特定的 Firefox 标志，如 browser.send_pings，可以通过偏好设置实现：

cypress.config.js 文件
cypress.config.ts 文件

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser = {}, launchOptions) => {
        if (browser.family === 'firefox') {
          launchOptions.preferences['browser.send_pings'] = true
        }

        return launchOptions
      })
    },
  },
})

import { defineConfig } from 'cypress'

export default defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser = {}, launchOptions) => {
        if (browser.family === 'firefox') {
          launchOptions.preferences['browser.send_pings'] = true
        }

        return launchOptions
      })
    },
  },
})

历史记录

版本	变更
4.0.0	新的 `options` 对象取代了 `before:browser:launch` 的第二个参数 `args`
4.0.0	所有基于 Chromium 的浏览器（包括 Electron）的 `family` 属性都设置为 `chromium`。
4.0.0	为浏览器添加了 `channel` 属性。

浏览器启动事件

语法​

使用方式​

修改浏览器启动参数​

默认打开开发者工具​

添加浏览器扩展​

配置浏览器环境​

修改浏览器偏好设置​

修改 Electron 应用开关​

Linux/OSX​

Windows​

查看所有 Chrome 浏览器开关​

示例​

设置无头模式下的屏幕尺寸​

覆盖设备像素比​

以全屏模式启动​

使用假视频测试摄像头功能​

支持独特的文件下载 MIME 类型​

设置 Firefox 标志​

历史记录​

目录

语法

使用方式

修改浏览器启动参数

默认打开开发者工具

添加浏览器扩展

配置浏览器环境

修改浏览器偏好设置

修改 Electron 应用开关

Linux/OSX

Windows

查看所有 Chrome 浏览器开关

示例

设置无头模式下的屏幕尺寸

覆盖设备像素比

以全屏模式启动

使用假视频测试摄像头功能

支持独特的文件下载 MIME 类型

设置 Firefox 标志

历史记录