사용자 지정 쿼리 테스트

사용자 지정 쿼리 테스트 정보

CodeQL는 쿼리의 자동화된 회귀 테스트를 위한 간단한 테스트 프레임워크를 제공합니다. 쿼리가 예상대로 작동하는지 테스트합니다.

쿼리 테스트 중에 CodeQL는 사용자가 쿼리가 생성될 것으로 예상하는 결과를 실제로 생성된 결과와 비교합니다. 예상 결과와 실제 결과가 다르면 쿼리 테스트가 실패합니다. 테스트를 수정하려면 실제 결과와 예상 결과가 정확히 일치할 때까지 쿼리 및 예상 결과를 반복해야 합니다. 이 항목에서는 하위 명령을 사용하여 test run 테스트 파일을 만들고 테스트 파일을 실행하는 방법을 보여 줍니다.

사용자 지정 쿼리에 대한 테스트 CodeQL 팩 설정

모든 CodeQL 테스트는 특별한 "테스트" CodeQL 팩에 저장해야 합니다. 즉, 다음을 정의하는 파일이 있는 테스트 파일의 qlpack.yml 디렉터리입니다.

name: <name-of-test-pack>
version: 0.0.0
dependencies:
  <codeql-libraries-and-queries-to-test>: "*"
extractor: <language-of-code-to-test>

값은 dependencies 테스트할 쿼리가 포함된 CodeQL 팩을 지정합니다. 일반적으로 이러한 팩은 원본에서 확인되므로 고정된 버전의 팩을 지정할 필요가 없습니다. 는 extractor CLI가 이 CodeQL 팩에 저장된 코드 파일에서 테스트 데이터베이스를 만드는 데 사용할 언어를 정의합니다. 자세한 내용은 "CodeQL 팩 정보"를 참조하세요.

쿼리 테스트가 CodeQL 리포지토리에서 구성되는 방식을 살펴보는 것이 유용할 수 있습니다. 각 언어에는 src 코드베이스를 분석하기 위한 라이브러리 및 쿼리가 포함된 디렉터리 ql/<language>/ql/src가 있습니다. src 디렉터리와 test 함께 이러한 라이브러리 및 쿼리에 대한 테스트가 있는 디렉터리가 있습니다.

각 test 디렉터리가 두 개의 하위 디렉터리가 있는 테스트 CodeQL 팩으로 구성됩니다.

• query-tests 디렉터리에 저장된 쿼리에 대한 테스트가 포함된 src 일련의 하위 디렉터리입니다. 각 하위 디렉터리에는 테스트할 쿼리를 지정하는 테스트 코드와 QL 참조 파일이 포함되어 있습니다.
• library-tests QL 라이브러리 파일에 대한 테스트를 사용하는 일련의 하위 디렉터리입니다. 각 하위 디렉터리에는 라이브러리에 대한 단위 테스트로 작성된 테스트 코드 및 쿼리가 포함됩니다.

쿼리에 대한 테스트 파일 설정

테스트하려는 각 쿼리에 대해 테스트 CodeQL 팩에 하위 디렉터리를 만들어야 합니다. 그런 다음, 테스트 명령을 실행하기 전에 하위 디렉터리에 다음 파일을 추가합니다.

• 테스트할 쿼리의 위치를 정의하는 쿼리 참조 파일(.qlref 파일)입니다. 위치는 쿼리를 포함하는 CodeQL 팩의 루트를 기준으로 정의됩니다. 일반적으로 테스트 팩 블록에 지정된 dependencies CodeQL 팩입니다. 자세한 내용은 "쿼리 참조 파일"을 참조하세요.

  테스트하려는 쿼리가 테스트 디렉터리에 저장된 경우 쿼리 참조 파일을 추가할 필요가 없지만 일반적으로 테스트와 별도로 쿼리를 저장하는 것이 좋습니다. 유일한 예외는 경고 또는 경로를 생성하는 쿼리와는 별도로 테스트 팩에 저장되는 경향이 있는 QL 라이브러리에 대한 단위 테스트입니다.

• 쿼리를 실행할 예제 코드입니다. 쿼리가 식별하도록 설계된 코드의 예제를 포함하는 하나 이상의 파일로 구성되어야 합니다.

확장 .expected명 를 사용하여 파일을 만들어 예제 코드에 대해 쿼리를 실행할 때 예상되는 결과를 정의할 수도 있습니다. 또는 테스트 명령을 그대로 두고 파일을 만들 .expected 수 있습니다.

