Cypress应用

命令行

本指南假设您已阅读安装 Cypress 指南并将 Cypress 安装为 npm 模块。安装后，您将能够从 项目根目录 执行本文档中的所有命令。

info

您也可以使用我们的模块 API 将 Cypress 作为 Node 模块引入并运行。

如何运行命令

您可以从 项目根目录 使用取决于您所用包管理器（npm、Yarn 或 pnpm）的命令运行 Cypress。例如，您需要为命令 cypress run 添加前缀，如下所示：

npm
yarn
pnpm

npx cypress run

yarn cypress run

pnpm cypress run

在命令行末尾添加任何所需的选项。例如，如果您想以无头模式运行单个 spec 文件中的测试并将结果记录到 Cypress Cloud，命令应为：

npm
Yarn
pnpm

npx cypress run --record --spec "cypress/e2e/my-spec.cy.js"

yarn cypress run --record --spec "cypress/e2e/my-spec.cy.js"

pnpm cypress run --record --spec "cypress/e2e/my-spec.cy.js"

info

PowerShell

当 cypress run 选项或 cypress open 选项指定了多个以逗号分隔的值时，例如 --config 或 --env 选项，并且您在 Windows 上使用 PowerShell，可能需要用引号包围键/值对，例如：--env "host=api.dev.local,port=4222"。

使用脚本

可以将 Cypress 命令字符串保存为脚本以便重复使用。

假设您经常需要使用 Chrome 浏览器以无头模式运行 Cypress E2E 测试。您可以将相应的命令 cypress run --browser chrome 添加到 package.json 文件中的 scripts 对象，并使用名称 e2e:chrome 来标识它。

{
  "scripts": {
    "e2e:chrome": "cypress run --browser chrome"
  }
}

如下运行脚本 e2e:chrome 将执行您定义的命令：

npm
Yarn
pnpm

npm run e2e:chrome

yarn e2e:chrome

pnpm e2e:chrome

caution

最佳实践

不要将 cypress 用作脚本的确切名称，尤其是当您使用 Yarn 作为包管理器时。在运行 Cypress 二进制文件的命令（例如 yarn cypress verify）时， Yarn 会引用同名的脚本，Cypress CLI 命令可能无法按预期工作。

扩展脚本选项

您不需要为每个命令字符串的变体定义新脚本。您可以使用附加选项扩展脚本。

假设当您使用脚本 e2e:chrome 运行完整测试集时，显示了一个测试规范 cypress/e2e/my-spec.cy.js 中的失败。您已纠正了问题，并希望仅重新运行之前失败的测试规范。

选项 --spec 允许您指定要运行的测试规范，因此您可以在脚本名称 e2e:chrome 之后将其添加到命令中：

npm
Yarn
pnpm

npm run e2e:chrome -- --spec "cypress/e2e/my-spec.cy.js"

yarn e2e:chrome --spec "cypress/e2e/my-spec.cy.js"

pnpm e2e:chrome --spec "cypress/e2e/my-spec.cy.js"

请参阅每个包管理器的文档以获取命令和脚本使用的完整详情：

npm CLI
当从 npm 调用脚本名称后添加 Cypress 选项时，需要使用 -- 字符串传递命令参数（参见 npm-run-script）。
Yarn CLI
pnpm CLI

命令

info

以下命令列表中没有显示运行 cypress 所需的前缀。您需要根据您使用的包管理器在命令行中添加前缀 npx、yarn 或 pnpm。参见如何运行命令。

`cypress run`

运行 Cypress 测试直至完成。默认情况下，cypress run 将以无头模式运行所有测试。

cypress run [options]

选项

