테스트 실행

참고 항목

이 콘텐츠는 CodeQL CLI의 최신 릴리스에 대해 설명합니다. 이 요소에 대한 자세한 내용은 https://github.com/github/codeql-cli-binaries/releases을(를) 참조하세요.

이전 릴리스에서 이 명령에 사용할 수 있는 옵션의 세부 정보를 보려면 터미널에서 옵션을 사용하여 --help 명령을 실행합니다.

개요

Shell

codeql test run [--threads=<num>] [--ram=<MB>] <options>... -- <test|dir>...

codeql test run [--threads=<num>] [--ram=<MB>] <options>... -- <test|dir>...

Options

기본 옵션

`<test|dir>...`

각 인수는 다음 중 하나입니다.

실행할 테스트를 정의하는 .ql 또는 .qlref 파일입니다.
실행할 테스트를 재귀적으로 검색할 디렉터리입니다.

`--failing-exitcode=<code>`

          \[고급] 실패가 발생하는 경우 반환할 종료 코드를 설정합니다. 일반적으로 1을 사용하지만, 출력을 파싱하는 도구에서는 0으로 설정하는 것이 유용할 수 있습니다.

`--format=<fmt>`

출력 형식을 선택합니다. 가능한 선택지는 다음과 같습니다.

          `text`              _(기본값)_: 사람이 읽을 수 있는 텍스트 형식으로 출력합니다.

          `json`: 테스트 결과 객체로 구성된 스트리밍 JSON 배열을 출력합니다.

          `betterjson`: 이벤트 객체로 구성된 스트리밍 JSON 배열을 출력합니다.

          `jsonz`: 널(null) 종료된(JSON zero-terminated) 테스트 결과 객체 스트림을 출력합니다.

          `betterjsonz`: 널 종료된(JSON zero-terminated) 이벤트 객체 스트림을 출력합니다.

betterjson 및 betterjsonz 형식의 경우, 각 이벤트에는 이벤트 유형을 지정하는 type 속성이 있습니다. 향후 새 이벤트 유형이 추가될 수 있으므로, 소비자는 인식되지 않는 kind 속성을 가진 이벤트는 무시해야 합니다.

`--[no-]keep-databases`

          \[고급] 디렉터리 내의 모든 테스트가 통과하더라도 테스트 쿼리를 실행하기 위해 추출된 데이터베이스를 유지합니다. (테스트가 _실패_하는 경우에는 데이터베이스가 항상 유지됩니다.)

`--[no-]fast-compilation`

          \[사용 중단됨] \[고급] 테스트 쿼리를 컴파일할 때 특히 느린 최적화 단계를 생략합니다.

`--[no-]learn`

          \[고급] 테스트에서 예상치 못한 출력이 생성된 경우, 테스트를 실패 처리하는 대신 실제 출력에 맞게 `.expected` 파일을 업데이트하여 통과하도록 합니다. 이 모드에서도 테스트는 실패할 수 있습니다. 예를 들어, 쿼리할 테스트 데이터베이스 생성이 성공하지 않는 경우가 이에 해당합니다.

`--consistency-queries=<dir>`

          \[고급] 각 테스트 데이터베이스에 대해 실행할 일관성 쿼리가 포함된 디렉터리를 지정합니다. 문제를 발견한 경우를 제외하고는 이러한 쿼리는 어떤 출력도 생성하지 않아야 합니다. 단, 테스트 디렉터리에 `.expected` 파일이 포함된 `CONSISTENCY` 하위 디렉터리가 있는 경우는 예외입니다. 이는 주로 추출기를 테스트하는 데 유용합니다.

`--[no-]check-databases`

          \[고급] 생성된 각 테스트 데이터베이스에 대해 [codeql dataset check](/code-security/codeql-cli/codeql-cli-manual/dataset-check)를 실행하고, 불일치가 감지되면 실패로 보고합니다. 이는 추출기를 테스트할 때 유용합니다. 특정 데이터베이스에 대해 해당 검사가 (일시적으로) 실패할 것으로 예상되는 경우, 테스트 디렉터리에 `DB-CHECK.expected` 파일을 배치합니다.

`--[no-]show-extractor-output`

          \[고급] 테스트 데이터베이스를 생성하는 추출기 스크립트의 출력을 표시합니다. 이는 테스트 사례를 개발하거나 편집하는 동안 유용할 수 있습니다.

