통합 테스트 (Integration tests)
이 문서는 이 프로젝트에서 사용되는 통합 테스트 프레임워크에 대한 정보를 제공합니다.
개요 (Overview)
통합 테스트는 Gemini CLI의 엔드투엔드 기능을 검증하도록 설계되었습니다. 통제된 환경에서 빌드된 바이너리를 실행하고 파일 시스템과 상호 작용할 때 예상대로 작동하는지 확인합니다.
이 테스트들은 integration-tests 디렉터리에 위치하며 사용자 지정 테스트 실행기를 사용하여 실행됩니다.
테스트 빌드 (Building the tests)
통합 테스트를 실행하기 전에 실제로 테스트하려는 릴리스 번들을 생성해야 합니다:
npm run bundleCLI 소스 코드를 변경한 후에는 반드시 이 명령을 다시 실행해야 하지만, 테스트를 변경한 후에는 다시 실행할 필요가 없습니다.
테스트 실행 (Running the tests)
통합 테스트는 기본 npm run test 명령의 일부로 실행되지 않습니다. npm run test:integration:all 스크립트를 사용하여 명시적으로 실행해야 합니다.
통합 테스트는 다음 단축 명령을 사용하여 실행할 수도 있습니다:
npm run test:e2e특정 테스트 세트 실행 (Running a specific set of tests)
테스트 파일의 하위 집합을 실행하려면 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이름으로 단일 테스트 실행 (Running a single test by name)
이름으로 단일 테스트를 실행하려면 --test-name-pattern 플래그를 사용하세요:
npm run test:e2e -- --test-name-pattern "reads a file"모델 응답 재생성 (Regenerating model responses)
일부 통합 테스트는 가짜 모델 응답을 사용하는데, 구현이 변경됨에 따라 때때로 재생성해야 할 수 있습니다.
이러한 골든 파일(golden files)을 재생성하려면 테스트를 실행할 때 REGENERATE_MODEL_GOLDENS 환경 변수를 "true"로 설정하십시오. 예를 들어:
경고: 로컬에서 실행하는 경우 gemini가 이러한 응답에 포함했을 수 있는 자신 또는 시스템에 대한 정보를 검토해야 합니다.
REGENERATE_MODEL_GOLDENS="true" npm run test:e2e경고: 테스트 마지막에 **await rig.cleanup()**을 실행해야 합니다. 그렇지 않으면 골든 파일이 업데이트되지 않습니다.
테스트 안정화 (Deflaking a test)
새로운 통합 테스트를 추가하기 전에, 안정화 스크립트나 워크플로를 사용하여 최소 5번 이상 테스트하여 불안정하지 않은지 확인해야 합니다.
안정화 스크립트 (Deflake script)
npm run deflake -- --runs=5 --command="npm run test:e2e -- -- --test-name-pattern '<your-new-test-name>'"안정화 워크플로 (Deflake workflow)
gh workflow run deflake.yml --ref <your-branch> -f test_name_pattern="<your-test-name-pattern>"모든 테스트 실행 (Running all tests)
전체 통합 테스트 모음을 실행하려면 다음 명령을 사용하세요:
npm run test:integration:all샌드박스 매트릭스 (Sandbox matrix)
all 명령은 no sandboxing, docker, podman에 대한 테스트를 실행합니다.
각 개별 유형은 다음 명령을 사용하여 실행할 수 있습니다:
npm run test:integration:sandbox:nonenpm run test:integration:sandbox:dockernpm run test:integration:sandbox:podman진단 (Diagnostics)
통합 테스트 실행기는 테스트 실패 원인을 추적하는 데 도움이 되는 여러 진단 옵션을 제공합니다.
테스트 출력 유지 (Keeping test output)
검사를 위해 테스트 실행 중 생성된 임시 파일을 보존할 수 있습니다. 이는 파일 시스템 작업 관련 문제를 디버깅하는 데 유용합니다.
테스트 출력을 유지하려면 KEEP_OUTPUT 환경 변수를 true로 설정하세요.
KEEP_OUTPUT=true npm run test:integration:sandbox:none출력이 유지되면 테스트 실행기는 테스트 실행을 위한 고유 디렉터리의 경로를 인쇄합니다.
상세 출력 (Verbose output)
더 자세한 디버깅을 위해 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> ---린팅 및 포맷팅 (Linting and formatting)
코드 품질과 일관성을 보장하기 위해 통합 테스트 파일은 기본 빌드 프로세스의 일부로 린트됩니다. 린터와 자동 수정기를 수동으로 실행할 수도 있습니다.
린터 실행 (Running the linter)
린팅 오류를 확인하려면 다음 명령을 실행하세요:
npm run lint명령에 :fix 플래그를 포함하여 수정 가능한 린팅 오류를 자동으로 수정할 수 있습니다:
npm run lint:fix디렉터리 구조 (Directory structure)
통합 테스트는 .integration-tests 디렉터리 내에 각 테스트 실행을 위한 고유 디렉터리를 생성합니다. 이 디렉터리 내에는 각 테스트 파일에 대한 하위 디렉터리가 생성되고, 그 안에는 각 개별 테스트 케이스에 대한 하위 디렉터리가 생성됩니다.
이 구조 덕분에 특정 테스트 실행, 파일 또는 케이스에 대한 아티팩트를 쉽게 찾을 수 있습니다.
.integration-tests/
└── <run-id>/
└── <test-file-name>.test.js/
└── <test-case-name>/
├── output.log
└── ...other test artifacts...지속적 통합 (Continuous integration)
통합 테스트가 항상 실행되도록 하기 위해 GitHub Actions 워크플로가 .github/workflows/chained_e2e.yml에 정의되어 있습니다. 이 워크플로는 main 브랜치에 대한 풀 리퀘스트를 위해 또는 풀 리퀘스트가 병합 대기열에 추가될 때 자동으로 통합 테스트를 실행합니다.
워크플로는 다양한 샌드박싱 환경에서 테스트를 실행하여 Gemini CLI가 각 환경에서 테스트되도록 합니다:
sandbox:none: 샌드박싱 없이 테스트를 실행합니다.sandbox:docker: Docker 컨테이너에서 테스트를 실행합니다.sandbox:podman: Podman 컨테이너에서 테스트를 실행합니다.