Aller au contenu principal
Version : Suivant

Options CLI de Jest

Traduction Bêta Non Officielle

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

L'exécuteur en ligne de commande jest propose plusieurs options utiles. Vous pouvez exécuter jest --help pour voir toutes les options disponibles. Beaucoup des options présentées ci-dessous peuvent également être combinées pour exécuter vos tests exactement comme vous le souhaitez. Toutes les options de Configuration de Jest peuvent également être spécifiées via la CLI.

Voici un aperçu rapide :

Exécution depuis la ligne de commande​

Exécuter tous les tests (par défaut) :

jest

Exécuter uniquement les tests spécifiés par un motif ou un nom de fichier :

jest my-test #or
jest path/to/my-test.js

Exécuter les tests liés aux fichiers modifiés (fichiers non commités) via hg/git :

jest -o

Exécuter les tests liés à path/to/fileA.js et path/to/fileB.js :

jest --findRelatedTests path/to/fileA.js path/to/fileB.js

Exécuter les tests correspondant à ce nom de spécification (correspond au nom dans describe ou test).

jest -t name-of-spec

Lancer le mode watch :

jest --watch #runs jest -o by default
jest --watchAll #runs all tests

Le mode watch permet également de spécifier le nom ou le chemin d'un fichier pour se concentrer sur un ensemble spécifique de tests.

Utilisation avec un gestionnaire de paquets​

Si vous exécutez Jest via votre gestionnaire de paquets, vous pouvez quand même passer les arguments de ligne de commande directement à Jest.

Au lieu de :

jest -u -t="ColorPicker"

vous pouvez utiliser :

npm test -- -u -t="ColorPicker"

Support des arguments camelCase et kebab-case​

Jest prend en charge les formats d'arguments camelCase et kebab-case. Les exemples suivants produiront le même résultat :

jest --collect-coverage
jest --collectCoverage

Les arguments peuvent également être mélangés :

jest --update-snapshot --detectOpenHandles

Options​

note

Les options CLI ont priorité sur les valeurs de la Configuration.

Référence​

jest <regexForTestFiles>​

Lorsque vous exécutez jest avec un argument, celui-ci est traité comme une expression régulière pour filtrer les fichiers de votre projet. Vous pouvez exécuter des suites de tests en fournissant un motif. Seuls les fichiers correspondant au motif seront exécutés. Selon votre terminal, vous devrez peut-être mettre cet argument entre guillemets : jest "my.*(complex)?pattern". Sous Windows, utilisez / comme séparateur de chemin ou échappez \ avec \\.

--bail[=<n>]​

Alias : -b. Quitte immédiatement la suite de tests après n échecs de suite de tests. Par défaut 1.

--cache​

Active ou non le cache. Par défaut true. Désactivez le cache avec --no-cache.

attention

Le cache ne devrait être désactivé qu'en cas de problèmes liés à la mise en cache. En moyenne, désactiver le cache rend Jest au moins deux fois plus lent.

Pour inspecter le cache, utilisez --showConfig et cherchez la valeur cacheDirectory. Pour vider le cache, utilisez --clearCache.

--changedFilesWithAncestor​

Exécute les tests liés aux changements actuels et aux modifications du dernier commit. Comportement similaire à --onlyChanged.

--changedSince​

Exécute les tests liés aux modifications depuis la branche ou le hash de commit fourni. Si la branche courante a divergé de la branche donnée, seuls les changements locaux seront testés. Comportement similaire à --onlyChanged.

--ci​

Lorsque cette option est activée, Jest suppose qu'il s'exécute dans un environnement CI. Cela modifie le comportement lorsqu'un nouveau snapshot est rencontré : au lieu de le stocker automatiquement, le test échoue et nécessite d'exécuter Jest avec --updateSnapshot.

--clearCache​

Supprime le répertoire de cache de Jest puis quitte sans exécuter les tests. Supprime cacheDirectory si l'option est fournie, ou le répertoire de cache par défaut de Jest. Le répertoire de cache par défaut peut être trouvé en exécutant jest --showConfig.

attention

Vider le cache réduira les performances.

--clearMocks​

