Skip to content

集成测试

¥Integration Tests

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

¥This document provides information about the integration testing framework used in this project.

概述

¥Overview

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

¥The integration tests are designed to validate the end-to-end functionality of the Gemini CLI. They execute the built binary in a controlled environment and verify that it behaves as expected when interacting with the file system.

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

¥These tests are located in the integration-tests directory and are run using a custom test runner.

运行测试

¥Running the tests

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

¥The integration tests are not run as part of the default npm run test command. They must be run explicitly using the npm run test:integration:all script.

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

¥The integration tests can also be run using the following shortcut:

npm run test:e2e

运行一组特定的测试

¥Running a specific set of tests

要运行测试文件的子集，您可以使用npm run <integration test command> <file_name1> ....在哪里要么test:e2e或者test:integration*和<file_name>是.test.js文件integration-tests/目录。例如，以下命令运行list_directory.test.js和write_file.test.js：

¥To run a subset of test files, you can use npm run <integration test command> <file_name1> .... where is either test:e2e or test:integration* and <file_name> is any of the .test.js files in the integration-tests/ directory. For example, the following command runs list_directory.test.js and write_file.test.js:

npm run test:e2e list_directory write_file

按名称运行单个测试

¥Running a single test by name

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

¥To run a single test by its name, use the --test-name-pattern flag:

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

运行所有测试

¥Running all tests

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

¥To run the entire suite of integration tests, use the following command:

npm run test:integration:all

沙盒矩阵

¥Sandbox matrix

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

¥The all command will run tests for no sandboxing, docker and podman. Each individual type can be run using the following commands:

npm run test:integration:sandbox:none

npm run test:integration:sandbox:docker

npm run test:integration:sandbox:podman

诊断

¥Diagnostics

集成测试运行器提供了多种诊断选项来帮助追踪测试失败。

¥The integration test runner provides several options for diagnostics to help track down test failures.

保留测试输出

¥Keeping test output

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

¥You can preserve the temporary files created during a test run for inspection. This is useful for debugging issues with file system operations.

为了保持测试输出设置KEEP_OUTPUT环境变量true。

¥To keep the test output set the KEEP_OUTPUT environment variable to true.

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

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

¥When output is kept, the test runner will print the path to the unique directory for the test run.

详细输出

¥Verbose output

如需更详细的调试，请设置VERBOSE环境变量true。

¥For more detailed debugging, set the VERBOSE environment variable to true.

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

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

¥When using VERBOSE=true and KEEP_OUTPUT=true in the same command, the output is streamed to the console and also saved to a log file within the test's temporary directory.

详细输出的格式可以清楚地识别日志的来源：

¥The verbose output is formatted to clearly identify the source of the logs:

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

代码检查和格式化

¥Linting and formatting

为了确保代码质量和一致性，集成测试文件会在主构建过程中进行 lint 测试。您也可以手动运行 lint 和自动修复程序。

¥To ensure code quality and consistency, the integration test files are linted as part of the main build process. You can also manually run the linter and auto-fixer.

运行 linter

¥Running the linter

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

¥To check for linting errors, run the following command:

npm run lint

您可以包括:fix命令中的标志可以自动修复任何可修复的 linting 错误：

¥You can include the :fix flag in the command to automatically fix any fixable linting errors:

npm run lint:fix

目录结构

¥Directory structure

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

¥The integration tests create a unique directory for each test run inside the .integration-tests directory. Within this directory, a subdirectory is created for each test file, and within that, a subdirectory is created for each individual test case.

通过这种结构可以轻松找到特定测试运行、文件或案例的工件。

¥This structure makes it easy to locate the artifacts for a specific test run, file, or case.

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

持续集成

¥Continuous integration

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

¥To ensure the integration tests are always run, a GitHub Actions workflow is defined in .github/workflows/e2e.yml. This workflow automatically runs the integrations tests for pull requests against the main branch, or when a pull request is added to a merge queue.

工作流程在不同的沙盒环境中运行测试，以确保 Gemini CLI 在每个环境中都经过测试：

¥The workflow runs the tests in different sandboxing environments to ensure Gemini CLI is tested across each:

  • sandbox:none：无需任何沙盒即可运行测试。

    ¥sandbox:none: Runs the tests without any sandboxing.

  • sandbox:docker：在 Docker 容器中运行测试。

    ¥sandbox:docker: Runs the tests in a Docker container.

  • sandbox:podman：在 Podman 容器中运行测试。

    ¥sandbox:podman: Runs the tests in a Podman container.