여러 스레드와 함께 사용할 경우 출력이 중복되거나 형식이 잘못될 수 있으므로 주의하세요.

`--slice=<N/M>`

          \[고급] 거의 동일한 크기의 _M_개 조각으로 테스트 사례를 분할한 후 그 중 _&#x4E;_&#x74;h번째만 처리합니다. 이는 테스트 프로세스를 수동으로 병렬화하는 데 사용할 수 있습니다.

`--[no-]strict-test-discovery`

          \[고급] 테스트로 강하게 식별될 수 있는 쿼리만 사용합니다.

이 모드는 단위 테스트를 정의하는 .ql 파일과 유용한 쿼리로 사용되도록 의도된 .ql 파일을 구분하려고 시도합니다. 이 옵션은 디렉터리 트리 내의 파일 배치 방식에 대한 사전 지식에 의존하지 않고 모든 단위 테스트를 식별해야 하는 IDE와 같은 도구에서 사용됩니다.

qlpack.yml에 tests 디렉터리를 선언한 QL 팩 내에서는 해당 디렉터리의 모든 .ql 파일이 테스트로 간주되며, 그 외 위치의 .ql 파일은 무시됩니다. tests 디렉터리를 선언하지 않는 QL 팩에서는, 대응되는 .expected 파일이 있는 경우에만 .ql 파일이 테스트로 식별됩니다.

일관성을 위해 .qlref 파일은 .qlref 파일이 실제로 비테스트가 될 수 없음에도 불구하고 .ql 파일과 동일한 규칙이 적용됩니다.

테스트에서 사용되는 라이브러리와 추출기를 찾기 위한 옵션입니다.

`--search-path=<dir>[:<dir>...]`

QL 팩이 존재할 수 있는 디렉터리 목록입니다. 각 디렉터리는 QL 팩(또는 루트에 .codeqlmanifest.json 파일을 포함하는 팩 번들)이거나, 그러한 디렉터리 하나 이상을 직접 포함하는 상위 디렉터리일 수 있습니다.

경로에 두 개 이상의 디렉터리가 포함된 경우, 나열된 순서에 따라 우선순위가 결정됩니다. 즉, 해결해야 하는 팩 이름이 둘 이상의 디렉터리 트리에서 일치하는 경우, 먼저 지정된 디렉터리가 우선됩니다.

오픈 소스 CodeQL 리포지토리의 체크아웃 경로로 이를 지정하면, 그 안에 포함된 언어 중 하나를 쿼리할 때 정상적으로 작동해야 합니다.

압축 해제된 CodeQL 툴체인과 나란히 CodeQL 리포지토리를 체크아웃한 경우에는 이 옵션을 지정할 필요가 없습니다. 이러한 형제 디렉터리는 다른 방법으로 찾을 수 없는 QL 팩을 검색할 때 항상 자동으로 탐색됩니다. (이 기본 설정이 작동하지 않는 경우, 사용자별 구성 파일에서 --search-path를 한 번 설정해 두는 것을 강력히 권장합니다.)

(참고: Windows에서는 경로 구분자가 ;입니다.)

`--additional-packs=<dir>[:<dir>...]`

이 디렉터리 목록이 지정된 경우, --search-path에 포함된 디렉터리보다 먼저 팩을 검색합니다. 이들 간의 순서는 중요하지 않습니다. 다만 이 목록을 통해 동일한 팩 이름이 두 곳에서 발견되면 오류가 발생합니다.

이는 기본 경로에도 존재하는 팩의 새 버전을 일시적으로 개발하는 경우에 유용합니다. 반대로, 이 옵션을 구성 파일에서 재정의하는 것은 권장하지 않습니다. 일부 내부 동작에서는 이 옵션을 동적으로 추가하여, 구성된 값을 덮어쓰기 때문입니다.

(참고: Windows에서는 경로 구분자가 ;입니다.)

`--library-path=<dir>[:<dir>...]`

          \[고급] QL 라이브러리에 대한 원시 가져오기 검색 경로에 추가될 선택적 디렉터리 목록입니다. 이는 QL 팩으로 패키징되지 않은 QL 라이브러리를 사용하는 경우에만 사용해야 합니다.