Efface automatiquement les appels, instances, contextes et résultats des mocks avant chaque test. Équivalent à appeler jest.clearAllMocks() avant chaque test. Cela ne supprime aucune implémentation de mock qui aurait pu être fournie.

--collectCoverageFrom=<glob>​

Un motif glob relatif à rootDir correspondant aux fichiers depuis lesquels les informations de couverture doivent être collectées.

--colors​

Force la mise en évidence des résultats de test même si stdout n'est pas un TTY.

note

Alternativement, vous pouvez définir la variable d'environnement FORCE_COLOR=true pour activer forcément ou FORCE_COLOR=false pour désactiver la sortie colorée. L'utilisation de FORCE_COLOR prime sur toutes les autres vérifications de support couleur.

--config=<path>​

Alias : -c. Le chemin vers un fichier de configuration Jest spécifiant comment trouver et exécuter les tests. Si aucun rootDir n'est défini dans la configuration, le répertoire contenant le fichier de config est considéré comme le rootDir du projet. Peut aussi être une valeur encodée en JSON que Jest utilisera comme configuration.

--coverage[=<boolean>]​

Alias : --collectCoverage. Indique que les informations de couverture de test doivent être collectées et rapportées dans la sortie. Passez optionnellement <boolean> pour surcharger l'option définie dans la configuration.

--coverageDirectory=<path>​

Le répertoire où Jest doit écrire ses fichiers de couverture.

--coverageProvider=<provider>​

Indique quel fournisseur utiliser pour instrumenter le code en vue de la couverture. Les valeurs autorisées sont babel (par défaut) ou v8.

--debug​

Affiche des informations de débogage sur votre configuration Jest.

--detectOpenHandles​

Tente de collecter et d'afficher les handles ouverts empêchant Jest de quitter proprement. Utilisez ceci dans les cas où vous devez utiliser --forceExit pour que Jest quitte, afin de potentiellement identifier la cause. Implique --runInBand, faisant s'exécuter les tests en série. Implémenté via async_hooks. Cette option impacte significativement les performances et doit être réservée au débogage.

--env=<environment>​

L'environnement de test utilisé pour tous les tests. Peut pointer vers n'importe quel fichier ou module node. Exemples : jsdom, node ou path/to/my-environment.js.

--errorOnDeprecated​

Fait en sorte que l'appel d'APIs obsolètes génère des messages d'erreur utiles. Facilité la migration vers des versions plus récentes.

--expand​

Alias : -e. Utilisez ce drapeau pour afficher les diffs complets et les erreurs au lieu d'un patch.

--filter=<file>​

Chemin vers un module exportant une fonction de filtrage. Cette fonction asynchrone reçoit une liste de chemins de tests qu'elle peut manipuler pour exclure des tests de l'exécution, et doit retourner un objet de forme { filtered: Array<string> } contenant les tests que Jest doit exécuter. Particulièrement utile avec une infrastructure de test pour filtrer les tests connus comme cassés.

my-filter.js
// This filter when applied will only run tests ending in .spec.js (not the best way to do it, but it's just an example):
const filteringFunction = testPath => testPath.endsWith('.spec.js');

module.exports = testPaths => {
  const allowedPaths = testPaths.filter(filteringFunction); // ["path1.spec.js", "path2.spec.js", etc]

  return {
    filtered: allowedPaths,
  };
};

--findRelatedTests <spaceSeparatedListOfSourceFiles>​

Trouve et exécute les tests couvrant une liste de fichiers sources séparés par des espaces passés en arguments. Utile pour l'intégration dans des hooks pre-commit afin d'exécuter le strict minimum de tests nécessaires. Peut être utilisé avec --coverage pour inclure la couverture de test des fichiers sources, sans besoin de dupliquer les arguments --collectCoverageFrom.

--forceExit​

Force Jest à quitter après l'exécution complète de tous les tests. Utile lorsque les ressources configurées par le code de test ne peuvent être correctement nettoyées.

attention