选项	描述
`--auto-cancel-after-failures`	覆盖 Cloud 项目级配置，设置自动取消的失败测试阈值或禁用录制到 Cloud 时的自动取消
`--browser`, `-b`	在给定名称的浏览器中运行 Cypress。如果提供了文件系统路径，Cypress 将尝试使用该路径下的浏览器。
`--ci-build-id`	为运行指定唯一标识符以启用分组或并行化。
`--component`	运行组件测试
`--config`, `-c`	指定配置
`--config-file`, `-C`	指定配置文件
`--e2e`	运行端到端测试（默认）
`--env`, `-e`	指定环境变量
`--group`	将录制的测试分组在单个运行下
`--headed`	显示浏览器而不是无头运行
`--headless`	隐藏浏览器而不是显示（`cypress run` 期间默认）
`--help`, `-h`	输出使用信息
`--key`, `-k`	指定您的秘密记录密钥
`--no-exit`	在规范文件运行测试后保持 Cypress 打开
`--no-runner-ui`	隐藏 Cypress Runner UI
`--parallel`	在多台机器上并行运行录制的规范
`--port`,`-p`	覆盖默认端口
`--project`, `-P`	特定项目的路径
`--quiet`, `-q`	减少输出到 `stdout`
`--record`	是否记录测试运行
`--reporter`, `-r`	指定 Mocha 报告器
`--reporter-options`, `-o`	指定 Mocha 报告器选项
`--runner-ui`	显示 Cypress Runner UI。当启用测试回放时，仍希望显示 Cypress Runner UI 以查看截图和视频时很有用
`--spec`, `-s`	指定要运行的规范文件
`--tag`, `-t`	使用一个或多个标签标识运行

`cypress run --auto-cancel-after-failures <autoCancelAfterFailures>`

注意：在 Cypress 12.6.0 及更高版本中可用

"autoCancelAfterFailures" 参数是测试可以失败的次数在运行被取消之前

cypress run --record --key <<your_record_key>> --auto-cancel-after-failures 1

您还可以为值指定 false 以禁用运行的自动取消：

cypress run --record --key <<your_record_key>> --auto-cancel-after-failures false

`cypress run --browser <browser-name-or-path>`

cypress run --browser chrome

"browser" 参数可以设置为 chrome、chromium、edge、electron、 firefox 以启动系统上检测到的浏览器。Cypress 将尝试自动为您找到已安装的浏览器。

要启动非稳定版浏览器，添加冒号和所需的发布渠道。例如，要启动 Chrome Canary，使用 chrome:canary。

您也可以通过提供路径选择浏览器：

cypress run --browser /usr/bin/chromium

遇到浏览器检测问题？查看我们的故障排除指南

`cypress run --ci-build-id <id>`

对于大多数 CI 提供商，此值应自动检测到，除非 Cypress 无法确定，否则无需定义。

通常，这是在您的 CI 提供商中定义为环境变量的，定义一个唯一的 "构建" 或 "运行"。

cypress run --ci-build-id BUILD_NUMBER

仅在提供 --group 或 --parallel 标志时有效。阅读我们的并行化文档以了解更多。

`cypress run --config <config>`

设置配置值。多个值用逗号分隔。此处设置的值会覆盖配置文件中设置的任何值。

cypress run --config pageLoadTimeout=100000,watchForFileChanges=false

对于更复杂的配置对象，您可能需要考虑传递一个 JSON.stringified 对象并用单引号包围。

这里，我们传递组件规范文件的配置。

cypress run --config '{"watchForFileChanges":false,"specPattern":["**/*.cy.js","**/*.cy.ts"]}'

info

真实世界示例

Cypress 真实世界应用(RWA) 使用 --config 标志轻松指定视口大小以进行响应式测试，在本地和专用 CI 作业中。

示例：

npm 脚本以移动视口运行 Cypress。
Circle CI 作业配置用于在移动视口中运行测试套件。

`cypress run --config-file <configuration-file>`

您可以指定一个文件路径，其中设置了 Cypress 配置值。

cypress run --config-file tests/cypress.config.js

`cypress run --env <env>`

设置 Cypress 环境变量。

cypress run --env host=api.dev.local

使用逗号且无空格传递多个变量。数字会自动从字符串转换。

cypress run --env host=api.dev.local,port=4222

将对象作为字符串中的 JSON 传递。

cypress run --env flags='{"feature-a":true,"feature-b":false}'

`cypress run --group <name>`

将录制的测试分组在单个运行下。

cypress run --group develop-env

您可以通过传递不同的名称向同一运行添加多个组。这可以帮助区分不同的规范组。

cypress run --group admin-tests --spec 'cypress/e2e/admin/**/*'

