集成测试

本文档提供了关于本项目使用的集成测试框架的信息。

概述

集成测试旨在验证 Gemini CLI 的端到端功能。它们在受控环境中执行构建的二进制文件，并验证在与文件系统交互时其行为是否符合预期。

这些测试位于 integration-tests 目录中，并使用自定义测试运行器运行。

构建测试

在运行任何集成测试之前，你需要创建一个想要实际测试的发布包：

npm run bundle

在更改 CLI 源代码后，你必须重新运行此命令，但在更改测试后则不需要。

运行测试

集成测试不是默认 npm run test 命令的一部分。它们必须明确使用 npm run test:integration:all 脚本运行。

也可以使用以下快捷方式运行集成测试：

npm run test:e2e

运行特定的测试集

要运行测试文件的子集，你可以使用 npm run <integration test command> <file_name1> ....，其中 <集成测试命令> 是 test:e2e 或 test:integration*，而 <file_name> 是 integration-tests/ 目录中任意一个 .test.js 文件。例如，以下命令运行 list_directory.test.js 和 write_file.test.js：

npm run test:e2e list_directory write_file

通过名称运行单个测试

要按名称运行单个测试，请使用 --test-name-pattern 标志：

npm run test:e2e -- --test-name-pattern "reads a file"

重新生成模型响应

某些集成测试使用模拟的模型响应，随着实现的变化，可能需要不时地重新生成这些响应。

要重新生成这些黄金文件，请在运行测试时将 REGENERATE_MODEL_GOLDENS 环境变量设置为 “true”，例如：

警告：如果在本地上运行，你应该检查这些更新的响应中是否有关于你自己或你的系统可能被 Gemini 包含的信息。

REGENERATE_MODEL_GOLDENS="true" npm run test:e2e

警告：确保在测试的最后运行 await rig.cleanup()，否则黄金文件将不会被更新。

去除测试的不稳定性

在添加新的集成测试之前，你应该使用去不稳定脚本或工作流程至少测试5次，以确保它不是偶然失败的。

去不稳定脚本

npm run deflake -- --runs=5 --command="npm run test:e2e -- -- --test-name-pattern '<your-new-test-name>'"

去不稳定工作流程

gh workflow run deflake.yml --ref <your-branch> -f test_name_pattern="<your-test-name-pattern>"

运行所有测试

要运行整个集成测试套件，请使用以下命令：

npm run test:integration:all

沙盒矩阵

all 命令将运行 no sandboxing、docker 和 podman 的测试。可以使用以下命令单独运行每种类型：

npm run test:integration:sandbox:none

npm run test:integration:sandbox:docker

npm run test:integration:sandbox:podman

诊断

集成测试运行器提供了一些用于诊断的选项，以帮助追踪测试失败的原因。

保留测试输出

你可以保留测试运行期间创建的临时文件以供检查。这对于调试文件系统操作问题很有用。

要保留测试输出，请将 KEEP_OUTPUT 环境变量设置为 true。

KEEP_OUTPUT=true npm run test:integration:sandbox:none

当保留输出时，测试运行器将打印出到该测试运行的唯一目录的路径。

详细输出

若要获取更详细的调试信息，请将 VERBOSE 环境变量设置为 true。

VERBOSE=true npm run test:integration:sandbox:none

当在同一个命令中使用 VERBOSE=true 和 KEEP_OUTPUT=true 时，输出将流式传输到控制台，并保存到测试临时目录中的日志文件。

详细输出被格式化为清晰标识日志的来源：

--- TEST: <log dir>:<test-name> ---
... output from the gemini command ...
--- END TEST: <log dir>:<test-name> ---

代码规范检查和格式化

为了确保代码质量和一致性，集成测试文件在主构建过程中进行了规范检查。你也可以手动运行规范检查器和自动修复器。

运行规范检查器

要检查规范错误，请运行以下命令：

npm run lint

您可以通过在命令中包含 :fix 标志来自动修复任何可修复的代码风格错误：

目录结构

集成测试在 .integration-tests 目录内为每次测试运行创建一个唯一的目录。在此目录内，为每个测试文件创建一个子目录，并且在该子目录内为每个单独的测试用例创建一个子目录。

这种结构使得查找特定测试运行、文件或用例的工件变得容易。

持续集成

为确保始终运行集成测试，在 .github/workflows/chained_e2e.yml 中定义了一个 GitHub Actions 工作流。此工作流会针对 main 分支的拉取请求自动运行集成测试，或者在拉取请求被添加到合并队列时。

工作流在不同的沙箱环境中运行测试，以确保 Gemini CLI 在每个环境中都得到测试：

sandbox:none：在没有沙箱的情况下运行测试。
sandbox:docker：在 Docker 容器中运行测试。
sandbox:podman：在 Podman 容器中运行测试。