跳转至

--- TEST: : --- ... output from the gemini command ... --- END TEST: : ---

集成测试

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

概述

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

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

运行测试

集成测试不包含在默认的 npm run test 命令中。必须显式使用 npm run test:integration:all 脚本来运行。

也可以通过以下快捷方式运行集成测试:

npm run test:e2e

运行特定测试集

要运行测试文件的子集,可以使用 npm run <integration test command> <file_name1> .... 命令,其中 可以是 test:e2etest:integration*,而 <file_name>integration-tests/ 目录中的任意 .test.js 文件。例如,以下命令运行 list_directory.test.jswrite_file.test.js

npm run test:e2e list_directory write_file

按名称运行单个测试

要通过测试名称运行单个测试,使用 --test-name-pattern 标志:

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

运行所有测试

要运行完整的集成测试套件,使用以下命令:

npm run test:integration:all

沙盒矩阵

all 命令会运行 no sandboxingdockerpodman 的测试。 每种类型可以分别使用以下命令运行:

npm run test:integration:sandbox:none
npm run test:integration:sandbox:docker
npm run test:integration:sandbox:podman

诊断

集成测试运行器提供了多个诊断选项来帮助排查测试失败原因。

保留测试输出

您可以选择保留测试运行过程中生成的临时文件以供检查。这对于调试文件系统操作相关的问题非常有用。

要保留测试输出,您可以使用 --keep-output 标志或将 KEEP_OUTPUT 环境变量设为 true

# 使用标志
npm run test:integration:sandbox:none -- --keep-output


# 使用环境变量
KEEP_OUTPUT=true npm run test:integration:sandbox:none

当输出被保留时,测试运行器会打印该次测试运行对应的唯一目录路径。

详细输出

如需更详细的调试信息,可使用 --verbose 标志将 gemini 命令的实时输出流式传输到控制台。

npm run test:integration:sandbox:none -- --verbose

当在同一命令中同时使用 --verbose--keep-output 时,输出不仅会流式传输到控制台,还会保存到测试临时目录中的日志文件。

详细输出经过格式化,能清晰标识日志来源:


代码检查与格式化

为确保代码质量和一致性,集成测试文件作为主构建流程的一部分会进行代码检查。您也可以手动运行检查器和自动修复工具。

运行检查器

要检查代码规范错误,可运行以下命令:

npm run lint

您可以在命令中加入 --fix 标志来自动修复可修复的规范错误:

npm run lint --fix

目录结构

集成测试会在 .integration-tests 目录下为每次测试运行创建一个唯一的目录。在该目录中,会为每个测试文件创建一个子目录,并在其中为每个测试用例再创建一个子目录。

这种结构使得定位特定测试运行、文件或用例的产物变得非常容易。

.integration-tests/
└── <运行ID>/
    └── <测试文件名>.test.js/
        └── <测试用例名>/
            ├── output.log
            └── ...其他测试产物...

持续集成

为确保集成测试始终被执行,在 .github/workflows/e2e.yml 中定义了一个 GitHub Actions 工作流。该工作流会在每次拉取请求和推送到 main 分支时自动运行集成测试。

工作流会在不同的沙盒环境中运行测试,以确保 Gemini CLI 在每种环境下都能通过测试:

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