cypress run --group user-tests --spec 'cypress/e2e/user/**/*'

指定 --ci-build-id 也可能是必要的。

阅读更多关于分组的信息。

`cypress run --headed`

默认情况下，Cypress 在 cypress run 期间会以无头模式运行测试。

传递 --headed 将强制显示浏览器。这与您通过 cypress open 运行任何浏览器的方式匹配。

cypress run --headed

`cypress run --no-exit`

为了防止 Cypress 在规范文件中运行测试后退出，使用 --no-exit。

您可以传递 --headed --no-exit 以便在 spec 运行后查看 命令日志 或访问 开发者工具。

cypress run --headed --no-exit

`cypress run --no-runner-ui`

为了防止 Cypress 渲染 Runner UI，使用 --no-runner-ui。

cypress run --no-runner-ui

`cypress run --parallel`

在多台机器上并行运行录制的规范。

cypress run --record --parallel

您可以额外传递 --group 标志，以便将其显示为命名的组。

cypress run --record --parallel --group e2e-staging-specs

阅读我们的并行化文档以了解更多。

`cypress run --port <port>`

cypress run --port 8080

`cypress run --project <project-path>`

要查看实际操作，我们设置了一个示例仓库来演示这一点。

cypress run --project ./some/nested/folder

`cypress run --quiet`

为了减少 Cypress 打印到 stdout 的输出，使用 --quiet。

cypress run --quiet

如果传递了此选项，Cypress 将仅从内置默认 Mocha spec 报告器或任何其他配置的 Mocha 报告器打印输出到 stdout。

`cypress run --record --key <record-key>`

将您的测试结果记录到 Cypress Cloud。对于此选项起作用，您必须首先设置您的项目以记录，确保您的 projectId 在您的 Cypress 配置文件中设置，并将您的 记录密钥 附加到命令中。

cypress run --record --key <record_key>

如果您将 记录密钥 设置为环境变量 CYPRESS_RECORD_KEY，您可以省略 --key 标志。您通常会在持续集成中设置此环境变量。

export CYPRESS_RECORD_KEY=abc-key-123

现在您可以省略 --key 标志。

cypress run --record

有关记录运行的更多信息，请参阅 Cypress Cloud 设置说明。对于关于 Cypress 如何使用您的记录密钥和 projectId 将您的测试结果保存到 Cypress Cloud 的深入解释，请参阅标识部分。

`cypress run --reporter <reporter>`

您可以测试指定特定的 Mocha 报告器。

cypress run --reporter json

您可以使用 --reporter-options <reporter-options> 标志指定报告器选项。

cypress run --reporter junit --reporter-options mochaFile=result.xml,toConsole=true

`cypress run --runner-ui`

为了强制 Cypress 渲染 Runner UI，使用 --runner-ui。

cypress run --runner-ui

当启用测试回放时，您仍希望渲染 Runner UI 以查看截图和视频时很有用。

`cypress run --spec <spec>`

运行测试，指定要运行的单个测试文件而不是所有测试。规范路径应为绝对路径或可以相对于当前工作目录。

cypress run --spec "cypress/e2e/examples/actions.cy.js"

运行与 glob 匹配的文件夹中的测试（注意：强烈建议使用双引号）。

cypress run --spec "cypress/e2e/login/**/*"

运行测试，指定要运行的多个测试文件。

cypress run --spec "cypress/e2e/examples/actions.cy.js,cypress/e2e/examples/files.cy.js"

与 --project 参数结合使用。假设 Cypress 测试位于当前项目的子文件夹 tests/e2e 中：

app/
  node_modules/
  package.json
  tests/
    unit/
    e2e/
      cypress/
        e2e/
          spec.cy.js
      cypress.config.js

如果我们在 app 文件夹中，可以使用以下命令运行规范

cypress run --project tests/e2e --spec ./tests/e2e/cypress/e2e/spec.cy.js

`cypress run --tag <tag>`

向录制的运行添加一个或多个标签。这可以用于帮助在 Cypress Cloud 中显示时区分不同的运行。

cypress run  --record --tag "staging"

为一个运行提供多个标签。

cypress run --record --tag "production,nightly"