(참고: Windows에서는 경로 구분자가 ;입니다.)

`--dbscheme=<file>`

          \[고급] 어떤 dbscheme 쿼리를 대상으로 컴파일할지 명시적으로 정의합니다. 이는 자신이 무엇을 하고 있는지에 대해 매우 확신이 있는 호출자만 지정해야 합니다.

`--compilation-cache=<dir>`

          \[고급] 컴파일 캐시로 사용할 추가 디렉터리를 지정합니다.

`--no-default-compilation-cache`

          \[고급] 쿼리가 포함된 QL 팩이나 CodeQL 툴체인 디렉터리와 같은 표준 위치의 컴파일 캐시를 사용하지 않습니다.

CodeQL 패키지 관리자를 구성하기 위한 옵션입니다.

`--registries-auth-stdin`

쉼표로 구분된 <registry_url>=<token> 쌍 목록을 전달하여 GitHub Enterprise Server 컨테이너 레지스트리에 인증합니다.

예를 들어, https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2을 전달할 수 있습니다. 이는 두 개의 GitHub Enterprise Server 인스턴스에 인증하기 위한 것입니다.

이 옵션은 CODEQL_REGISTRIES_AUTH 및 GITHUB_TOKEN 환경 변수를 덮어씁니다. github.com 컨테이너 레지스트리에만 인증하면 되는 경우, 더 단순한 --github-auth-stdin 옵션을 사용하여 인증할 수 있습니다.

`--github-auth-stdin`

표준 입력을 통해 github.com용 GitHub Apps 토큰 또는 개인 액세스 토큰을 전달하여 github.com 컨테이너 레지스트리에 인증합니다.

GitHub Enterprise Server 컨테이너 레지스트리에 인증하려면 --registries-auth-stdin를 전달하거나 CODEQL_REGISTRIES_AUTH 환경 변수를 사용합니다.

이 옵션은 GITHUB_TOKEN 환경 변수를 덮어씁니다.

쿼리 컴파일을 제어하기 위한 옵션입니다.

`--no-release-compatibility`

          \[고급] 이식성을 희생하는 대신 최신 컴파일러 기능을 사용합니다.

때때로 새로운 QL 언어 기능과 평가기 최적화가 QL 컴파일러에서 기본적으로 활성화되기 몇 릴리스 전에 QL 평가기에서 먼저 지원됩니다. 이는 최신 CodeQL 릴리스에서 쿼리를 개발할 때 경험하는 성능이 코드 스캐닝 또는 CI 통합에서 여전히 사용 중일 수 있는 이전 버전의 릴리스에서도 동일하게 구현될 수 있도록 하는 데 도움이 됩니다.

쿼리가 다른(이전 또는 이후) CodeQL 릴리스와의 호환성을 고려하지 않아도 되는 경우, 이 플래그를 사용하여 컴파일러의 최근 개선 사항을 조기에 활성화함으로써 경우에 따라 소폭의 추가 성능을 얻을 수 있습니다.

활성화할 최근 개선 사항이 없는 릴리스에서는 이 옵션은 아무 동작도 하지 않습니다. 따라서 이를 전역 CodeQL 구성 파일에 한 번 설정해 두어도 안전합니다.

v2.11.1부터 사용할 수 있습니다.

테스트 쿼리의 평가를 제어하는 옵션입니다.

`--[no-]tuple-counting`

          \[고급] 쿼리 평가기 로그에서 각 평가 단계별 튜플 수를 표시합니다. 튜플 수는 `--evaluator-log` 옵션이 제공되면, 명령에서 생성되는 텍스트 기반 로그와 구조화된 JSON 로그 모두에 포함됩니다. (이는 복잡한 QL 코드의 성능 최적화에 유용할 수 있습니다.)

`--timeout=<seconds>`

          \[고급] 쿼리 평가의 제한 시간을 초 단위로 설정합니다.

제한 시간 기능은 복잡한 쿼리가 평가에 매우 오랜 시간이 걸리는 경우를 포착하기 위한 것입니다. 이는 쿼리 평가에 소요될 수 있는 전체 시간을 제한하는 효과적인 방법은 아닙니다. 평가는 각각 별도로 시간 측정되는 계산 부분이 제한 시간 내에 완료되는 한 계속 허용됩니다. 현재 이러한 개별 시간 측정 단위는 최적화된 쿼리의 “RA 레이어”이지만, 향후 변경될 수 있습니다.

