test run

Synopsis

codeql test run [--threads=<num>] [--ram=<MB>] <options>... -- <test|dir>...

codeql test run [--threads=<num>] [--ram=<MB>] <options>... -- <test|dir>...

Description

Exécute des tests unitaires pour les requêtes QL.

Options

Options principales

<test|dir>...

Chaque argument est l’un des éléments suivants :

• Fichier .ql ou .qlref qui définit un test à exécuter.
• Répertoire dans lequel les tests à exécuter sont recherchés de façon récursive.

--failing-exitcode=<code>

[Avancé] Définit le code de sortie à produire en cas d’échec. Généralement 1, mais les outils qui analysent la sortie peuvent trouver utile de la définir sur 0.

--format=<fmt>

Sélectionne le format de sortie. Choix possibles :

text (par défaut)  : Rendu textuel lisible par les êtres humains.

json : tableau JSON des objets de résultat de test diffusé en continu.

betterjson : tableau JSON des objets d’événements diffusé en continu.

jsonz : flux d’objets de résultat de test JSON se terminant par zéro.

betterjsonz : flux d’objets d’événements JSON se terminant par zéro.

Pour les formats betterjson et betterjsonz, chaque événement a une propriété type spécifiant le type de l’événement. De nouveaux types d’événements peuvent être ajoutés à l’avenir. Les consommateurs doivent donc ignorer tout événement avec une propriété kind non reconnue.

--[no-]keep-databases

[Avancé] Conserve les bases de données extraites pour exécuter les requêtes de test, même si tous les tests d’un répertoire réussissent. (La base de données reste toujours présente quand des tests échouent.)

--[no-]fast-compilation

[Déprécié] [Avancé] Omet les étapes d’optimisation particulièrement lentes lors de la compilation des requêtes de test.

--[no-]learn

[Avancé] Lorsqu’un test produit une sortie inattendue, au lieu de le mettre en échec, met à jour son fichier .expected pour le faire correspondre à la sortie actuelle et ainsi le faire réussir. Les tests peuvent quand même échouer dans ce mode, par exemple si la création d’une base de données de test à interroger ne réussit pas.

--consistency-queries=<dir>

[Avancé] Répertoire avec des requêtes de cohérence qui seront exécutées pour chaque base de données de test. Ces requêtes ne doivent pas produire de sortie (sauf lorsqu’elles rencontrent un problème), sauf si le répertoire de test inclut un sous-répertoire CONSISTENCY avec un fichier .expected. Cette option est principalement utile pour tester les extracteurs.

--[no-]check-databases

[Avancé] Exécute codeql dataset check sur chaque base de données de test créée et signale un échec si elle détecte des incohérences. Cette option est utile lors du test des extracteurs. Si la vérification est (temporairement !) censée échouer pour une base de données en particulier, placez un fichier DB-CHECK.expected dans le répertoire de test.

--[no-]show-extractor-output

[Avancé] Affiche la sortie des scripts d’extracteur qui créent les bases de données de test. Peut être utile lors du développement ou de la modification de cas de test. Attention, cela peut générer une sortie dupliquée ou incorrecte si vous l’utilisez avec plusieurs threads !

-M, --ram=<MB>

Définit la quantité totale de RAM que l’exécuteur de test doit être autorisé à utiliser.

--slice=<N/M>

[Avancé] Divisez les cas de test en M tranches de taille à peu près égale et ne traitez que le Nth d’entre elles. Cela peut être utilisé pour la parallélisation manuelle du processus de test.

--[no-]strict-test-discovery

[Avancé] Utilise uniquement des requêtes qui peuvent être fortement identifiées en tant que tests. Ce mode tente de faire la distinction entre les fichiers .ql qui définissent des tests unitaires et les fichiers .ql destinés à être des requêtes utiles. Cette option est utilisée par les outils, tels que les IDE, qui doivent identifier tous les tests unitaires dans une arborescence de répertoires sans avoir besoin de savoir au préalable comment les fichiers y sont organisés.

Dans un pack QL dont qlpack.yml déclare un répertoire tests, tous les fichiers de ce répertoire sont considérés comme des tests, et les fichiers .ql et .ql en dehors de celui-ci sont ignorés. Dans un pack QL qui ne déclare pas de répertoire tests, un fichier .ql est identifié comme test uniquement s’il a un fichier .expected correspondant.

À des fins de cohérence, les fichiers .qlref sont limités par les mêmes règles que les fichiers .ql, même si un fichier .qlref ne peut pas vraiment être un non-test.

Options pour rechercher les bibliothèques et les extracteurs utilisés par les tests

--search-path=<dir>[:<dir>...]

Liste des répertoires sous lesquels les packs QL peuvent être trouvés. Chaque répertoire peut être un pack QL (ou un bundle de packs contenant un fichier .codeqlmanifest.json à la racine) ou le parent immédiat d’un ou plusieurs de ces répertoires.

