Abfragereferenzdateien

Informationen zu Abfragereferenzdateien

Eine Abfragereferenzdatei ist eine Textdatei, die den Speicherort einer zu testenden Abfrage definiert.

Du verwendest eine Abfragereferenzdatei, wenn du den Unterbefehl test run anweisen möchtest, eine Abfrage auszuführen, die nicht Teil eines Testverzeichnisses ist. Es gibt zwei Möglichkeiten, Abfragen anzugeben, die du als Tests ausführen möchtest:

1. Du verwendest eine Abfragereferenzdatei, um den Speicherort einer Abfrage anzugeben, die getestet werden soll. Dies ist nützlich, wenn du Tests für Warnungs- und Pfadabfragen erstellst, die Probleme in echten Codebases identifizieren sollen. Du kannst mehrere Verzeichnisse mit Testcode erstellen, die sich jeweils auf unterschiedliche Aspekte der Abfrage konzentrieren. Anschließend fügst du jedem Verzeichnis mit Testcode eine Abfragereferenzdatei hinzu, um die zu testende Abfrage anzugeben.
2. Du fügst die Abfrage direkt einem Verzeichnis von Tests hinzu. Dies ist in der Regel nützlich, wenn du Abfragen explizit schreibst, um das Verhalten von QL-Bibliotheken zu testen. Häufig enthalten diese Abfragen nur einige Aufrufe von Bibliotheksprädikaten, die sie in eine select-Anweisung einschließen, damit ihre Ausgabe getestet werden kann.

Definieren einer Abfragereferenzdatei

Jede Abfragereferenzdatei (.qlref) enthält eine einzelne Zeile, die definiert, wo eine Abfrage zu finden ist. Der Speicherort muss relativ zum Stamm des CodeQL-Pakets definiert werden, das die Abfrage enthält. In der Regel handelt es sich entweder um das CodeQL-Paket, das die Abfragereferenzdatei (.qlref) enthält, ein im dependencies-Block für das Testpaket angegebenes CodeQL-Paket oder eine transitive Abhängigkeit des CodeQL-Pakets.

Du solltest auf allen Betriebssystemen Schrägstriche im Pfad verwenden, um die Kompatibilität zwischen den Systemen sicherzustellen.

Beispiel

Abfragereferenzdatei zum Testen einer JavaScript-Warnungsabfrage: DeadAngularJSEventListener.qlref

Die qlpack.yml-Datei https://github.com/github/codeql/blob/main/javascript/ql/test/qlpack.yml für das CodeQL-Paket in javascript/ql/test definiert codeql/javascript-queries als Abhängigkeit. Daher definiert die Abfragereferenzdatei den Speicherort der Abfrage relativ zum CodeQL-Paket codeql/javascript-queries:

AngularJS/DeadAngularJSEventListener.ql

Ein weiteres Beispiel findest du unter Testen benutzerdefinierter Abfragen.