Skip to main content

Arquivos de referência de consulta

Você pode usar arquivos de referência de consulta para definir o local de uma consulta que deseja executar em testes.

Quem pode usar esse recurso?

O CodeQL do GitHub é licenciado por usuário após a instalação. Você pode usar o CodeQL somente para determinadas tarefas sob as restrições de licença. Para obter mais informações, confira "Sobre a CLI do CodeQL".

Se você tiver uma licença do GitHub Advanced Security, poderá usar o CodeQL para análise automatizada, integração contínua e entrega contínua. Para obter mais informações, confira "Sobre a Segurança Avançada do GitHub".

Sobre os arquivos de referência de consulta

Um arquivo de referência de consulta é um arquivo de texto que define o local de uma consulta a ser testada.

Use um arquivo de referência de consulta quando quiser instruir o subcomando test run a executar uma consulta que não faça parte de um diretório de teste. Há duas maneiras de especificar consultas que você deseja executar como testes:

  1. Use um arquivo de referência de consulta para especificar o local de uma consulta a ser testada. Isso é útil quando você cria testes para consultas de alerta e de caminho destinadas a identificar problemas em bases de código reais. Você pode criar vários diretórios de código de teste, cada um com foco em diferentes aspectos da consulta. Depois, você adicionaria um arquivo de referência de consulta a cada diretório de código de teste para especificar a consulta a ser testada.
  2. Adicione a consulta diretamente a um diretório de testes. Isso é útil quando você está escrevendo consultas explicitamente para testar o comportamento das bibliotecas do QL. Geralmente, essas consultas contêm apenas algumas chamadas para predicados de biblioteca, encapsulando-as em uma instrução select para que a saída possa ser testada.

Como definir um arquivo de referência de consulta

Cada arquivo de referência de consulta, .qlref, contém uma só linha que define onde encontrar uma consulta. O local precisa ser definido em relação à raiz do pacote CodeQL que contém a consulta. Normalmente, esse é o pacote do CodeQL que contém o .qlref, um pacote do CodeQL especificado no bloco dependencies do pacote de teste ou uma dependência transitiva do pacote CodeQL.

Você deve usar barras "/" no caminho em todos os sistemas operacionais para garantir a compatibilidade entre os sistemas.

Exemplo

Um arquivo de referência de consulta para testar uma consulta de alerta do JavaScript: DeadAngularJSEventListener.qlref

O qlpack.yml arquivo https://github.com/github/codeql/blob/main/javascript/ql/test/qlpack.yml para o pacote CodeQL em javascript/ql/test define codeql/javascript-queries como uma dependência. Portanto, o arquivo de referência de consulta define o local da consulta em relação ao pacote codeql/javascript-queries do CodeQL:

AngularJS/DeadAngularJSEventListener.ql

Para ver outro exemplo, confira "Testar consultas personalizadas".