{"meta":{"title":"Testar consultas personalizadas","intro":"Verifique as suas consultas personalizadas CodeQL e identifique as alterações significativas antes que afetem os seus code scanning resultados em novas versões do CodeQL CLI.","product":"Qualidade de segurança e código","breadcrumbs":[{"href":"/pt/code-security","title":"Qualidade de segurança e código"},{"href":"/pt/code-security/how-tos","title":"How-tos"},{"href":"/pt/code-security/how-tos/find-and-fix-code-vulnerabilities","title":"Localizar e corrigir vulnerabilidades de código"},{"href":"/pt/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line","title":"Verificar a partir da linha de comando"},{"href":"/pt/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/testing-custom-queries","title":"Testar consultas personalizadas"}],"documentType":"article"},"body":"# Testar consultas personalizadas\n\nVerifique as suas consultas personalizadas CodeQL e identifique as alterações significativas antes que afetem os seus code scanning resultados em novas versões do CodeQL CLI.\n\n## Testar consultas personalizadas\n\n```\n          CodeQL fornece uma estrutura de teste simples para testes automatizados de regressão de consultas. Teste as consultas para garantir que elas se comportem conforme o esperado.\n```\n\nDurante um teste de consulta, CodeQL compara os resultados que o usuário espera que a consulta produza com os realmente produzidos. Se os resultados esperados e reais forem diferentes, o teste de consulta falhará. Para corrigir o teste, você deve iterar na consulta e nos resultados esperados até que os resultados reais e os resultados esperados correspondam exatamente. Este tópico mostra como criar arquivos de teste e executar testes neles usando o subcomando `test run`.\n\n## Configurando um pacote de teste CodeQL para consultas personalizadas\n\nTodos os CodeQL testes devem ser armazenados em um pacote especial de \"teste CodeQL \". Ou seja, um diretório de arquivos de teste com um arquivo `qlpack.yml` que defina:\n\n```yaml\nname: <name-of-test-pack>\nversion: 0.0.0\ndependencies:\n  <codeql-libraries-and-queries-to-test>: \"*\"\nextractor: <language-of-code-to-test>\n```\n\nO `dependencies` valor especifica os CodeQL pacotes que contêm consultas a serem testadas.\nNormalmente, esses pacotes serão resolvidos na origem e, portanto, não é necessário especificar uma versão fixa do pacote. Define `extractor` qual idioma a CLI usará para criar bancos de dados de teste a partir dos arquivos de código armazenados neste CodeQL pacote. Para obter mais informações, consulte [Como personalizar a análise com pacotes CodeQL](/pt/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs).\n\nVocê pode achar útil examinar a forma como os testes de consulta são organizados no [CodeQL repositório](https://github.com/github/codeql). Cada linguagem tem um diretório `src`, o `ql/<language>/ql/src`, que contém bibliotecas e consultas para analisar bases de código. Junto com o diretório `src`, há um diretório `test` com testes para essas bibliotecas e consultas.\n\nCada `test` diretório é configurado como um pacote de teste CodeQL com dois subdiretórios:\n\n* `query-tests` uma série de subdiretórios com testes para consultas armazenadas no diretório `src`. Cada subdiretório contém código de teste e um arquivo de referência QL que especifica a consulta a ser testada.\n* `library-tests` uma série de subdiretórios com testes para arquivos da biblioteca QL. Cada subdiretório contém códigos de teste e consultas que foram gravadas como testes de unidade para uma biblioteca.\n\nDepois de criar o arquivo `qlpack.yml`, é necessário baixar todas as dependências e disponibilizá-las para a CLI. Faça isso executando o seguinte comando no mesmo diretório do arquivo `qlpack.yml`:\n\n```shell\ncodeql pack install\n```\n\nIsso gera um arquivo `codeql-pack.lock.yml` que especifica todas as dependências transitivas necessárias para executar consultas neste pacote. É preciso fazer check-in desse arquivo no controle do código-fonte.\n\n## Como configura os arquivos de teste para uma consulta\n\nPara cada consulta que você deseja testar, você deve criar um subdiretório no pacote de teste CodeQL .\nDepois, adicione os seguintes arquivos ao subdiretório antes de executar o comando de teste:\n\n* Um arquivo de referência de consulta (`.qlref` arquivo) que define o local da consulta a ser testada. O local é definido em relação à raiz do CodeQL pacote que contém a consulta. Normalmente, esse é um CodeQL pacote especificado no `dependencies` bloco do pacote de teste. Para obter mais informações, consulte [Arquivos de referência de consulta](/pt/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/query-reference-files).\n\n  Você não precisará adicionar um arquivo de referência de consulta se a consulta que deseja testar estiver armazenada no diretório de teste, mas uma boa prática é armazenar as consultas separadamente dos testes. A única exceção são os testes de unidade para bibliotecas QL, que costumam ser armazenados em pacotes de teste, separados das consultas que geram alertas ou caminhos.\n\n* O código de exemplo no qual você deseja executar a consulta. Isso deve consistir em um ou mais arquivos contendo exemplos de código que a consulta foi projetada para identificar.\n\nVocê também pode definir os resultados esperados ao executar a consulta no código de exemplo, criando um arquivo com a extensão `.expected`. Como alternativa, você pode deixar o comando de teste para criar o arquivo `.expected`.\n\nPara obter um exemplo mostrando como criar e testar uma consulta, veja o [exemplo](#example) abaixo.\n\n> \\[!NOTE]\n> Os seus arquivos `.ql`, `.qlref`, e `.expected` devem ter nomes consistentes:\n>\n> * Se você quiser especificar diretamente o próprio arquivo `.ql` no comando de teste, ele precisará ter o mesmo nome base que o arquivo correspondente `.expected`. Por exemplo, se a consulta for `MyJavaQuery.ql`, o arquivo de resultados esperado precisará ser `MyJavaQuery.expected`.\n> * Se você quiser especificar um arquivo `.qlref` no comando, ele deverá ter o mesmo nome base que o arquivo correspondente `.expected`, mas a consulta em si poderá ter um nome diferente.\n> * Os nomes dos arquivos de código de exemplo não precisam ser consistentes com os outros arquivos de teste. Todos os arquivos de código de exemplo encontrados ao lado do arquivo `.qlref` (ou `.ql`) e nos subdiretórios serão usados para criar um banco de dados de teste. Portanto, para simplificar, recomendamos que você não salve os arquivos de teste em diretórios que sejam ancestrais uns dos outros.\n\n## Em execução `codeql test run`\n\n```\n          CodeQL Os testes de consulta são executados executando o seguinte comando:\n```\n\n```shell\ncodeql test run <test|dir>\n```\n\nO argumento `<test|dir>` pode ser um ou mais destes:\n\n* Caminho para um arquivo `.ql`.\n* Caminho para um arquivo `.qlref` que faz referência a um arquivo `.ql`.\n* Caminho para um diretório que será pesquisado recursivamente para arquivos `.ql` e `.qlref`.\n\nVocê também pode especificar:\n\n* `--threads:` opcionalmente, o número de threads a serem usadas na execução de consultas. A opção padrão é `1`. Você pode especificar mais threads para acelerar a execução da consulta. A especificação `0` corresponde o número de threads ao número de processadores lógicos.\n\nPara obter detalhes completos sobre todas as opções que você pode usar ao testar consultas, consulte [execução de teste](/pt/code-security/codeql-cli/codeql-cli-manual/test-run).\n\n## Exemplo\n\nO exemplo a seguir mostra como configurar um teste para uma consulta que pesquisa código Java em busca de instruções `if` que tenham blocos vazios `then`. O procedimento inclui etapas para adicionar a consulta personalizada e os arquivos de teste correspondentes a CodeQL pacotes separados fora do checkout do CodeQL repositório . Isso garante que, ao atualizar as bibliotecas do CodeQL ou fazer check-out de uma ramificação diferente, você não substitua as consultas e os testes personalizados.\n\n### Preparar uma consulta e arquivos de teste\n\n1. Desenvolva a consulta. Por exemplo, a consulta simples a seguir localiza blocos vazios `then` no código Java:\n\n   ```shell\n   import java\n\n   from IfStmt ifstmt\n   where ifstmt.getThen() instanceof EmptyStmt\n   select ifstmt, \"This if statement has an empty then.\"\n   ```\n\n2. Salve a consulta em um arquivo chamado `EmptyThen.ql` em um diretório com outras consultas personalizadas. Por exemplo, `custom-queries/java/queries/EmptyThen.ql`.\n\n3. Se você ainda não adicionou suas consultas personalizadas a um CodeQL pacote, crie um CodeQL pacote agora. Por exemplo, se as consultas Java personalizadas forem armazenadas no `custom-queries/java/queries`, adicione um arquivo `qlpack.yml` com o seguinte conteúdo a `custom-queries/java/queries`:\n\n   ```yaml\n   name: my-custom-queries\n   dependencies:\n     codeql/java-queries: \"*\"\n   ```\n\n   Para obter mais informações sobre CodeQL pacotes, consulte [Como personalizar a análise com pacotes CodeQL](/pt/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs).\n\n4. Crie um CodeQL pacote para seus testes Java adicionando um arquivo `qlpack.yml` com o seguinte conteúdo em `custom-queries/java/tests`, atualizando o `dependencies` para corresponder ao nome do seu CodeQL pacote de consultas personalizadas:\n\n   O arquivo `qlpack.yml` a seguir informa que `my-github-user/my-query-tests` depende de `my-github-user/my-custom-queries` em uma versão igual ou superior a 1.2.3 e inferior a 2.0.0. Ele também declara que a CLI deve usar o Java `extractor` ao criar bancos de dados de teste. A linha `tests: .` declara que todos os arquivos `.ql` no pacote devem ser executados como testes quando `codeql test run` é executado com a opção `--strict-test-discovery`. Normalmente, os pacotes de teste não contêm uma propriedade `version`. Isso impede que você os publique acidentalmente.\n\n   ```yaml\n   name: my-github-user/my-query-tests\n   dependencies:\n     my-github-user/my-custom-queries: ^1.2.3\n   extractor: java-kotlin\n   tests: .\n   ```\n\n5. Execute `codeql pack install` na raiz do diretório de teste. Isso gera um arquivo `codeql-pack.lock.yml` que especifica todas as dependências transitivas necessárias para executar consultas neste pacote.\n\n6. No pacote de teste Java, crie um diretório para conter os arquivos de teste associados a `EmptyThen.ql`. Por exemplo, `custom-queries/java/tests/EmptyThen`.\n\n7. No novo diretório, crie `EmptyThen.qlref` para definir o local de `EmptyThen.ql`. O caminho para a consulta deve ser especificado em relação à raiz do CodeQL pacote que contém a consulta. Nesse caso, a consulta está no diretório de nível superior do CodeQL pacote do chamado `my-custom-queries`, que é declarado como uma dependência para `my-query-tests`. Portanto, `EmptyThen.qlref` deve simplesmente conter `EmptyThen.ql`.\n\n8. Crie um snippet de código para ser testado. O código Java a seguir contém uma instrução vazia `if` na terceira linha. Salve-o em `custom-queries/java/tests/EmptyThen/Test.java`.\n\n   ```java\n   class Test {\n     public void problem(String arg) {\n       if (arg.isEmpty())\n         ;\n       {\n         System.out.println(\"Empty argument\");\n       }\n     }\n\n     public void good(String arg) {\n       if (arg.isEmpty()) {\n         System.out.println(\"Empty argument\");\n       }\n     }\n   }\n   ```\n\n### Executar o teste\n\nPara executar o teste, acesse o diretório `custom-queries` e execute `codeql\ntest run java/tests/EmptyThen`.\n\nAo ser executado, o teste:\n\n1. Localizará um teste no diretório `EmptyThen`.\n\n2. Extrai o CodeQL banco de dados dos `.java` arquivos armazenados no `EmptyThen` diretório.\n\n3. Compilará a consulta referenciada pelo arquivo `EmptyThen.qlref`.\n\n   Se essa etapa falhar, é porque a CLI não consegue localizar seu pacote personalizado CodeQL . Execute novamente o comando e especifique o local do pacote personalizado CodeQL , por exemplo:\n\n   `codeql test run --search-path=java java/tests/EmptyThen`\n\n   Para obter informações sobre como salvar o caminho de pesquisa como parte da sua configuração, consulte [Como especificar opções de comando em um arquivo de configuração do CodeQL](/pt/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/specifying-command-options-in-a-codeql-configuration-file).\n\n4. Executará o teste executando a consulta e gerando um arquivo de resultados `EmptyThen.actual`.\n\n5. Verificará se há um arquivo `EmptyThen.expected` a ser comparado com o arquivo de resultados `.actual`.\n\n6. Relatará os resultados do teste. Neste caso, uma falha: `0 tests passed; 1 tests failed:`. O teste falhou porque ainda não adicionamos um arquivo com os resultados esperados da consulta.\n\n### Exibir a saída do teste de consulta\n\n```\n          CodeQL gera os seguintes arquivos no `EmptyThen` diretório:\n```\n\n* `EmptyThen.actual`, um arquivo que contém os resultados reais gerados pela consulta.\n* ```\n            `EmptyThen.testproj`, um banco de dados de teste que você pode carregar no VS Code e usar para depurar testes com falha. Quando os testes são concluídos com êxito, esse banco de dados é excluído em uma etapa de manutenção. Você pode substituir essa etapa executando `test run` com a opção `--keep-databases`.\n  ```\n\nNesse caso, a falha era esperada e fácil de ser corrigida. Se você abrir o arquivo `EmptyThen.actual`, verá os resultados do teste:\n\n```shell\n\n| Test.java:3:5:3:22 | stmt | This if statement has an empty then. |\n\n```\n\nEsse arquivo contém uma tabela, com uma coluna de local do resultado, juntamente com colunas separadas para cada parte da cláusula `select` que a consulta gera.\nComo os resultados são o esperado, podemos atualizar a extensão de arquivo para definir isso como o resultado esperado desse teste (`EmptyThen.expected`).\n\nSe você executar novamente o teste agora, a saída será semelhante, mas será concluída relatando: `All 1 tests passed.`.\n\nSe os resultados da consulta forem alterados, por exemplo, se você revisar a instrução `select` da consulta, o teste falhará. Para resultados com falha, a saída da CLI inclui uma comparação unificada dos arquivos `EmptyThen.expected` e `EmptyThen.actual`.\nEssas informações podem ser suficientes para depurar falhas de teste triviais.\n\nPara falhas mais difíceis de depurar, você pode importar `EmptyThen.testproj` para CodeQL no VS Code, executar `EmptyThen.ql` e exibir os resultados no código de exemplo `Test.java`. Para obter mais informações, consulte [Como gerenciar bancos de dados do CodeQL](/pt/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/managing-codeql-databases#choosing-a-database-to-analyze).\n\n## Leitura adicional\n\n* [\n  CodeQL consultas](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries)\n* [Testar consultas do CodeQL no Visual Studio Code](/pt/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/testing-codeql-queries-in-vs-code)."}