Cette fonctionnalité est une échappatoire. Si Jest ne quitte pas à la fin d'une série de tests, cela signifie que des ressources externes sont encore retenues ou que des minuteries sont en attente dans votre code. Il est conseillé de démonter les ressources externes après chaque test pour garantir une fermeture propre de Jest. Utilisez --detectOpenHandles pour aider à localiser le problème.

--help​

Affiche les informations d'aide, similaires à cette page.

--ignoreProjects <project1> ... <projectN>​

Ignore les tests des projets spécifiés. Jest utilise l'attribut displayName dans la configuration pour identifier chaque projet. Si vous utilisez cette option, fournissez un displayName à tous vos projets.

--injectGlobals​

Injecte les variables globales de Jest (expect, test, describe, beforeEach, etc.) dans l'environnement global. Si vous définissez cette option sur false, vous devez les importer depuis @jest/globals, par exemple :

import {expect, jest, test} from '@jest/globals';

jest.useFakeTimers();

test('some test', () => {
  expect(Date.now()).toBe(0);
});
note

Cette option n'est prise en charge qu'avec le runner de test par défaut jest-circus.

--json​

Imprime les résultats des tests au format JSON. Ce mode redirige toutes les autres sorties de test et messages utilisateur vers stderr.

--lastCommit​

Exécute tous les tests affectés par les modifications de fichiers du dernier commit. Se comporte comme --onlyChanged.

--listTests​

Liste tous les fichiers de tests que Jest exécutera avec les arguments fournis, puis quitte.

--logHeapUsage​

Enregistre l'utilisation du tas après chaque test. Utile pour déboguer les fuites mémoire. À utiliser avec --runInBand et --expose-gc dans node.

--maxConcurrency=<num>​

Empêche Jest d'exécuter plus que le nombre spécifié de tests simultanément. Affecte uniquement les tests utilisant test.concurrent.

--maxWorkers=<num>|<string>​

Alias : -w. Spécifie le nombre maximum de workers que le pool créera pour exécuter les tests. En mode single run, par défaut égal au nombre de cœurs disponibles moins un (pour le thread principal). En mode watch, par défaut la moitié des cœurs disponibles pour éviter la surcharge. Ajustez cette valeur dans les environnements limités (comme les CI), mais les valeurs par défaut conviennent à la plupart des cas.

Pour les environnements à nombre variable de CPU, utilisez une configuration en pourcentage : --maxWorkers=50%

--noStackTrace​

Désactive les traces de pile dans les résultats des tests.

--notify​

Active les notifications natives du système d'exploitation pour les résultats de tests. Idéal quand vous voulez vous concentrer exclusivement sur les tests JavaScript. Nécessite le package node-notifier, à installer séparément.

--onlyChanged​

Alias : -o. Tente d'identifier les tests à exécuter en fonction des fichiers modifiés dans le dépôt actuel. Nécessite un dépôt git/hg et un graphe de dépendances statique (sans require dynamique).

--onlyFailures​

Alias : -f. Exécute les tests ayant échoué lors de la précédente exécution.

--openHandlesTimeout=<milliseconds>​

Lorsque --detectOpenHandles et --forceExit sont désactivés, Jest affichera un avertissement si le processus ne s'est pas terminé proprement après ce nombre de millisecondes. Une valeur de 0 désactive l'avertissement. Valeur par défaut : 1000.

--outputFile=<filename>​

Écrit les résultats des tests dans un fichier lorsque l'option --json est également spécifiée. La structure JSON retournée est documentée dans testResultsProcessor.

--passWithNoTests​

Permet à la suite de tests de réussir lorsqu'aucun fichier n'est trouvé.

--projects <path1> ... <pathN>​

Exécute les tests d'un ou plusieurs projets situés dans les chemins spécifiés ; accepte également les globs de chemins. Cette option est l'équivalent CLI de l'option de configuration projects.

note

Si des fichiers de configuration sont trouvés dans les chemins spécifiés, tous les projets définis dans ces fichiers de configuration seront exécutés.

--randomize​

Mélange aléatoirement l'ordre des tests dans un fichier. Le mélange est basé sur la graine (seed). Voir --seed=<num> pour plus d'informations.

La valeur de la graine est affichée lorsque cette option est activée. Équivalent à l'option CLI --showSeed.