쿼리를 만들고 테스트하는 방법을 보여 주는 예제는 아래 예제 를 참조하세요.

실행 중 codeql test run

CodeQL 쿼리 테스트는 다음 명령을 실행하여 실행됩니다.

codeql test run <test|dir>

인수는 <test|dir> 다음 중 하나 이상이 될 수 있습니다.

• 파일의 경로입니다 .ql .
• 파일을 참조하는 .qlref 파일의 경로입니다 .ql .
• 및 .qlref 파일을 재귀적으로 .ql 검색할 디렉터리의 경로입니다.

다음을 지정할 수도 있습니다.

• --threads: 필요에 따라 쿼리를 실행할 때 사용할 스레드 수입니다. 기본 옵션은 입니다 1. 더 많은 스레드를 지정하여 쿼리 실행 속도를 높일 수 있습니다. 를 지정하면 0 스레드 수가 논리 프로세서 수와 일치합니다.

쿼리를 테스트할 때 사용할 수 있는 모든 옵션에 대한 자세한 내용은 테스트 실행 참조 설명서를 참조하세요.

예제

다음 예제에서는 Java 코드에서 빈 then 블록이 있는 문을 검색하는 쿼리에 대한 if 테스트를 설정하는 방법을 보여 줍니다. 여기에는 CodeQL 리포지토리의 체크 아웃 외부에서 CodeQL 팩을 구분하는 사용자 지정 쿼리 및 해당 테스트 파일을 추가하는 단계가 포함되어 있습니다. 이렇게 하면 CodeQL 라이브러리를 업데이트하거나 다른 분기를 체크 아웃할 때 사용자 지정 쿼리 및 테스트를 덮어쓰지 않습니다.

쿼리 및 테스트 파일 준비

1. 쿼리를 개발합니다. 예를 들어 다음 간단한 쿼리는 Java 코드에서 빈 then 블록을 찾습니다.

   import java
   
   from IfStmt ifstmt
   where ifstmt.getThen() instanceof EmptyStmt
   select ifstmt, "This if statement has an empty then."
   

2. 다른 사용자 지정 쿼리를 사용하여 디렉터리에 있는 라는 EmptyThen.ql 파일에 쿼리를 저장합니다. 예들 들어 custom-queries/java/queries/EmptyThen.ql입니다.

3. CodeQL 팩에 사용자 지정 쿼리를 아직 추가하지 않은 경우 지금 CodeQL 팩을 만듭니다. 예를 들어 사용자 지정 Java 쿼리가 에 custom-queries/java/queries저장된 경우 다음 내용이 포함된 파일을 에 custom-queries/java/queries추가 qlpack.yml 합니다.

   name: my-custom-queries
   dependencies:
     codeql/java-queries: "*"
   

   CodeQL 팩에 대한 자세한 내용은 "CodeQL 팩 정보"를 참조하세요.

4. 다음 내용이 포함된 파일을 에 추가하여 qlpack.yml Java 테스트에 대한 CodeQL 팩을 custom-queries/java/tests만들고 을 사용자 지정 쿼리의 CodeQL 팩의 이름과 일치하도록 업데이트 dependencies 합니다.

   다음 qlpack.yml 파일은 1.2.3보다 크거나 같은 버전에서 2.0.0보다 작은 버전에 의존하는 my-github-user/my-custom-queries 것을 나타냅니다my-github-user/my-query-tests. 또한 CLI는 테스트 데이터베이스를 만들 때 Java extractor 를 사용해야 한다고 선언합니다. 줄은 tests: . 옵션을 사용하여 가 실행될 때 codeql test run 팩의 모든 .ql 파일을 테스트로 실행 --strict-test-discovery 해야 한다고 선언합니다. 일반적으로 테스트 팩에는 속성이 version 포함되어 있지 않습니다. 이렇게 하면 실수로 게시할 수 없습니다.

     name: my-github-user/my-query-tests
     dependencies:
       my-github-user/my-custom-queries: ^1.2.3
     extractor: java
     tests: .
   

5. Java 테스트 팩 내에서 와 연결된 테스트 파일을 포함할 디렉터리를 만듭니다 EmptyThen.ql. 예들 들어 custom-queries/java/tests/EmptyThen입니다.

