CLI

相关源文件

• cli/__snapshots__/cli_spec.js
• cli/__snapshots__/cypress_spec.js
• cli/__snapshots__/util_spec.js
• cli/index.js
• cli/lib/cli.js
• cli/lib/cypress.js
• cli/lib/exec/open.js
• cli/lib/exec/run.js
• cli/lib/exec/shared.js
• cli/lib/exec/spawn.js
• cli/lib/exec/xvfb.js
• cli/lib/util.js
• cli/test/lib/cli_spec.js
• cli/test/lib/cypress_spec.js
• cli/test/lib/exec/open_spec.js
• cli/test/lib/exec/run_spec.js
• cli/test/lib/exec/spawn_spec.js
• cli/test/lib/exec/xvfb_spec.js
• cli/test/lib/util_spec.js

命令行界面（CLI）是执行 Cypress 测试的主要入口点。它处理命令行参数、管理 Cypress 二进制文件，并提供用于运行和启动 Cypress 的命令行工具和可编程 API。本文档涵盖了 CLI 的实现细节、命令结构以及底层架构。

有关二进制文件管理的信息，请参阅 二进制文件管理。

命令结构

Cypress CLI 支持多个主要命令：

命令	描述
open	在交互式 GUI 中打开 Cypress
run	从 CLI 运行 Cypress 测试，不带 GUI
install	安装与包版本匹配的 Cypress 二进制文件
verify	验证 Cypress 是否安装正确且可执行
cache	管理 Cypress 二进制文件缓存
info	打印 Cypress 和系统信息
version	打印 Cypress 版本信息
help	显示 CLI 帮助信息

来源：cli/lib/cli.js132-144

CLI 处理流程

Cypress CLI 命令遵循从用户输入到执行的一致处理流程。

图示：CLI 命令处理流程

来源：cli/lib/cli.js397-601 cli/lib/exec/spawn.js166-410

选项处理

CLI 命令接受许多选项，这些选项在传递给 Cypress 二进制文件之前会被解析和规范化。

1. 参数使用 Commander.js 库进行解析。
2. 选项会被验证和规范化。
3. 执行特定于命令的处理（例如，转换 spec 路径）。
4. 最终参数会被传递以启动二进制文件。

来源：cli/lib/cli.js58-93 cli/lib/exec/run.js37-160 cli/lib/exec/open.js17-72

使用 spawn 进行命令执行

spawn 模块负责使用提供的参数执行 Cypress 二进制文件。

图示：Spawn 进程流程

来源：cli/lib/exec/spawn.js166-410 cli/lib/exec/xvfb.js36-59

特定平台处理

Spawn 进程以特定方式处理不同平台：

平台	行为
Windows	对 stdio 使用 pipe，并设置 windowsHide: false。
Linux	如果未设置 DISPLAY 环境变量或其无效，则可能启动 XVFB。
macOS	使用特定的 stdio 配置来过滤输出。

来源：cli/lib/exec/spawn.js127-160 cli/lib/exec/xvfb.js61-95

输出过滤

CLI 会过滤输出日志中的“噪音”，尤其是在 Linux 上，因为 X11 和图形驱动程序可能会生成让用户感到困惑的警告。

来源：cli/lib/exec/spawn.js104-119 cli/lib/exec/spawn.js316-325

模块 API

CLI 还提供了一个 JavaScript API，用于以编程方式执行 Cypress。

图示：模块 API 流程

来源：cli/lib/cypress.js12-90

关键 API 函数

模块 API 公开了以下主要函数：

功能	描述
cypress.run(options)	以编程方式运行 Cypress 测试
cypress.open(options)	以编程方式在交互式 GUI 中打开 Cypress
cypress.cli.parseRunArguments(args)	解析 CLI 参数以供 API 使用
cypress.defineConfig(config)	用于配置文件中 TypeScript 智能提示的辅助函数

来源：cli/lib/cypress.js16-89

选项规范化

模块 API 在将选项传递给命令处理程序之前会对它们进行规范化。

来源：cli/lib/util.js72-74 cli/test/lib/cypress_spec.js128-139

命令实现

运行命令

run 命令在不使用 GUI 的情况下执行 Cypress 测试。

图示：Run 命令流程

来源：cli/lib/exec/run.js166-200 cli/lib/exec/run.js37-160

Open 命令

open 命令启动 Cypress GUI。

图示：Open 命令流程

来源：cli/lib/exec/open.js77-102 cli/lib/exec/open.js17-72

CLI 初始化和入口点

CLI 可以通过三种主要方式调用：

1. 命令行：cypress run、cypress open 等。
2. NPM Scripts：npm test 配合脚本 cypress run。
3. 编程 API：require('cypress').run()。

图示：CLI 入口点

来源：cli/index.js1-28 cli/lib/cli.js397-601 cli/lib/cypress.js12-90

命令行选项

以下是主要命令的选项：

Run 命令选项

选项	描述
--browser	运行测试的浏览器
--config	覆盖配置值
--config-file	配置文件路径
--env	设置环境变量
--spec	运行特定的测试文件
--headed	在 headed 模式下运行
--headless	在 headless 模式下运行
--record	将结果记录到 Cypress Cloud
--parallel	并行运行测试
--group	分组记录的测试
--tag	为记录的运行添加标签

来源：cli/lib/cli.js236-260

Open 命令选项

选项	描述
--browser	打开的浏览器
--config	覆盖配置值
--config-file	配置文件路径
--env	设置环境变量
--project	项目路径
--global	以全局模式运行
--component	运行组件测试
--e2e	运行端到端测试

来源: cli/lib/cli.js267-278

Linux 下的 XVFB 集成

在没有显示服务器的 Linux 上，CLI 会自动管理一个 X Virtual Frame Buffer (Xvfb)

图示：XVFB 集成流程

来源: cli/lib/exec/spawn.js358-403 cli/lib/exec/xvfb.js36-107

错误处理

CLI 以用户友好的方式处理错误

1. 命令特定的验证错误
2. 二进制文件验证错误
3. 进程执行错误 (例如，被终止，权限被拒绝)
4. 特定于平台的错误 (例如，Linux 上的 Xvfb 错误)

错误消息格式化以便于阅读，并且通常包含故障排除说明。

来源: cli/lib/cli.js217-216 cli/lib/util.js366-370

CLI 内部架构

CLI 组织成几个关键模块

图示：CLI 模块架构

来源: cli/lib/cli.js311-601 cli/lib/cypress.js12-90

命令行解析器实现

CLI 使用 Commander.js 来解析命令行参数

图示：命令行解析器实现

来源: cli/lib/cli.js219-229 cli/lib/cli.js232-278 cli/lib/cli.js397-601

Cypress CLI 系统的这个详细概述涵盖了它的架构、命令处理流程以及与操作系统的集成。CLI 作为用户命令和 Cypress 二进制文件之间的桥梁，处理特定于平台的注意事项，并提供命令行界面和编程 API。