Cypress Cloud 将显示与相应运行一起发送的任何标签。

退出代码

当 Cypress 完成运行测试时，它会退出。如果没有失败的测试，则退出代码将为 0。

## 所有测试通过
$ cypress run
...
                                        测试  通过    失败
    ✔  所有规范通过！      00:16       17       17        0

## 在 Mac 或 Linux 上打印退出代码
$ echo $?
0

如果有任何测试失败，则退出代码将匹配失败的测试数量。

## 规范中有两个失败的测试
$ cypress run
...
                                        测试  通过    失败
    ✖  1 个中有 1 个失败 (100%)   00:22       17       14        2

## 在 Mac 或 Linux 上打印退出代码
$ echo $?
2

如果 Cypress 因某些原因无法运行（例如找不到规范文件），则退出代码将为 1。

## 找不到规范文件
$ cypress run --spec not-found.js
...
无法运行，因为找不到规范文件。

我们搜索了匹配此 glob 模式的任何文件：

not-found.js

## 在 Mac 或 Linux 上打印退出代码
$ echo $?
1

`cypress open`

打开 Cypress。

cypress open [options]

选项：

传递给 cypress open 的选项将自动应用于您打开的项目。这些选项在所有项目中持续存在，直到您退出 Cypress。这些选项也会覆盖 Cypress 配置文件中的值。

通过在启动项目时传递 --browser 和 --e2e 或 --component，您可以打开 Cypress 并同时启动浏览器。如果单独传递 --browser 标志，浏览器将在被引导通过项目和/或测试类型选择后自动启动。否则，您将被引导通过选择浏览器、项目和/或测试类型。

选项	描述
`--browser`, `-b`	在给定名称的浏览器中运行 Cypress。如果提供了文件系统路径，Cypress 将尝试使用该路径下的浏览器。
`--component`	以组件测试模式打开
`--config`, `-c`	指定配置
`--config-file`, `-C`	指定配置文件
`--detached`, `-d`	以分离模式打开 Cypress
`--e2e`	以端到端测试模式打开（默认）
`--env`, `-e`	指定环境变量
`--global`	以全局模式打开
`--help`, `-h`	输出使用信息
`--port`, `-p`	覆盖默认端口
`--project`, `-P`	特定项目的路径

`cypress open --browser <browser-path>`

默认情况下，Cypress 会自动找到并允许您使用系统上安装的浏览器。

"browser" 选项允许您指定自定义浏览器的路径以与 Cypress 一起使用：

cypress open --browser /usr/bin/chromium

如果找到，指定的浏览器将被添加到可用浏览器列表中。

目前，仅支持 Chrome 系列（包括新的基于 Chromium 的 Microsoft Edge 和 Brave）和 Firefox 浏览器。

遇到启动浏览器问题？查看我们的故障排除指南

`cypress open --config <config>`

设置配置值。多个值用逗号分隔。此处设置的值会覆盖配置文件中设置的任何值。

cypress open --config pageLoadTimeout=100000,watchForFileChanges=false

对于更复杂的配置对象，您可能需要考虑传递一个 JSON.stringified 对象。

这里，我们传递组件规范文件的配置。

cypress open --config "{\"watchForFileChanges\":false,\"specPattern\":[\"**/*.cy.js\",\"**/*.cy.ts\"]}"

`cypress open --config-file <configuration-file>`

您可以指定一个文件路径，其中设置了 Cypress 配置值。

cypress open --config-file tests/cypress.config.js

`cypress open --env <env>`

设置 Cypress 环境变量。

cypress open --env host=api.dev.local

使用逗号且无空格传递多个变量。数字会自动从字符串转换。

cypress open --env host=api.dev.local,port=4222

将对象作为字符串中的 JSON 传递。

cypress open --env flags='{"feature-a":true,"feature-b":false}'

`cypress open --global`

以全局模式打开 Cypress 很有用，如果您有多个嵌套项目但希望共享 Cypress 的单个全局安装。在这种情况下，您可以将每个嵌套项目添加到全局模式下的 Cypress，从而为您提供一个漂亮的 UI 以在它们之间切换。

cypress open --global

`cypress open --port <port>`

cypress open --port 8080

