Skip to main content
GitHub Docs
Search
Select language: current language is English
Open Search BarClose Search Bar
Open Menu
Open Sidebar
  • Secure coding/
  • GitHub security features
  • Audit security alerts
  • Enable security features in trial
  • Choose security configuration
    • Configure global settings
    • Edit custom configuration
    • Delete custom configuration
    • Push protection
    • Enable push protection
    • Resolve alerts
    • Push protection from the REST API
    • Generate regular expressions with AI
    • About CodeQL code scanning
    • Configure advanced setup
    • Hardware resources for CodeQL
    • Disable Copilot Autofix
    • Track alerts in issues
    • CodeQL query suites
    • C# CodeQL queries
    • Python CodeQL queries
    • Using code scanning with your existing CI system
    • Alerts in generated code
    • Cannot enable CodeQL in a private repository
    • Logs not detailed enough
    • Resource not accessible
    • Two CodeQL workflows
    • GitHub Advanced Security disabled
    • Results file too large
    • Preparing code for analysis
    • Advanced setup of the CodeQL CLI
    • Testing custom queries
    • Specifying command options in a CodeQL configuration file
    • Extractor options
    • bqrs diff
    • database add-diagnostic
    • database create
    • database index-files
    • database run-queries
    • dataset check
    • dataset upgrade
    • execute language-server
    • execute upgrades
    • github merge-results
    • pack ci
    • pack install
    • pack resolve-dependencies
    • query format
    • resolve extensions-by-pack
    • resolve library-path
    • resolve qlpacks
    • resolve tests
    • test run
    • Manage CodeQL databases
    • CodeQL model editor
    • Test CodeQL queries
    • Telemetry
    • About global security advisories
    • Permission levels
    • Edit repository advisories
    • Add collaborators
    • Best practices
    • Dependency graph
    • Export dependencies as SBOM
    • Customize dependency review action
    • Overview
    • Dependabot ecosystem support
    • Configure notifications
    • Manage auto-dismissed alerts
    • Dependabot version updates
    • Control dependency update
    • Auto-update actions
    • Manage Dependabot on self-hosted runners
    • Troubleshoot Dependabot on Actions
    • Advanced functionality/
    • Query reference files

    Query reference files

    You can use query reference files to define the location of a query you want to run in tests.

    Who can use this feature?

    CodeQL is available for the following repository types:

    • Public repositories on GitHub.com, see GitHub CodeQL Terms and Conditions

    In this article

    • About query reference files
    • Defining a query reference file

    About query reference files

    A query reference file is text file that defines the location of one query to test.

    You use a query reference file when you want to tell the test run subcommand to run a query that’s not part of a test directory. There are two ways to specify queries that you want to run as tests:

    1. Use a query reference file to specify the location of a query to test. This is useful when you create tests for alert and path queries that are intended to identify problems in real codebases. You might create several directories of test code, each focusing on different aspects of the query. Then you would add a query reference file to each directory of test code, to specify the query to test.
    2. Add the query directly to a directory of tests. These is typically useful when you’re writing queries explicitly to test the behavior of QL libraries. Often these queries contain just a few calls to library predicates, wrapping them in a select statement so their output can be tested.

    Defining a query reference file

    Each query reference file, .qlref, contains a single line that defines where to find one query. The location must be defined relative to the root of the CodeQL pack that contains the query. Usually, this is either the CodeQL pack that contains the .qlref, a CodeQL pack specified in the dependencies block for the test pack, or a transitive dependency of the CodeQL pack.

    You should use forward slashes in the path on all operating systems to ensure compatibility between systems.

    Example

    A query reference file to test a JavaScript alert query: DeadAngularJSEventListener.qlref

    The qlpack.yml file, https://github.com/github/codeql/blob/main/javascript/ql/test/qlpack.yml, for the CodeQL pack at javascript/ql/test defines codeql/javascript-queries as a dependency. So the query reference file defines the location of the query relative to the codeql/javascript-queries CodeQL pack:

    AngularJS/DeadAngularJSEventListener.ql

    For another example, see

    Follow Lee on X/Twitter - Father, Husband, Serial builder creating AI, crypto, games & web tools. We are friends :) AI Will Come To Life!

    Check out: eBank.nz (Art Generator) | Netwrck.com (AI Tools) | Text-Generator.io (AI API) | BitBank.nz (Crypto AI) | ReadingTime (Kids Reading) | RewordGame | BigMultiplayerChess | WebFiddle | How.nz | Helix AI Assistant