集成测试

本文档介绍本项目使用的集成测试框架。

概览

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

这些测试位于 integration-tests 目录，由自定义测试运行器执行。

运行测试

集成测试不会在默认的 npm run test 中执行，需要手动运行 npm run test:integration:all。

也可以使用以下快捷命令执行集成测试：

npm run test:e2e

运行指定测试集合

要运行部分测试文件，可使用 npm run <integration test command> <file_name1> ....，其中 <integration test command> 可以是 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 "读取文件的用例"

测试去抖

在提交新的集成测试前，应至少配合 deflake 脚本运行 5 次，确认不会偶发失败。

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

运行全部测试

要运行完整的集成测试套件，可执行：

npm run test:integration:all

Sandbox 组合

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> ---

Lint 与格式化

为确保代码质量与一致性，集成测试文件会在主构建流程中进行 Lint。你也可以手动运行 Linter 及自动修复命令。

运行 Linter

检查 Lint 错误：

npm run lint

在命令中添加 :fix 可自动修复可修复的问题：

npm run lint:fix

目录结构

集成测试会在 .integration-tests 目录下为每次测试运行创建唯一目录，在该目录内，每个测试文件对应一个子目录，每个测试用例又有对应子目录。

该结构便于按测试运行、文件或用例定位产物。

.integration-tests/
└── <run-id>/
    └── <test-file-name>.test.js/
        └── <test-case-name>/
            ├── output.log
            └── ...other test artifacts...

持续集成

为确保集成测试持续执行，.github/workflows/e2e.yml 中定义了 GitHub Actions 工作流。该工作流会在针对 main 分支的 Pull Request 或被加入合并队列时自动运行集成测试。

该工作流会在不同的 Sandboxing 环境中运行测试，确保 Gemini CLI 在各环境下都能通过：

sandbox:none：无 Sandboxing 环境执行。
sandbox:docker：在 Docker 容器中执行。
sandbox:podman：在 Podman 容器中执行。