`cypress open --project <project-path>`

要查看实际操作，我们设置了一个示例仓库来演示这一点。

cypress open --project ./some/nested/folder

`cypress info`

打印有关 Cypress 和当前环境的信息，例如：

Cypress 在机器上检测到的浏览器列表。
控制代理配置的任何环境变量。
以 CYPRESS 前缀开头的任何环境变量（敏感变量如记录密钥被屏蔽以保护安全）。
运行时数据的存储位置。
Cypress 二进制文件的缓存位置。
操作系统信息。
系统内存，包括可用空间。

cypress info
显示 Cypress 信息...

检测到安装了 2 个浏览器：

1. Chrome
  - 名称：chrome
  - 渠道：stable
  - 版本：79.0.3945.130
  - 可执行文件：/path/to/google-chrome
  - 配置文件：/user/profile/folder/for/google-chrome

2. Firefox Nightly
  - 名称：firefox
  - 渠道：nightly
  - 版本：74.0a1
  - 可执行文件：/path/to/firefox

注意：要运行这些浏览器，将 <name>:<channel> 传递给 '--browser' 字段

示例：
- cypress run --browser firefox:nightly
- cypress run --browser chrome

了解更多：https://on.cypress.io/launching-browsers

代理设置：未检测到
环境变量：未检测到

应用程序数据：/path/to/app/data/cypress/cy/development
浏览器配置文件：/path/to/app/data/cypress/cy/development/browsers
二进制缓存：/user/profile/path/.cache/Cypress

Cypress 版本：4.1.0
系统平台：darwin (19.2.0)
系统内存：17.2 GB 可用 670 MB

提示： 设置 DEBUG 环境变量为 cypress:launcher:* 当运行 cypress info 时以排查浏览器检测问题。

`cypress verify`

验证 Cypress 是否正确安装并可执行。

cypress verify
✔  已验证 Cypress！/Users/jane/Library/Caches/Cypress/3.0.0/Cypress.app

要更改默认的 30 秒超时，您可以设置环境变量 CYPRESS_VERIFY_TIMEOUT：

export CYPRESS_VERIFY_TIMEOUT=60000 # 等待 60 秒
cypress verify

请注意，cypress verify 命令作为 cypress open 和 cypress run 命令的一部分执行。CYPRESS_VERIFY_TIMEOUT 环境变量应为这些命令提供，如果您希望修改超时持续时间。

您可以通过将 CYPRESS_SKIP_VERIFY 环境变量设置为 true 来禁用验证。

`cypress version`

打印已安装的 Cypress 二进制版本、Cypress 包版本、用于构建 Cypress 的 Electron 版本以及捆绑的 Node 版本。

在大多数情况下，二进制和包版本将是相同的，但它们可能不同，如果您安装了不同版本的包并且由于某种原因未能安装匹配的二进制版本。

cypress version
Cypress 包版本：12.0.0
Cypress 二进制版本：12.0.0
Electron 版本：21.0.0
捆绑的 Node 版本：16.16.0

您也可以打印每个单独组件的版本号。

cypress version --component package
12.0.0
cypress version --component binary
12.0.0
cypress version --component electron
21.0.0
cypress version --component node
16.16.0

`cypress cache [command]`

用于管理全局 Cypress 缓存的命令。Cypress 缓存适用于您机器上所有安装的 Cypress，无论是全局还是非全局。

`cypress cache path`

打印 Cypress 缓存文件夹的 path。您可以按照这些说明更改 Cypress 缓存的位置。

cypress cache path
/Users/jane/Library/Caches/Cypress

`cypress cache list`

打印所有已安装的 Cypress 版本。输出将是一个表格，其中包含缓存的版本和用户上次使用二进制文件的时间，根据文件的访问时间确定。

cypress cache list
┌─────────┬──────────────┐
│ 版本   │ 上次使用    │
├─────────┼──────────────┤
│ 3.0.0   │ 3 个月前    │
├─────────┼──────────────┤
│ 3.0.1   │ 5 天前      │
└─────────┴──────────────┘

您可以通过向命令添加 --size 参数来计算每个 Cypress 版本文件夹的大小。请注意，计算磁盘大小可能会很慢。