Si le chemin contient plusieurs répertoires, leur ordre définit la priorité entre eux : quand un nom de pack qui doit être résolu est mis en correspondance dans plusieurs arborescences de répertoires, celle donnée en premier gagne.

Le pointage de ce chemin vers une extraction du dépôt CodeQL open source devrait fonctionner lors de l’interrogation d’un des langages qui y résident.

Si vous avez extrait le dépôt CodeQL en tant que frère de la chaîne d’outils CodeQL décompressée, vous n’avez pas besoin de donner cette option ; ces répertoires frères sont toujours recherchés pour les packs QL qui ne peuvent pas être trouvés autrement. (Si cette valeur par défaut ne fonctionne pas, il est fortement recommandé de configurer --search-path une fois pour toutes dans un fichier de configuration par utilisateur).

(Remarque : Sur Windows, le séparateur de chemin est ;.)

--additional-packs=<dir>[:<dir>...]

Si cette liste de répertoires est donnée, des packs y sont recherchés avant ceux indiqués dans --search-path. L’ordre entre eux n’a pas d’importance ; il s’agit d’une erreur si un nom de pack est trouvé dans deux répertoires différents de cette liste.

Cette option est utile si vous développez temporairement une nouvelle version d’un pack qui apparaît aussi dans le chemin par défaut. En revanche, il n’est pas recommandé de remplacer cette option dans un fichier de configuration ; certaines actions internes ajoutent cette option à la volée, remplaçant toute valeur configurée.

(Remarque : Sur Windows, le séparateur de chemin est ;.)

--library-path=<dir>[:<dir>...]

[Avancé] Liste facultative des répertoires qui sont ajoutés au chemin de recherche d’importation brut pour les bibliothèques QL. Doit être utilisé seulement si vous utilisez des bibliothèques QL qui n’ont pas été empaquetées en tant que packs QL.

(Remarque : Sur Windows, le séparateur de chemin est ;.)

--dbscheme=<file>

[Avancé] Définit explicitement les requêtes de schéma de base de données à compiler. Ne doit être donné que par les appelants qui sont extrêmement sûrs de ce qu’ils font.

--compilation-cache=<dir>

[Avancé] Spécifie un répertoire supplémentaire à utiliser comme cache de compilation.

--no-default-compilation-cache

[Avancé] N’utilise pas de caches de compilation dans des emplacements standard, comme dans le pack QL contenant la requête ou dans le répertoire de la chaîne d’outils CodeQL.

Options pour configurer le gestionnaire de package CodeQL

--registries-auth-stdin

Permet de vous authentifier auprès des registres de conteneurs GitHub Enterprise Server en passant une liste de paires <registry_url>=<token> séparées par des virgules.

Par exemple, vous pouvez passer https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2 pour vous authentifier auprès de deux instances GitHub Enterprise Server.

Cela remplace les variables d’environnement CODEQL_REGISTRIES_AUTH et GITHUB_TOKEN. Si vous avez seulement besoin de vous authentifier auprès du registre de conteneurs github.com, vous pouvez vous authentifier en utilisant l’option plus simple --github-auth-stdin.

--github-auth-stdin

Permet de vous authentifier auprès du registre de conteneurs github.com en passant un jeton github.com GitHub Apps ou un jeton d’accès personnel via une entrée standard.

Pour vous authentifier auprès des registres de conteneurs GitHub Enterprise Server, passez --registries-auth-stdin ou utilisez la variable d’environnement CODEQL_REGISTRIES_AUTH.

Cela remplace la variable d’environnement GITHUB_TOKEN.

Options pour contrôler la compilation de requête

--no-release-compatibility

[Avancé] Utilise les fonctionnalités les plus récentes du compilateur, au détriment de la portabilité.

Parfois, les nouvelles fonctionnalités du langage QL et les optimisations de l’évaluateur sont prises en charge par l’évaluateur QL quelques versions avant qu’elles ne soient activées par défaut dans le compilateur QL. Cela permet de garantir que les performances dont vous bénéficiez lors du développement de requêtes dans la dernière version de CodeQL peuvent être atteintes par des versions légèrement plus anciennes qui peuvent encore être utilisées pour l’Analyse du code ou les intégrations CI.

Si la compatibilité de vos requêtes avec d’autres versions (antérieures ou ultérieures) de CodeQL n’est pas un souci pour vous, vous pouvez parfois atteindre des performances un peu meilleures en utilisant cet indicateur pour activer les améliorations récentes du compilateur dès le début.

Dans les versions pour lesquelles il n’y a pas d’améliorations récentes à activer, cette option ne fait rien. Par conséquent, vous pouvez sans problème la définir une fois pour toutes dans votre fichier de configuration CodeQL global.

Disponible depuis v2.11.1.

Options qui contrôlent l’évaluation des requêtes de test

--[no-]tuple-counting

