테스트 실행

참고

이 콘텐츠는 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>`

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

`--[no-]check-databases`

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

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

[고급] 테스트 데이터베이스를 생성하는 추출기 스크립트의 출력을 표시합니다. 이는 테스트 사례를 개발하거나 편집하는 동안 유용할 수 있습니다. 여러 스레드와 함께 사용할 경우 출력이 중복되거나 형식이 잘못될 수 있으므로 주의하세요.

`--slice=<N/M>`

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

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

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

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

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

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

`--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분입니다).

`-j, --threads=<num>`

쿼리를 평가하는 데 사용할 스레드 수를 지정합니다.

기본값은 1입니다. 0을 전달하면 머신의 각 코어당 하나의 스레드를 사용하며, -_N_을 전달하면 최소 하나의 스레드는 사용하되 _N_개의 코어를 사용하지 않도록 합니다.

구조화된 평가기 로그 출력 제어를 위한 옵션입니다.

`--evaluator-log=<file>`

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

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

이 기사에서