cypress cache list --size
┌─────────┬──────────────┬─────────┐
│ 版本   │ 上次使用    │ 大小    │
├─────────┼──────────────┼─────────┤
│ 5.0.0   │ 3 个月前    │ 425.3MB │
├─────────┼──────────────┼─────────┤
│ 5.3.0   │ 5 天前      │ 436.3MB │
└─────────┴──────────────┴─────────┘

`cypress cache clear`

清除 Cypress 缓存的内容。当您希望 Cypress 清除可能缓存在您机器上的所有已安装 Cypress 版本时，这很有用。运行此命令后，您需要运行 cypress install 才能再次运行 Cypress。

cypress cache clear

`cypress cache prune`

从缓存中删除所有已安装的 Cypress 版本，除了当前安装的版本。

cypress cache prune

调试命令

启用调试日志

如果您使用的是 macOS、Linux 或 Windows（Git Bash）并且您的包管理器是 npm，您可以使用以下 CLI 命令运行 Cypress 并启用调试日志：

DEBUG=cypress:* npx cypress run

有关生成调试日志的选项的更详细说明，请参阅故障排除，也适用于 Yarn 和 pnpm 包管理器，以及 Windows CMD 和 PowerShell 终端窗口。

历史

版本	变更
12.6.0	向 `cypress run` 添加了 `--auto-cancel-after-failures` 标志
5.4.0	向 `cypress cache` 添加了 `prune` 子命令
5.4.0	向 `cypress cache list` 子命令添加了 `--size` 标志
4.9.0	向 `cypress run` 添加了 `--quiet` 标志

命令行

如何运行命令​

使用脚本​

扩展脚本选项​

命令​

cypress run​

选项​

cypress run --auto-cancel-after-failures <autoCancelAfterFailures>​

cypress run --browser <browser-name-or-path>​

cypress run --ci-build-id <id>​

cypress run --config <config>​

真实世界示例​

cypress run --config-file <configuration-file>​

cypress run --env <env>​

cypress run --group <name>​

cypress run --headed​

cypress run --no-exit​

cypress run --no-runner-ui​

cypress run --parallel​

cypress run --port <port>​

cypress run --project <project-path>​

cypress run --quiet​

cypress run --record --key <record-key>​

cypress run --reporter <reporter>​

cypress run --runner-ui​

cypress run --spec <spec>​

cypress run --tag <tag>​

退出代码​

cypress open​

选项：​

cypress open --browser <browser-path>​

cypress open --config <config>​

cypress open --config-file <configuration-file>​

cypress open --env <env>​

cypress open --global​

cypress open --port <port>​

cypress open --project <project-path>​

cypress info​

cypress verify​

cypress version​

cypress cache [command]​

cypress cache path​

cypress cache list​

cypress cache clear​

cypress cache prune​

调试命令​

启用调试日志​

历史​

目录

如何运行命令

使用脚本

扩展脚本选项

命令

`cypress run`

选项

`cypress run --auto-cancel-after-failures <autoCancelAfterFailures>`

`cypress run --browser <browser-name-or-path>`

`cypress run --ci-build-id <id>`

`cypress run --config <config>`

真实世界示例

`cypress run --config-file <configuration-file>`

`cypress run --env <env>`

`cypress run --group <name>`

`cypress run --headed`

`cypress run --no-exit`

`cypress run --no-runner-ui`

`cypress run --parallel`

`cypress run --port <port>`

`cypress run --project <project-path>`

`cypress run --quiet`

`cypress run --record --key <record-key>`

`cypress run --reporter <reporter>`

`cypress run --runner-ui`

`cypress run --spec <spec>`

`cypress run --tag <tag>`

退出代码

`cypress open`

选项：

`cypress open --browser <browser-path>`

`cypress open --config <config>`

`cypress open --config-file <configuration-file>`

`cypress open --env <env>`

`cypress open --global`

`cypress open --port <port>`

`cypress open --project <project-path>`

`cypress info`

`cypress verify`

`cypress version`

`cypress cache [command]`

`cypress cache path`

`cypress cache list`

`cypress cache clear`

`cypress cache prune`

调试命令

启用调试日志

历史