test run

참고 항목

이 콘텐츠는 CodeQL CLI의 최신 릴리스에 대해 설명합니다. 이 요소에 대한 자세한 내용은 http://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`: 0으로 종료되는 JSON 테스트 결과 개체의 스트림입니다.

          `betterjsonz`: 0으로 종료되는 JSON 이벤트 개체의 스트림입니다.

betterjson 및 betterjsonz 형식에서는 각 이벤트마다 이벤트의 유형을 지정하는 type 속성이 있습니다. 이후에 새 이벤트 유형이 추가될 수 있으므로 소비자는 인식할 수 없는 kind 속성이 포함된 이벤트를 무시해야 합니다.

`--[no-]keep-databases`

          \[고급] 디렉터리의 테스트가 모두 통과한 경우에도 테스트 쿼리 실행을 위해 추출된 데이터베이스를 유지합니다. (_실패_한 테스트가 있으면 데이터베이스는 항상 그대로 유지됩니다.)

`--[no-]fast-compilation`

          \[사용되지 않음] \[고급] 테스트 쿼리를 컴파일하는 경우에는 특히 느린 최적화 단계를 생략합니다.

`--[no-]learn`

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

`--consistency-queries=<dir>`

          \[고급] 각 테스트 데이터베이스마다 실행될 일관성 쿼리가 포함된 디렉터리입니다. 이 쿼리는 문제를 발견한 경우를 제외하고 어떤 출력도 생성해서는 안 됩니다. 단, 며 테스트 디렉터리에 `CONSISTENCY` 하위 디렉터리와 `.expected` 파일이 포함되는 경우는 예외입니다. 일반적으로 추출기 테스트 시 유용합니다.

`--[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 팩의 경우, .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`

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

예를 들어, http://containers.GHEHOSTNAME1/v2/=TOKEN1,http://containers.GHEHOSTNAME2/v2/=TOKEN2을 전달하여 두 개의 GitHub Enterprise Server 인스턴스에 인증할 수 있습니다.

이는 CODEQL_REGISTRIES_AUTH 및 GITHUB_TOKEN 환경 변수를 재정의합니다. github.com 컨테이너 레지스트리 인증만 필요한 경우 --github-auth-stdin 옵션을 사용하여 간편하게 인증할 수 있습니다.

`--github-auth-stdin`

GitHub Apps 토큰 또는 개인용 액세스 토큰을 github.com에 전달하여 표준 입력을 통해 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 로그의 크기가 최소화되지만 가독성이 크게 저하됩니다.

가져온 트랩을 검사하기 위한 옵션

`--[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`

          \[고급] 트랩 가져오기 중에 오류가 발생한 경우 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에 옵션을 제공합니다.

(옵션에 공백이 포함되면 제대로 처리되지 않을 수 있는 점에 유의해야 합니다.)

          \[고급] 세부 정보 표시 수준을 명시적으로 오류, 경고, 진행률, 진행률+, 진행률++, 진행률+++ 중 하나로 설정합니다. 
          `-v` 및 `-q`를 재정의합니다.

`--logdir=<dir>`

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

(로그 파일 이름을 직접 작성하려면 대신 --log-to-stderr을 지정하고 stderr를 원하는 위치로 리디렉션합니다.)

`--common-caches=<dir>`

          \[고급] 다운로드한 QL 팩 및 컴파일된 쿼리 계획 등 CLI를 여러 번 실행해도 지속되는 디스크의 캐시된 데이터의 위치를 제어합니다. 명시적으로 설정하지 않으면, 기본적으로 사용자의 홈 디렉터리에 이름이 지정된 `.codeql` 디렉터리로 설정됩니다. 디렉터리가 아직 없는 경우에는 만들어집니다.

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

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

이 문서의 내용