[Avancé] Affiche le nombre de tuples pour chaque étape d’évaluation dans les journaux de l’évaluateur de requêtes. Si l’option --evaluator-log est fournie, les nombres de tuples sont inclus dans les journaux JSON textuels et structurés générés par la commande. (Cela peut être utile pour l’optimisation des performances du code QL complexe.)

--timeout=<seconds>

[Avancé] Définit la durée du délai d’expiration pour l’évaluation de la requête, en secondes.

La fonctionnalité de délai d’expiration est destinée à intercepter les cas où l’évaluation d’une requête complexe durerait « indéfiniment ». Il ne s’agit pas d’un moyen efficace de limiter la durée totale de l’évaluation de la requête. L’évaluation est autorisée à se poursuivre tant que chaque partie du calcul se termine dans le délai d’expiration qui lui a été imparti séparément. Pour l’instant, ces parties sont des « couches RA » de la requête optimisée, mais cela peut changer.

Si aucun délai d’expiration n’est spécifié ou que 0 est fourni, aucun délai n’est défini (sauf pour codeql test run, où le délai d’expiration par défaut est de 5 minutes).

-j, --threads=<num>

Utilise le nombre de threads spécifié pour évaluer les requêtes.

La valeur par défaut est de 1. Vous pouvez passer 0 pour utiliser un thread par cœur sur la machine ou -N pour laisser N cœurs inutilisés (sauf si au moins un thread est toujours utilisé).

Options pour contrôler la sortie des journaux structurés de l’évaluateur

--evaluator-log=<file>

[Avancé] Génère des journaux structurés sur les performances de l’évaluateur dans le fichier donné. Le format de ce fichier journal est susceptible d’être modifié sans préavis, mais il s’agit d’un flux d’objets JSON séparés par deux caractères de nouvelle ligne (par défaut) ou un seul si l’option --evaluator-log-minify est transmise. Utilisez codeql generate log-summary <file> pour produire un résumé plus stable de ce fichier et évitez d’analyser le fichier directement. Le fichier est remplacé, s’il existe déjà.

--evaluator-log-minify

[Avancé] Si l’option --evaluator-log est transmise, le passage de cette option réduit également la taille du journal JSON produit, mais celui-ci devient beaucoup moins lisible par les êtres humains en contrepartie.

Options pour vérifier les fichiers TRAP importés

--[no-]check-undefined-labels

[Avancé] Signale les erreurs pour les étiquettes non définies.

--[no-]check-unused-labels

[Avancé] Signale les erreurs pour les étiquettes non utilisées.

--[no-]check-repeated-labels

[Avancé] Signale les erreurs pour les étiquettes répétées.

--[no-]check-redefined-labels

[Avancé] Signale les erreurs pour les étiquettes redéfinies.

--[no-]check-use-before-definition

[Avancé] Signale les erreurs pour les étiquettes utilisées avant leur définition.

--[no-]fail-on-trap-errors

[Avancé] Sort une valeur non nulle si une erreur se produit lors de l’importation d’un fichier TRAP.

--[no-]include-location-in-star

[Avancé] Construit des ID d’entité qui encodent l’emplacement dans le fichier TRAP dont ils proviennent. Peut être utile pour le débogage des générateurs TRAP, mais prend beaucoup d’espace dans le jeu de données.

--[no-]linkage-aware-import

[Avancé] Contrôle si l’importation de jeu de données codeql prend en compte les liaisons (par défaut) ou non. Sur les projets dans lesquels cette partie de la création de base de données consomme trop de mémoire, la désactivation de cette option peut les aider à progresser au détriment de la complétion de la base de données.

Disponible depuis v2.15.3.

Options courantes

-h, --help

Affiche ce texte d’aide.

-J=<opt>

[Avancé] Donne une option à l’environnement JVM exécutant la commande.

(Attention, les options contenant des espaces ne sont pas gérées correctement.)

-v, --verbose

Augmente de façon incrémentielle le nombre de messages de progression affichés.

-q, --quiet

Diminue de façon incrémentielle le nombre de messages de progression affichés.

--verbosity=<level>

[Avancé] Définit explicitement le niveau de détail sur errors, warnings, progress, progress+, progress++ ou progress+++. Remplace -v et -q.

--logdir=<dir>

[Avancé] Écrit des journaux détaillés dans un ou plusieurs fichiers du répertoire donné, avec des noms générés qui incluent des horodatages et le nom de la sous-commande en cours d’exécution.

(Pour écrire un fichier journal avec un nom sur lequel vous avez un contrôle total, donnez plutôt --log-to-stderr et redirigez stderr comme vous le souhaitez.)

--common-caches=<dir>

[Avancé] Contrôle l’emplacement des données en cache sur le disque qui persisteront entre plusieurs exécutions de l’interface CLI, telles que les packs QL téléchargés et les plans de requête compilés. S’il n’est pas défini explicitement, il s’agit par défaut d’un répertoire nommé .codeql dans le répertoire de base de l’utilisateur. S’il n’existe pas déjà, il est créé.

Disponible depuis v2.15.2.