제한 시간이 지정되지 않거나 0으로 지정된 경우에는 제한 시간이 설정되지 않습니다(단, codeql test run의 경우 기본 제한 시간은 5분입니다).

          \[고급] 지정된 파일에 평가기 성능에 대한 구조화된 로그를 출력합니다. 이 로그 파일의 형식은 예고 없이 변경될 수 있으나, 기본적으로는 두 개의 개행 문자로 구분된 JSON 객체 스트림이며, `--evaluator-log-minify` 옵션이 전달된 경우에는 하나의 개행 문자로 구분됩니다. 이 파일의 보다 안정적인 요약을 생성하려면 `codeql generate log-summary <file>`을 사용하고, 파일을 직접 파싱하는 것은 피하세요. 파일이 이미 존재하는 경우 덮어씁니다.

`--evaluator-log-minify`

          \[고급] `--evaluator-log` 옵션이 전달된 경우, 이 옵션을 함께 전달하면 사람이 읽기 훨씬 어려워지는 대신 생성되는 JSON 로그의 크기를 최소화합니다.

가져온 TRAP을 검사하기 위한 옵션입니다.

`--[no-]check-undefined-labels`

          \[고급] 정의되지 않은 레이블에 대해 오류를 보고합니다.

`--[no-]check-unused-labels`

          \[고급] 사용되지 않은 레이블에 대해 오류를 보고합니다.

`--[no-]check-repeated-labels`

          \[고급] 반복된 레이블에 대해 오류를 보고합니다.

`--[no-]check-redefined-labels`

          \[고급] 재정의된 레이블에 대해 오류를 보고합니다.

`--[no-]check-use-before-definition`

          \[고급] 정의되기 전에 사용된 레이블에 대해 오류를 보고합니다.

`--[no-]fail-on-trap-errors`

          \[고급] TRAP 가져오기 중 오류가 발생하면 0이 아닌 값으로 종료합니다.

`--[no-]include-location-in-star`

          \[고급] TRAP 파일에서 가져온 위치를 인코딩하는 엔터티 ID를 생성합니다. TRAP 생성기를 디버깅하는 데 유용할 수 있으나, 데이터 세트에서 많은 공간을 차지합니다.

`--[no-]linkage-aware-import`

          \[고급] [codeql dataset import](/code-security/codeql-cli/codeql-cli-manual/dataset-import)의 링크 인식 방식인지 여부를 제어합니다 _(기본값)_. 데이터베이스 생성의 이 부분이 과도한 메모리를 소모하는 프로젝트의 경우, 이 옵션을 비활성화하면 데이터베이스의 완전성을 일부 희생하는 대신 처리가 진행되는 데 도움이 될 수 있습니다.

v2.15.3부터 사용할 수 있습니다.

          \[고급] 명령을 실행하는 JVM에 옵션을 전달합니다.

(공백을 포함한 옵션은 올바르게 처리되지 않으므로 주의하세요.)

          \[고급] 오류, 경고, progress, progress+, progress++, progress+++ 중 하나로 상세 출력 수준을 명시적으로 설정합니다. 
          `-v` 및 `-q`를 재정의합니다.

`--logdir=<dir>`

          \[고급] 지정된 디렉터리에 하나 이상의 파일로 상세 로그를 기록하며, 생성되는 파일 이름에는 타임스탬프와 실행 중인 하위 명령의 이름이 포함됩니다.

(파일 이름을 완전히 제어하여 로그 파일을 작성하려면 대신 --log-to-stderr를 지정하고 stderr를 원하는 대로 리디렉션하세요.)

`--common-caches=<dir>`

          \[고급] 다운로드된 QL 팩과 컴파일된 쿼리 계획 등 CLI를 여러 번 실행하는 동안 유지되는 디스크상의 캐시 데이터 위치를 제어합니다. 명시적으로 설정하지 않으면 사용자 홈 디렉터리 내의 `.codeql`이라는 디렉터리를 기본값으로 사용하며, 해당 디렉터리가 존재하지 않는 경우 생성합니다.

v2.15.2부터 사용할 수 있습니다.

누가 이 기능을 사용할 수 있나요?

이 문서의 내용