jest --randomize --seed 1234
note

Cette option n'est prise en charge qu'avec le runner de test par défaut jest-circus.

--reporters​

Exécute les tests avec les reporters spécifiés. Les options des reporters ne sont pas disponibles via CLI. Exemple avec plusieurs reporters :

jest --reporters="default" --reporters="jest-junit"

--resetMocks​

Réinitialise automatiquement l'état des mocks avant chaque test. Équivalent à appeler jest.resetAllMocks() avant chaque test. Cela supprimera les implémentations factices de tous les mocks mais ne restaurera pas leur implémentation initiale.

--restoreMocks​

Restaure automatiquement l'état et l'implémentation des simulacres avant chaque test. Équivalent à appeler jest.restoreAllMocks() avant chaque test. Cela supprime les implémentations factices et restaure le comportement d'origine.

--roots​

Liste de chemins vers les répertoires que Jest doit explorer.

--runInBand​

Alias : -i. Exécute tous les tests en série dans le processus courant, plutôt que de créer un pool de processus enfants. Utile pour le débogage.

--runTestsByPath​

Exécute uniquement les tests spécifiés par leur chemin exact. Évite de les convertir en expression régulière et de les faire correspondre à chaque fichier.

Par exemple, avec cette structure de fichiers :

__tests__
└── t1.test.js # test
└── t2.test.js # test

Avec un pattern, aucun test n'est trouvé :

jest --runTestsByPath __tests__/t

Sortie :

No tests found

Cependant, en passant un chemin exact, seul le test donné est exécuté :

jest --runTestsByPath __tests__/t1.test.js

Sortie :

PASS __tests__/t1.test.js
astuce

Le filtrage par expression régulière fonctionne bien sur de petits ensembles, mais devient lent avec plusieurs patterns ou beaucoup de tests. Cette option remplace la logique de correspondance par regex pour optimiser le temps de filtrage des fichiers de test par Jest.

--seed=<num>​

Définit une valeur de départ (seed) qui peut être récupérée dans un fichier de test via jest.getSeed(). La valeur doit être comprise entre -0x80000000 et 0x7fffffff inclus (-2147483648 (-(2 ** 31)) et 2147483647 (2 ** 31 - 1) en décimal).

jest --seed=1324
astuce

Si cette option n'est pas spécifiée, Jest générera aléatoirement la valeur. Vous pouvez utiliser le flag --showSeed pour afficher la valeur de départ dans le résumé du rapport de test.

Jest utilise cette valeur en interne pour mélanger l'ordre d'exécution des suites de test. Si l'option --randomize est utilisée, la valeur sert également à mélanger l'ordre des tests au sein de chaque bloc describe. Pour les tests instables (flaky), une réexécution avec la même valeur peut aider à reproduire l'échec.

--selectProjects <project1> ... <projectN>​

Exécute les tests des projets spécifiés. Jest utilise l'attribut displayName de la configuration pour identifier chaque projet. Si vous utilisez cette option, définissez un displayName pour tous vos projets.

--setupFilesAfterEnv <path1> ... <pathN>​

Liste de chemins vers des modules exécutant du code pour configurer le framework de test avant chaque test. Attention : les fichiers importés par ces scripts ne seront pas mockés pendant les tests.

--shard​

Fragment (shard) de la suite de test à exécuter, au format (?<shardIndex>\d+)/(?<shardCount>\d+).

shardIndex désigne le fragment à sélectionner tandis que shardCount contrôle le nombre total de fragments.

shardIndex et shardCount doivent être des nombres positifs commençant à 1, avec shardIndex inférieur ou égal à shardCount.

Lorsque shard est spécifié, le testSequencer configuré doit implémenter une méthode shard.

Par exemple, pour diviser la suite en trois fragments exécutant chacun un tiers des tests :

jest --shard=1/3
jest --shard=2/3
jest --shard=3/3

--showConfig​

Afficher votre configuration Jest et quitter.

--showSeed​

Affiche la valeur de départ (seed) dans le résumé du rapport de test. Voir --seed=<num> pour les détails.

Peut également être défini dans la configuration. Voir showSeed.

