{"meta":{"title":"Query reference files","intro":"You can use query reference files to define the location of a query you want to run in tests.","product":"Security and code quality","breadcrumbs":[{"href":"/en/enterprise-cloud@latest/code-security","title":"Security and code quality"},{"href":"/en/enterprise-cloud@latest/code-security/concepts","title":"Concepts"},{"href":"/en/enterprise-cloud@latest/code-security/concepts/code-scanning","title":"Code scanning"},{"href":"/en/enterprise-cloud@latest/code-security/concepts/code-scanning/codeql","title":"CodeQL"},{"href":"/en/enterprise-cloud@latest/code-security/concepts/code-scanning/codeql/query-reference-files","title":"Query reference files"}],"documentType":"article"},"body":"# Query reference files\n\nYou can use query reference files to define the location of a query you want to run in tests.\n\n## About query reference files\n\nA query reference file is text file that defines the location of one query to test.\n\nYou use a query reference file when you want to tell the `test run` subcommand\nto run a query that’s not part of a test directory.\nThere are two ways to specify queries that you want to run as tests:\n\n1. Use a query reference file to specify the location of a query to test.\n   This is useful when you create tests for alert and path queries that\n   are intended to identify problems in real codebases. You might create\n   several directories of test code, each focusing on different\n   aspects of the query. Then you would add a query reference file to\n   each directory of test code, to specify the query to test.\n2. Add the query directly to a directory of tests.\n   These is typically useful when you’re writing queries explicitly to test the behavior\n   of QL libraries. Often these queries contain just a few calls to library predicates,\n   wrapping them in a `select` statement so their output can be tested.\n\n## Defining a query reference file\n\nEach query reference file, `.qlref`, contains a single line that defines\nwhere to find one query. The location must be defined relative\nto the root of the CodeQL pack that contains the query.\nUsually, 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.\n\nYou should use forward slashes in the path on all operating\nsystems to ensure compatibility between systems.\n\n### Example\n\nA query reference file to test a JavaScript alert query:\n[DeadAngularJSEventListener.qlref](https://github.com/github/codeql/blob/main/javascript/ql/test/query-tests/AngularJS/DeadAngularJSEventListener/DeadAngularJSEventListener.qlref)\n\nThe `qlpack.yml` file, <https://github.com/github/codeql/blob/main/javascript/ql/test/qlpack.yml>,\nfor the CodeQL pack at `javascript/ql/test` defines `codeql/javascript-queries` as\na dependency. So the query reference file defines the location of the query relative\nto the `codeql/javascript-queries` CodeQL pack:\n\n```shell\nAngularJS/DeadAngularJSEventListener.ql\n```\n\nFor another example, see [Testing custom queries](/en/enterprise-cloud@latest/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries)."}