整合測試

本文件提供關於此專案中使用的整合測試框架的資訊。

總覽

整合測試旨在驗證 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 "reads a file"

執行所有測試

若要執行整套整合測試，請使用以下指令：

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 旗標，或將 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 時，輸出會串流至主控台，並同時儲存到測試暫存目錄中的記錄檔。

詳細輸出的格式會清楚標示記錄的來源：

--- TEST: <file-name-without-js>:<test-name> ---
... 來自 gemini 指令的輸出 ...
--- END TEST: <file-name-without-js>:<test-name> ---

Linting 與格式化

為了確保程式碼品質與一致性，整合測試檔案會作為主要建構過程的一部分進行 linting。您也可以手動執行 linter 和自動修復工具。

執行 linter

若要檢查 linting 錯誤，請執行以下指令：

npm run lint

您可以在指令中加入 --fix 旗標，以自動修復任何可修復的 linting 錯誤：

npm run lint --fix

目錄結構

整合測試會在 .integration-tests 目錄內為每次測試執行建立一個唯一的目錄。在這個目錄中，會為每個測試檔案建立一個子目錄，而在該子目錄中，會為每個個別的測試案例建立一個子目錄。

這種結構讓您能輕鬆找到特定測試執行、檔案或案例的產物。

.integration-tests/
└── <run-id>/
    └── <test-file-name>.test.js/
        └── <test-case-name>/
            ├── output.log
            └── ...其他測試產物...

持續整合

為確保整合測試總是會執行，我們在 .github/workflows/e2e.yml 中定義了一個 GitHub Actions 工作流程。此工作流程會在每次對 main 分支發出 pull request 和 push 時自動執行整合測試。

此工作流程會在不同的沙箱環境中執行測試，以確保 Gemini CLI 在每個環境中都經過測試：

  • sandbox:none: 在沒有任何沙箱的情況下執行測試。
  • sandbox:docker: 在 Docker 容器中執行測試。
  • sandbox:podman: 在 Podman 容器中執行測試。
Last Updated:
Contributors: doggy8088