--silent​

Empêcher les tests d'imprimer des messages via la console.

--testEnvironmentOptions=<json string>​

Une chaîne JSON avec des options qui seront passées au testEnvironment. Les options pertinentes dépendent de l'environnement.

--testLocationInResults​

Ajoute un champ location aux résultats de test. Utile si vous souhaitez indiquer l'emplacement d'un test dans un rapporteur.

note

Dans l'objet résultant, column est indexé à partir de 0 tandis que line ne l'est pas.

{
  "column": 4,
  "line": 5
}

--testMatch glob1 ... globN​

Les modèles glob que Jest utilise pour détecter les fichiers de test. Veuillez vous référer à la configuration testMatch pour plus de détails.

--testNamePattern=<regex>​

Alias : -t. Exécute uniquement les tests dont le nom correspond à l'expression régulière. Par exemple, si vous souhaitez exécuter uniquement les tests liés à l'authentification qui auront des noms comme 'GET /api/posts with auth', vous pouvez utiliser jest -t=auth.

astuce

L'expression régulière est comparée au nom complet, qui combine le nom du test et tous les blocs de description environnants.

--testPathIgnorePatterns=<regex>|[array]​

Chaîne ou tableau de motifs regex testés contre tous les chemins de test avant exécution. Contrairement à --testPathPatterns, il n'exécutera que les tests dont le chemin ne correspond pas aux expressions regex fournies.

Pour passer un tableau, utilisez des parenthèses échappées et des regex séparés par des espaces comme \(/node_modules/ /tests/e2e/\). Alternativement, combinez les regex en une seule expression comme /node_modules/|/tests/e2e/. Ces deux exemples sont équivalents.

--testPathPatterns=<regex>​

Motif regex testé contre tous les chemins de test avant exécution. Sous Windows, utilisez / comme séparateur de chemin ou échappez \ en \\.

--testRunner=<path>​

Permet de spécifier un exécuteur de tests personnalisé.

--testSequencer=<path>​

Permet de spécifier un séquenceur de tests personnalisé. Voir la documentation testSequencer pour les détails.

--testTimeout=<number>​

Délai d'expiration par défaut d'un test en millisecondes. Valeur par défaut : 5000.

--updateSnapshot​

Alias : -u. Réenregistre tous les snapshots échouant pendant cette exécution de tests. Peut être combiné avec un motif de suite de tests ou --testNamePattern.

--useStderr​

Redirige toute la sortie vers stderr.

--verbose​

Affiche les résultats individuels des tests avec la hiérarchie des suites.

--version​

Alias : -v. Affiche la version et quitte.

--waitForUnhandledRejections​

Donne un tour de boucle d'événements pour gérer rejectionHandled, uncaughtException ou unhandledRejection.

Sans ce flag, Jest pourrait rapporter de fausses erreurs positives ou ne pas détecter des rejets non gérés.

Cette option peut ajouter une surcharge notable pour les suites de tests rapides.

--watch​

Surveille les fichiers modifiés et réexécute les tests concernés. Pour réexécuter tous les tests après une modification, utilisez plutôt --watchAll.

astuce

Utilisez --no-watch (ou --watch=false) pour désactiver explicitement le mode watch s'il a été activé avec --watch. Dans la plupart des environnements CI, ceci est géré automatiquement.

--watchAll​

Surveille les fichiers modifiés et réexécute tous les tests lors d'un changement. Pour ne réexécuter que les tests dépendants des fichiers modifiés, utilisez --watch.

astuce

Utilisez --no-watchAll (ou --watchAll=false) pour désactiver explicitement le mode watch si celui-ci a été activé avec --watchAll. Dans la plupart des environnements CI, ceci est géré automatiquement.

--watchman​

Indique s'il faut utiliser watchman pour l'exploration des fichiers. Par défaut : true. Désactivez cette option avec --no-watchman.

--workerThreads​

Indique s'il faut utiliser des worker threads pour la parallélisation. Par défaut, des processus enfants sont utilisés.

attention

Il s'agit d'une fonctionnalité expérimentale. Consultez l'option de configuration workerThreads pour plus de détails.