6. 새 디렉터리에서 를 만들어 EmptyThen.qlref 의 EmptyThen.ql위치를 정의합니다. 쿼리가 포함된 CodeQL 팩의 루트를 기준으로 쿼리 경로를 지정해야 합니다. 이 경우 쿼리는 에 대한 my-query-tests종속성으로 선언된 라는 my-custom-queriesCodeQL 팩의 최상위 디렉터리에 있습니다. 따라서 는 단순히 를 EmptyThen.qlref 포함 EmptyThen.ql해야 합니다.

7. 테스트할 코드 조각을 만듭니다. 다음 Java 코드는 세 번째 줄에 빈 if 문을 포함합니다. 에 저장합니다 custom-queries/java/tests/EmptyThen/Test.java.

   class Test {
   public void problem(String arg) {
    if (arg.isEmpty())
    ;
    {
        System.out.println("Empty argument");
    }
   }
   
   public void good(String arg) {
    if (arg.isEmpty()) {
        System.out.println("Empty argument");
    }
   }
   }
   

테스트 실행

테스트를 실행하려면 디렉터리로 이동하고 를 custom-queries 실행 codeql test run java/tests/EmptyThen합니다.

테스트가 실행되면 다음을 수행합니다.

1. 디렉터리에서 EmptyThen 하나의 테스트를 찾습니다.

2. 디렉터리에 저장된 파일에서 .java CodeQL 데이터베이스를 EmptyThen 추출합니다.

3. 파일에서 참조하는 쿼리를 컴파일합니다 EmptyThen.qlref .

   이 단계가 실패하면 CLI에서 사용자 지정 CodeQL 팩을 찾을 수 없기 때문입니다. 명령을 다시 실행하고 사용자 지정 CodeQL 팩의 위치를 지정합니다. 예를 들면 다음과 같습니다.

   codeql test run --search-path=java java/tests/EmptyThen

   구성의 일부로 검색 경로를 저장하는 방법에 대한 자세한 내용은 "CodeQL 구성 파일에서 명령 옵션 지정"을 참조하세요.

4. 쿼리를 실행하고 결과 파일을 생성하여 테스트를 실행합니다 EmptyThen.actual .

5. EmptyThen.expected 결과 파일과 비교할 파일을 확인합니다.actual.

6. 테스트 결과를 보고합니다. 이 경우 오류는 0 tests passed; 1 tests failed:입니다. 쿼리의 예상 결과가 포함된 파일을 아직 추가하지 않았기 때문에 테스트에 실패했습니다.

쿼리 테스트 출력 보기

CodeQL은(는) 디렉터리에 다음 파일을 EmptyThen 생성합니다.

• EmptyThen.actual- 쿼리에서 생성된 실제 결과를 포함하는 파일입니다.
• EmptyThen.testprojVS Code에 로드하고 실패한 테스트를 디버그하는 데 사용할 수 있는 테스트 데이터베이스입니다. 테스트가 성공적으로 완료되면 이 데이터베이스는 하우스키핑 단계에서 삭제됩니다. 옵션을 사용하여 를 실행 test run 하여 이 단계를 재정의할 --keep-databases 수 있습니다.

이 경우 오류가 예상되었으며 쉽게 해결할 수 있습니다. 파일을 열 EmptyThen.actual 면 테스트 결과를 볼 수 있습니다.

| Test.java:3:5:3:22 | stmt | This if statement has an empty then. |

이 파일에는 쿼리가 출력하는 절의 각 부분에 대한 별도의 열과 함께 결과의 위치에 대한 열이 select 있는 테이블이 포함되어 있습니다. 결과가 예상한 결과이므로 파일 확장자를 업데이트하여 이 테스트(EmptyThen.expected)에 대한 예상 결과로 정의할 수 있습니다.

지금 테스트를 다시 실행하면 출력은 비슷하지만 보고 All 1 tests passed.하여 완료됩니다.

예를 들어 쿼리의 결과가 변경되면 쿼리에 select 대한 문을 수정하면 테스트가 실패합니다. 실패한 결과의 경우 CLI 출력에는 및 EmptyThen.actual 파일의 통합 차이가 EmptyThen.expected 포함됩니다. 이 정보는 간단한 테스트 실패를 디버그하기에 충분할 수 있습니다.

디버그하기 어려운 오류의 경우 VS Code용 CodeQL로 가져오 EmptyThen.testproj 고, 를 실행하고 EmptyThen.ql, 예제 코드에서 Test.java 결과를 볼 수 있습니다. 자세한 내용은 VS Code 도움말의 CodeQL에서 "프로젝트 분석"을 참조하세요.

추가 참고 자료

• "CodeQL 쿼리"
• "Visual Studio Code CodeQL 쿼리 테스트."