Aller au contenu principal
Version : 29.7

Configuration 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 →

La philosophie de Jest est de fonctionner parfaitement par défaut, mais parfois vous avez besoin de plus de puissance de configuration.

Il est recommandé de définir la configuration dans un fichier JavaScript, TypeScript ou JSON dédié. Le fichier sera détecté automatiquement s'il est nommé jest.config.js|ts|mjs|cjs|json. Vous pouvez utiliser l'option --config pour spécifier un chemin explicite vers le fichier.

note

N'oubliez pas que l'objet de configuration résultant doit toujours être sérialisable en JSON.

Le fichier de configuration doit simplement exporter un objet :

/** @type {import('jest').Config} */
const config = {
  verbose: true,
};

module.exports = config;

Ou une fonction qui retourne un objet :

/** @returns {Promise<import('jest').Config>} */
module.exports = async () => {
  return {
    verbose: true,
  };
};
astuce

Pour lire les fichiers de configuration TypeScript, Jest nécessite ts-node. Assurez-vous qu'il est installé dans votre projet.

La configuration peut également être stockée dans un fichier JSON sous forme d'objet simple :

jest.config.json
{
  "bail": 1,
  "verbose": true
}

Alternativement, la configuration de Jest peut être définie via la clé "jest" dans le package.json de votre projet :

package.json
{
  "name": "my-project",
  "jest": {
    "verbose": true
  }
}

Options​

info

Vous pouvez récupérer les configurations par défaut de Jest via jest-config pour les étendre si nécessaire :

const {defaults} = require('jest-config');

/** @type {import('jest').Config} */
const config = {
  moduleFileExtensions: [...defaults.moduleFileExtensions, 'mts', 'cts'],
};

module.exports = config;

Référence​

automock [boolean]​

Par défaut : false

Cette option indique à Jest que tous les modules importés dans vos tests doivent être mockés automatiquement. Tous les modules utilisés auront une implémentation de remplacement, tout en conservant la surface d'API.

Exemple :

utils.js
export default {
  authorize: () => 'token',
  isAuthorized: secret => secret === 'wizard',
};
__tests__/automock.test.js
import utils from '../utils';

test('if utils mocked automatically', () => {
  // Public methods of `utils` are now mock functions
  expect(utils.authorize.mock).toBeTruthy();
  expect(utils.isAuthorized.mock).toBeTruthy();

  // You can provide them with your own implementation
  // or pass the expected return value
  utils.authorize.mockReturnValue('mocked_token');
  utils.isAuthorized.mockReturnValue(true);

  expect(utils.authorize()).toBe('mocked_token');
  expect(utils.isAuthorized('not_wizard')).toBeTruthy();
});
note

Les modules Node sont automatiquement mockés lorsque vous avez un mock manuel en place (ex: __mocks__/lodash.js). Plus d'infos ici.

Les modules core de Node.js, comme fs, ne sont pas mockés par défaut. Ils peuvent être mockés explicitement avec jest.mock('fs').

bail [nombre | boolean]​

Par défaut : 0

Par défaut, Jest exécute tous les tests et affiche toutes les erreurs dans la console à la fin. L'option bail permet d'arrêter l'exécution des tests après n échecs. Définir bail sur true équivaut à le définir sur 1.

cacheDirectory [chaîne]​

Par défaut : "/tmp/<path>"

Le répertoire où Jest doit stocker ses informations de dépendances en cache.

Jest tente d'analyser votre arborescence de dépendances une seule fois (en amont) et de la mettre en cache afin de réduire certaines opérations coûteuses sur le système de fichiers lors de l'exécution des tests. Cette option vous permet de personnaliser l'emplacement où Jest stocke ces données de cache sur le disque.

clearMocks [boolean]​

Par défaut : false

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.

collectCoverage [boolean]​

Par défaut : false

Indique si les informations de couverture de code doivent être collectées lors de l'exécution des tests. Comme cette opération instrumente tous les fichiers exécutés avec des instructions de collecte de couverture, elle peut ralentir significativement vos tests.

Jest intègre deux fournisseurs de couverture : babel (par défaut) et v8. Voir l'option coverageProvider pour plus de détails.

info

Les fournisseurs de couverture babel et v8 utilisent respectivement les commentaires /* istanbul ignore next */ et /* c8 ignore next */ pour exclure des lignes des rapports de couverture. Pour plus d'informations, consultez la documentation d'istanbuljs et celle de c8.

collectCoverageFrom [array]​

Par défaut : undefined

Un tableau de modèles glob indiquant un ensemble de fichiers pour lesquels les informations de couverture doivent être collectées. Si un fichier correspond au modèle glob spécifié, les informations de couverture seront collectées même si aucun test n'existe pour ce fichier et qu'il n'est jamais importé dans la suite de tests.

/** @type {import('jest').Config} */
const config = {
  collectCoverageFrom: [
    '**/*.{js,jsx}',
    '!**/node_modules/**',
    '!**/vendor/**',
  ],
};

module.exports = config;

Cette option collectera les informations de couverture pour tous les fichiers du rootDir du projet, sauf ceux correspondant à **/node_modules/** ou **/vendor/**.

astuce

Chaque modèle glob est appliqué dans l'ordre spécifié dans la configuration. Par exemple ["!**/__tests__/**", "**/*.js"] n'exclura pas __tests__ car la négation est écrasée par le second modèle. Pour que la négation fonctionne dans cet exemple, elle doit être placée après **/*.js.

note

Cette option nécessite que collectCoverage soit défini sur true ou que Jest soit invoqué avec --coverage.

Help:

If you are seeing coverage output such as...

=============================== Coverage summary ===============================
Statements   : Unknown% ( 0/0 )
Branches     : Unknown% ( 0/0 )
Functions    : Unknown% ( 0/0 )
Lines        : Unknown% ( 0/0 )
================================================================================
Jest: Coverage data for global was not found.

Most likely your glob patterns are not matching any files. Refer to the micromatch documentation to ensure your globs are compatible.

coverageDirectory [string]​

Par défaut : undefined

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

coveragePathIgnorePatterns [array<string>]​

Par défaut : ["/node_modules/"]

Un tableau de chaînes de motifs regex qui sont comparées à tous les chemins de fichiers avant l'exécution du test. Si le chemin correspond à l'un des motifs, les informations de couverture seront ignorées.

Ces motifs comparent le chemin complet. Utilisez le jeton <rootDir> pour inclure le chemin racine de votre projet et éviter d'ignorer accidentellement des fichiers dans différents environnements. Exemple : ["<rootDir>/build/", "<rootDir>/node_modules/"].

coverageProvider [string]​

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

coverageReporters [array<string | [string, options]>]​

Default: ["clover", "json", "lcov", "text"]

Liste des noms de reporters que Jest utilise pour générer les rapports de couverture. Tout reporter istanbul peut être utilisé.

astuce

Définir cette option remplace les valeurs par défaut. Ajoutez "text" ou "text-summary" pour voir un résumé de couverture dans la sortie console.

Des options supplémentaires peuvent être transmises en utilisant la forme tuple. Par exemple, vous pouvez masquer les lignes de rapport de couverture pour tous les fichiers entièrement couverts :

/** @type {import('jest').Config} */
const config = {
  coverageReporters: ['clover', 'json', 'lcov', ['text', {skipFull: true}]],
};

module.exports = config;

Pour plus d'informations sur la structure de l'objet d'options, référez-vous au type CoverageReporterWithOptions dans les définitions de types.

coverageThreshold [object]​

Par défaut : undefined

Permet de configurer les seuils minimums d'exigence pour les résultats de couverture. Les seuils peuvent être spécifiés comme global, via un glob, ou par chemin de dossier/fichier. Si les seuils ne sont pas atteints, Jest échouera. Les seuils positifs représentent le pourcentage minimum requis. Les seuils négatifs représentent le nombre maximum d'entités non couvertes autorisées.

Par exemple, avec cette configuration Jest échouera s'il y a moins de 80% de couverture des branches, lignes et fonctions, ou plus de 10 instructions non couvertes :

/** @type {import('jest').Config} */
const config = {
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: -10,
    },
  },
};

module.exports = config;

Si des globs ou chemins sont spécifiés avec global, leurs données de couverture seront soustraites de la couverture globale et les seuils s'appliqueront indépendamment. Les seuils pour les globs s'appliquent à tous les fichiers correspondants. Si un chemin spécifié est introuvable, une erreur est retournée.

Par exemple, avec cette configuration :

/** @type {import('jest').Config} */
const config = {
  coverageThreshold: {
    global: {
      branches: 50,
      functions: 50,
      lines: 50,
      statements: 50,
    },
    './src/components/': {
      branches: 40,
      statements: 40,
    },
    './src/reducers/**/*.js': {
      statements: 90,
    },
    './src/api/very-important-module.js': {
      branches: 100,
      functions: 100,
      lines: 100,
      statements: 100,
    },
  },
};

module.exports = config;

Jest échouera si :

  • Le dossier ./src/components a moins de 40% de couverture des branches ou instructions

  • Un fichier correspondant au glob ./src/reducers/**/*.js a moins de 90% de couverture des instructions

  • Le fichier ./src/api/very-important-module.js a moins de 100% de couverture

  • L'ensemble des fichiers restants a moins de 50% de couverture (global)

dependencyExtractor [string]​

Par défaut : undefined

Permet d'utiliser un extracteur de dépendances personnalisé. Doit être un module Node exportant un objet avec une fonction extract. Exemple :

const crypto = require('crypto');
const fs = require('fs');

module.exports = {
  extract(code, filePath, defaultExtract) {
    const deps = defaultExtract(code, filePath);
    // Scan the file and add dependencies in `deps` (which is a `Set`)
    return deps;
  },
  getCacheKey() {
    return crypto
      .createHash('md5')
      .update(fs.readFileSync(__filename))
      .digest('hex');
  },
};

La fonction extract doit retourner un itérable (Array, Set, etc.) contenant les dépendances trouvées dans le code.

Le module peut également contenir une fonction getCacheKey pour générer une clé de cache déterminant si la logique a changé et si les artefacts mis en cache doivent être invalidés.

displayName [string, object]​

Par défaut : undefined

Permet d'afficher un libellé à côté d'un test pendant son exécution. Utile dans les dépôts multi-projets avec plusieurs fichiers de configuration Jest. Indique visuellement à quel projet appartient un test.

/** @type {import('jest').Config} */
const config = {
  displayName: 'CLIENT',
};

module.exports = config;

Peut également être un objet avec les propriétés name et color pour personnaliser la couleur d'arrière-plan du displayName. displayName est blanc par défaut lorsque sa valeur est une chaîne. Jest utilise chalk, donc toutes les options de couleurs valides de chalk sont supportées.

/** @type {import('jest').Config} */
const config = {
  displayName: {
    name: 'CLIENT',
    color: 'blue',
  },
};

module.exports = config;

errorOnDeprecated [boolean]​

Par défaut : false

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.

extensionsToTreatAsEsm [array<string>]​

Valeur par défaut : []

Jest exécutera les fichiers .mjs et .js dont le package.json le plus proche a le champ type défini sur module en tant que modules ECMAScript. Si vous avez d'autres fichiers devant s'exécuter en ESM natif, vous devez spécifier leur extension ici.

/** @type {import('jest').Config} */
const config = {
  extensionsToTreatAsEsm: ['.ts'],
};

module.exports = config;
attention

La prise en charge d'ESM par Jest est toujours expérimentale, consultez sa documentation pour plus de détails.

fakeTimers [object]​

Par défaut : {}

Les horloges fictives sont utiles lorsqu'un code définit un long timeout qu'on ne souhaite pas attendre dans un test. Pour plus de détails, voir le guide Horloges fictives et la documentation de l'API.

Cette option fournit la configuration par défaut des horloges fictives pour tous les tests. Appeler jest.useFakeTimers() dans un fichier de test utilisera ces options ou les remplacera si un objet de configuration est fourni. Par exemple, vous pouvez demander à Jest de conserver l'implémentation originale de process.nextTick() et d'ajuster la limite des minuteries récursives exécutées :

/** @type {import('jest').Config} */
const config = {
  fakeTimers: {
    doNotFake: ['nextTick'],
    timerLimit: 1000,
  },
};

module.exports = config;
fakeTime.test.js
// install fake timers for this file using the options from Jest configuration
jest.useFakeTimers();

test('increase the limit of recursive timers for this and following tests', () => {
  jest.useFakeTimers({timerLimit: 5000});
  // ...
});
astuce

Au lieu d'inclure jest.useFakeTimers() dans chaque fichier de test, vous pouvez activer globalement les horloges fictives pour tous les tests dans votre configuration Jest :

/** @type {import('jest').Config} */
const config = {
  fakeTimers: {
    enableGlobally: true,
  },
};

module.exports = config;

Options de configuration :

type FakeableAPI =
  | 'Date'
  | 'hrtime'
  | 'nextTick'
  | 'performance'
  | 'queueMicrotask'
  | 'requestAnimationFrame'
  | 'cancelAnimationFrame'
  | 'requestIdleCallback'
  | 'cancelIdleCallback'
  | 'setImmediate'
  | 'clearImmediate'
  | 'setInterval'
  | 'clearInterval'
  | 'setTimeout'
  | 'clearTimeout';

type ModernFakeTimersConfig = {
  /**
   * If set to `true` all timers will be advanced automatically by 20 milliseconds
   * every 20 milliseconds. A custom time delta may be provided by passing a number.
   * The default is `false`.
   */
  advanceTimers?: boolean | number;
  /**
   * List of names of APIs that should not be faked. The default is `[]`, meaning
   * all APIs are faked.
   */
  doNotFake?: Array<FakeableAPI>;
  /** Whether fake timers should be enabled for all test files. The default is `false`. */
  enableGlobally?: boolean;
  /**
   * Use the old fake timers implementation instead of one backed by `@sinonjs/fake-timers`.
   * The default is `false`.
   */
  legacyFakeTimers?: boolean;
  /** Sets current system time to be used by fake timers, in milliseconds. The default is `Date.now()`. */
  now?: number;
  /** Maximum number of recursive timers that will be run. The default is `100_000` timers. */
  timerLimit?: number;
};
Horloges fictives héritées

Pour certaines raisons, vous pourriez devoir utiliser l'implémentation héritée des horloges fictives. Voici comment l'activer globalement (les options supplémentaires ne sont pas prises en charge) :

/** @type {import('jest').Config} */
const config = {
  fakeTimers: {
    enableGlobally: true,
    legacyFakeTimers: true,
  },
};

module.exports = config;

forceCoverageMatch [array<string>]​

Par défaut : ['']

Les fichiers de test sont normalement ignorés lors de la collecte de couverture de code. Avec cette option, vous pouvez outrepasser ce comportement et inclure ces fichiers dans la couverture.

Par exemple, si vous avez des tests dans des fichiers sources nommés avec l'extension .t.js comme suit :

sum.t.js
export function sum(a, b) {
  return a + b;
}

if (process.env.NODE_ENV === 'test') {
  test('sum', () => {
    expect(sum(1, 2)).toBe(3);
  });
}

Vous pouvez collecter la couverture de ces fichiers en définissant forceCoverageMatch.

/** @type {import('jest').Config} */
const config = {
  forceCoverageMatch: ['**/*.t.js'],
};

module.exports = config;

globals [object]​

Par défaut : {}

Un ensemble de variables globales devant être disponibles dans tous les environnements de test.

Par exemple, la configuration suivante créera une variable globale __DEV__ définie sur true dans tous les environnements :

/** @type {import('jest').Config} */
const config = {
  globals: {
    __DEV__: true,
  },
};

module.exports = config;
note

Si vous spécifiez une valeur globale référencée (comme un objet ou tableau), et qu'un code modifie cette valeur pendant l'exécution d'un test, cette modification ne sera pas conservée pour les autres fichiers de test. De plus, l'objet globals doit être sérialisable en JSON, il ne peut donc pas être utilisé pour spécifier des fonctions globales. Pour cela, utilisez plutôt setupFiles.

globalSetup [string]​

Par défaut : undefined

Cette option permet d'utiliser un module de configuration global personnalisé, qui doit exporter une fonction (synchrone ou asynchrone). La fonction sera déclenchée une fois avant tous les suites de tests et recevra deux arguments : la globalConfig de Jest et la projectConfig.

info

Un module de configuration global configuré dans un projet (utilisant le runner multi-projets) ne sera déclenché que si vous exécutez au moins un test de ce projet.

Les variables globales définies via globalSetup ne sont accessibles que dans globalTeardown. Vous ne pouvez pas récupérer ces variables globales dans vos suites de tests.

Bien qu'une transformation de code soit appliquée au fichier de setup lié, Jest ne transformera pas le code dans node_modules. Cela est dû à la nécessité de charger les transformateurs réels (par ex. babel ou typescript) pour effectuer la transformation.

setup.js
module.exports = async function (globalConfig, projectConfig) {
  console.log(globalConfig.testPathPattern);
  console.log(projectConfig.cache);

  // Set reference to mongod in order to close the server during teardown.
  globalThis.__MONGOD__ = mongod;
};
teardown.js
module.exports = async function (globalConfig, projectConfig) {
  console.log(globalConfig.testPathPattern);
  console.log(projectConfig.cache);

  await globalThis.__MONGOD__.stop();
};

globalTeardown [string]​

Par défaut : undefined

Cette option permet d'utiliser un module de teardown global personnalisé qui doit exporter une fonction (synchrone ou asynchrone). La fonction sera déclenchée une fois après toutes les suites de tests et recevra deux arguments : la globalConfig de Jest et la projectConfig.

info

Un module de teardown global configuré dans un projet (utilisant le runner multi-projets) ne sera déclenché que si vous exécutez au moins un test de ce projet.

La même mise en garde concernant la transformation de node_modules que pour globalSetup s'applique à globalTeardown.

haste [object]​

Par défaut : undefined

Ce paramètre configure le comportement de jest-haste-map, le système interne de crawl/mise en cache de fichiers de Jest. Les options suivantes sont prises en charge :

type HasteConfig = {
  /** Whether to hash files using SHA-1. */
  computeSha1?: boolean;
  /** The platform to use as the default, e.g. 'ios'. */
  defaultPlatform?: string | null;
  /** Force use of Node's `fs` APIs rather than shelling out to `find` */
  forceNodeFilesystemAPI?: boolean;
  /**
   * Whether to follow symlinks when crawling for files.
   *   This options cannot be used in projects which use watchman.
   *   Projects with `watchman` set to true will error if this option is set to true.
   */
  enableSymlinks?: boolean;
  /** Path to a custom implementation of Haste. */
  hasteImplModulePath?: string;
  /** All platforms to target, e.g ['ios', 'android']. */
  platforms?: Array<string>;
  /** Whether to throw an error on module collision. */
  throwOnModuleCollision?: boolean;
  /** Custom HasteMap module */
  hasteMapModulePath?: string;
  /** Whether to retain all files, allowing e.g. search for tests in `node_modules`. */
  retainAllFiles?: boolean;
};

injectGlobals [boolean]​

Par défaut : true

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.

maxConcurrency [number]​

Par défaut : 5

Nombre limitant le nombre de tests pouvant s'exécuter simultanément avec test.concurrent. Tout test dépassant cette limite sera mis en file d'attente et exécuté lorsqu'un slot se libère.

maxWorkers [number | string]​

Spécifie le nombre maximum de workers que le pool créera pour exécuter les tests. En mode single run, la valeur par défaut correspond au nombre de cœurs disponibles sur votre machine moins un pour le thread principal. En mode watch, la valeur par défaut est la moitié des cœurs disponibles pour garantir que Jest reste discret et ne bloque pas votre machine. Il peut être utile d'ajuster cette valeur dans des environnements aux ressources limitées comme les CI, mais les valeurs par défaut conviennent à la plupart des cas d'usage.

Pour les environnements avec des CPU variables, une configuration basée sur des pourcentages est possible :

/** @type {import('jest').Config} */
const config = {
  maxWorkers: '50%',
};

module.exports = config;

moduleDirectories [array<string>]​

Par défaut : ["node_modules"]

Tableau de noms de répertoires à parcourir récursivement à partir de l'emplacement du module demandeur. Définir cette option remplacera la valeur par défaut. Si vous souhaitez toujours rechercher les packages dans node_modules, incluez-le avec les autres options :

/** @type {import('jest').Config} */
const config = {
  moduleDirectories: ['node_modules', 'bower_components'],
};

module.exports = config;
attention

Il est déconseillé d'utiliser '.' comme l'un des moduleDirectories, car cela empêche les packages scopés comme @emotion/react d'accéder aux packages portant le même nom de sous-répertoire (react). Consultez cette issue pour plus de détails. Dans la plupart des cas, il est préférable d'utiliser la configuration moduleNameMapper à la place.

moduleFileExtensions [array<string>]​

Par défaut : ["js", "mjs", "cjs", "jsx", "ts", "tsx", "json", "node"]

Un tableau d'extensions de fichiers utilisées par vos modules. Si vous importez des modules sans spécifier d'extension, Jest recherchera ces extensions dans l'ordre, de gauche à droite.

Nous recommandons de placer les extensions les plus couramment utilisées dans votre projet à gauche. Si vous utilisez TypeScript, envisagez de déplacer "ts" et/ou "tsx" au début du tableau.

moduleNameMapper [object<string, string | array<string>>]​

Par défaut : null

Une correspondance entre des expressions régulières et des noms de modules (ou tableaux de noms) permettant de remplacer des ressources comme des images ou des styles par un seul module.

Les modules mappés à un alias ne sont pas mockés par défaut, quel que soit l'état d'automock.

Utilisez le jeton <rootDir> pour référencer la valeur de rootDir si vous souhaitez utiliser des chemins de fichiers.

Vous pouvez également substituer des groupes capturés en utilisant des références arrière numérotées.

/** @type {import('jest').Config} */
const config = {
  moduleNameMapper: {
    '^image![a-zA-Z0-9$_-]+$': 'GlobalImageStub',
    '^[./a-zA-Z0-9$_-]+\\.png$': '<rootDir>/RelativeImageStub.js',
    'module_name_(.*)': '<rootDir>/substituted_module_$1.js',
    'assets/(.*)': [
      '<rootDir>/images/$1',
      '<rootDir>/photos/$1',
      '<rootDir>/recipes/$1',
    ],
  },
};

module.exports = config;

L'ordre des correspondances est important : les motifs sont vérifiés un par un jusqu'à trouver une correspondance. La règle la plus spécifique doit être listée en premier. Ceci s'applique aussi aux tableaux de noms de modules.

info

Si vous fournissez des noms de modules sans délimiteurs ^$, cela peut causer des erreurs difficiles à repérer. Par exemple, relay remplacera tous les modules contenant relay dans leur nom : relay, react-relay et graphql-relay pointeront tous vers votre stub.

modulePathIgnorePatterns [array<string>]​

Valeur par défaut : []

Un tableau de motifs regex testés contre tous les chemins de modules avant qu'ils ne soient considérés comme "visibles" par le chargeur de modules. Si un chemin correspond à l'un des motifs, il ne pourra pas être require() dans l'environnement de test.

Ces motifs regex sont comparés au chemin complet. Utilisez le jeton <rootDir> pour inclure le chemin racine de votre projet et éviter d'ignorer accidentellement vos fichiers dans différents environnements pouvant avoir des racines différentes.

/** @type {import('jest').Config} */
const config = {
  modulePathIgnorePatterns: ['<rootDir>/build/'],
};

module.exports = config;

modulePaths [array<string>]​

Valeur par défaut : []

Alternative à la variable d'environnement NODE_PATH, modulePaths est un tableau de chemins absolus vers des emplacements supplémentaires où rechercher des modules. Utilisez le jeton <rootDir> pour inclure le chemin racine de votre projet.

/** @type {import('jest').Config} */
const config = {
  modulePaths: ['<rootDir>/app/'],
};

module.exports = config;

notify [boolean]​

Par défaut : false

Active les notifications système natives pour les résultats des tests. Jest nécessite le package node-notifier pour afficher les notifications, qui doit être installé séparément :

npm install --save-dev node-notifier
astuce

Sur macOS, autorisez les notifications de terminal-notifier dans Préférences Système > Notifications.

Sur Windows, node-notifier crée une nouvelle entrée dans le menu démarrer lors du premier usage sans afficher de notification. Les notifications s'afficheront correctement lors des exécutions suivantes.

notifyMode [string]​

Par défaut : failure-change

Spécifie le mode de notification. Nécessite notify: true.

Modes​

  • always : envoie toujours une notification.

  • failure : envoie une notification quand les tests échouent.

  • success : envoie une notification quand les tests réussissent.

  • change : envoie une notification quand le statut change.

  • success-change : envoie une notification quand les tests réussissent ou une fois quand ils échouent.

  • failure-change : envoie une notification quand les tests échouent ou une fois quand ils réussissent.

openHandlesTimeout [number]​

Valeur par défaut : 1000

Affiche un avertissement indiquant des handles probablement ouverts si Jest ne s'arrête pas proprement après ce délai en millisecondes suivant son exécution. Utilisez 0 pour désactiver l'avertissement.

preset [string]​

Par défaut : undefined

Présélection utilisée comme base pour la configuration de Jest. Doit pointer vers un module npm contenant un fichier jest-preset.json, jest-preset.js, jest-preset.cjs ou jest-preset.mjs à sa racine.

Par exemple, ce préréglage foo-bar/jest-preset.js sera configuré comme suit :

/** @type {import('jest').Config} */
const config = {
  preset: 'foo-bar',
};

module.exports = config;

Les présélections peuvent aussi être relatives à des chemins du système de fichiers :

/** @type {import('jest').Config} */
const config = {
  preset: './node_modules/foo-bar/jest-preset.js',
};

module.exports = config;
info

Si vous avez spécifié rootDir, la résolution de ce fichier sera relative à ce répertoire racine.

prettierPath [string]​

Valeur par défaut : 'prettier'

Définit le chemin vers le module Node prettier utilisé pour mettre à jour les snapshots inline.

Prettier version 3 is not supported!

You can either pass prettierPath: null in your config to disable using prettier if you don't need it, or use v2 of Prettier solely for Jest.

package.json
{
  "devDependencies": {
    "prettier-2": "npm:prettier@^2"
  }
}
/** @type {import('jest').Config} */
const config = {
  prettierPath: require.resolve('prettier-2'),
};

module.exports = config;

We hope to support Prettier v3 seamlessly out of the box in a future version of Jest. See this tracking issue.

projects [array<string | ProjectConfig>]​

Par défaut : undefined

Lorsque la configuration projects reçoit un tableau de chemins ou de motifs globaux, Jest exécutera simultanément les tests dans tous les projets spécifiés. Idéal pour les monorepos ou le travail sur plusieurs projets.

/** @type {import('jest').Config} */
const config = {
  projects: ['<rootDir>', '<rootDir>/examples/*'],
};

module.exports = config;

Cette configuration exécutera Jest dans le répertoire racine et chaque dossier du répertoire examples. Vous pouvez exécuter un nombre illimité de projets dans la même instance Jest.

La fonctionnalité projects permet aussi d'exécuter plusieurs configurations ou plusieurs runners. Pour cela, passez un tableau d'objets de configuration. Exemple pour exécuter tests et ESLint (via jest-runner-eslint) dans la même invocation de Jest :

/** @type {import('jest').Config} */
const config = {
  projects: [
    {
      displayName: 'test',
    },
    {
      displayName: 'lint',
      runner: 'jest-runner-eslint',
      testMatch: ['<rootDir>/**/*.js'],
    },
  ],
};

module.exports = config;
astuce

Avec un runner multi-projets, ajoutez un displayName à chaque projet. Cela affichera le displayName du projet à côté de ses tests.

note

Avec projects, Jest copie les options de configuration racine dans chaque configuration enfant lors de l'exécution, en résolvant les valeurs dans leur contexte. Les jetons comme <rootDir> pointeront vers le répertoire racine de l'enfant.

randomize [boolean]​

Par défaut : false

Équivalent du flag --randomize pour randomiser l'ordre des tests dans un fichier.

reporters [array<moduleName | [moduleName, options]>]​

Par défaut : undefined

Utilisez cette option pour ajouter des reporters à Jest. Doit être une liste de noms de reporters, avec options supplémentaires via la forme de tuple :

/** @type {import('jest').Config} */
const config = {
  reporters: [
    'default',
    ['<rootDir>/custom-reporter.js', {banana: 'yes', pineapple: 'no'}],
  ],
};

module.exports = config;

Reporter par défaut​

Si des reporters personnalisés sont spécifiés, le reporter par défaut de Jest sera remplacé. Si vous souhaitez le conserver, 'default' doit être passé comme nom de reporter :

/** @type {import('jest').Config} */
const config = {
  reporters: [
    'default',
    ['jest-junit', {outputDirectory: 'reports', outputName: 'report.xml'}],
  ],
};

module.exports = config;

Reporter GitHub Actions​

S'il est inclus dans la liste, le reporter intégré GitHub Actions annotera les fichiers modifiés avec les messages d'échec des tests et (s'il est utilisé avec 'silent: false') imprimera les journaux avec les fonctionnalités de groupe de GitHub pour une navigation facile. Notez que 'default' ne doit pas être utilisé dans ce cas car 'github-actions' le gérera déjà, donc n'oubliez pas d'inclure également 'summary'. Si vous souhaitez l'utiliser uniquement pour les annotations, laissez simplement le reporter sans options car la valeur par défaut de 'silent' est 'true' :

/** @type {import('jest').Config} */
const config = {
  reporters: [['github-actions', {silent: false}], 'summary'],
};

module.exports = config;

Reporter de résumé​

Le reporter de résumé imprime un résumé de tous les tests. Il fait partie du reporter par défaut, il sera donc activé si 'default' est inclus dans la liste. Par exemple, vous pouvez l'utiliser comme reporter autonome à la place du reporter par défaut, ou avec le Silent Reporter :

/** @type {import('jest').Config} */
const config = {
  reporters: ['jest-silent-reporter', 'summary'],
};

module.exports = config;

Le reporter summary accepte des options. Comme il est inclus dans le reporter default, vous pouvez également passer les options à cet endroit.

/** @type {import('jest').Config} */
const config = {
  reporters: [['default', {summaryThreshold: 10}]],
};

module.exports = config;

L'option summaryThreshold se comporte de la manière suivante : si le nombre total de suites de test dépasse ce seuil, un résumé détaillé de tous les tests échoués sera imprimé après l'exécution de tous les tests. La valeur par défaut est 20.

Reporters personnalisés​

astuce

Envie de reporters ? Jetez un œil à la longue liste de reporters géniaux d'Awesome Jest.

Un module de reporter personnalisé doit exporter une classe qui prend globalConfig, reporterOptions et reporterContext comme arguments du constructeur :

custom-reporter.js
class CustomReporter {
  constructor(globalConfig, reporterOptions, reporterContext) {
    this._globalConfig = globalConfig;
    this._options = reporterOptions;
    this._context = reporterContext;
  }

  onRunComplete(testContexts, results) {
    console.log('Custom reporter output:');
    console.log('global config:', this._globalConfig);
    console.log('options for this reporter from Jest config:', this._options);
    console.log('reporter context passed from test scheduler:', this._context);
  }

  // Optionally, reporters can force Jest to exit with non zero code by returning
  // an `Error` from `getLastError()` method.
  getLastError() {
    if (this._shouldFail) {
      return new Error('Custom error reported!');
    }
  }
}

module.exports = CustomReporter;
note

Pour la liste complète des hooks et des types d'arguments, consultez l'interface Reporter dans packages/jest-reporters/src/types.ts.

resetMocks [boolean]​

Par défaut : false

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.

resetModules [boolean]​

Par défaut : false

Par défaut, chaque fichier de test possède son propre registre de modules indépendant. Activer resetModules va plus loin et réinitialise le registre de modules avant chaque test individuel. C'est utile pour isoler les modules à chaque test afin que l'état local des modules ne provoque pas de conflits entre les tests. Cela peut être fait programmatiquement avec jest.resetModules().

resolver [string]​

Par défaut : undefined

Cette option permet l'utilisation d'un resolver personnalisé. Ce resolver doit être un module qui exporte soit :

  1. une fonction attendant une chaîne de caractères comme premier argument pour le chemin à résoudre et un objet d'options comme second argument. La fonction doit retourner un chemin vers le module à résoudre ou lancer une erreur si le module est introuvable. soit

  2. un objet contenant les propriétés async et/ou sync. La propriété sync doit être une fonction avec la forme décrite ci-dessus, et la propriété async doit également être une fonction qui accepte les mêmes arguments, mais retourne une promesse qui se résout avec le chemin du module ou se rejette avec une erreur.

L'objet d'options fourni aux resolvers a la forme :

type ResolverOptions = {
  /** Directory to begin resolving from. */
  basedir: string;
  /** List of export conditions. */
  conditions?: Array<string>;
  /** Instance of default resolver. */
  defaultResolver: (path: string, options: ResolverOptions) => string;
  /** List of file extensions to search in order. */
  extensions?: Array<string>;
  /** List of directory names to be looked up for modules recursively. */
  moduleDirectory?: Array<string>;
  /** List of `require.paths` to use if nothing is found in `node_modules`. */
  paths?: Array<string>;
  /** Allows transforming parsed `package.json` contents. */
  packageFilter?: (pkg: PackageJSON, file: string, dir: string) => PackageJSON;
  /** Allows transforms a path within a package. */
  pathFilter?: (pkg: PackageJSON, path: string, relativePath: string) => string;
  /** Current root directory. */
  rootDir?: string;
};
astuce

Le defaultResolver passé en option est le résolveur par défaut de Jest, qui peut être utile lorsque vous écrivez votre propre résolveur personnalisé. Il prend les mêmes arguments qu'une fonction synchrone personnalisée, par exemple (path, options), et renvoie une chaîne ou lance une exception.

Par exemple, pour respecter le champ "browser" de Browserify, vous pouvez utiliser ce résolveur :

resolver.js
const browserResolve = require('browser-resolve');

module.exports = browserResolve.sync;

Et l'ajouter à la configuration Jest :

/** @type {import('jest').Config} */
const config = {
  resolver: '<rootDir>/resolver.js',
};

module.exports = config;

En combinant defaultResolver et packageFilter, nous pouvons implémenter un "pré-processeur" de package.json qui modifie la résolution des modules par le résolveur par défaut. Par exemple, pour prioriser le champ "module" s'il existe, sinon utiliser "main" :

module.exports = (path, options) => {
  // Call the defaultResolver, so we leverage its cache, error handling, etc.
  return options.defaultResolver(path, {
    ...options,
    // Use packageFilter to process parsed `package.json` before the resolution (see https://www.npmjs.com/package/resolve#resolveid-opts-cb)
    packageFilter: pkg => {
      return {
        ...pkg,
        // Alter the value of `main` before resolving the package
        main: pkg.module || pkg.main,
      };
    },
  });
};

restoreMocks [boolean]​

Par défaut : false

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.

rootDir [string]​

Par défaut : Racine du répertoire contenant votre fichier de configuration Jest OU package.json OU pwd si aucun package.json n'est trouvé

Répertoire racine que Jest doit parcourir pour trouver tests et modules. Si votre configuration Jest est dans package.json et que vous voulez que la racine soit celle du dépôt, cette valeur correspondra au répertoire du package.json.

Souvent, vous définirez 'src' ou 'lib' si votre code est dans ces répertoires.

astuce

Utilisez '<rootDir>' comme jeton dans les chemins de configuration pour référencer cette valeur. Par exemple, pour pointer setupFiles vers some-setup.js à la racine : '<rootDir>/some-setup.js'.

roots [array<string>]​

Par défaut : ["<rootDir>"]

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

Utile pour limiter la recherche à un sous-répertoire spécifique (comme src/), sans accéder au reste du dépôt.

info

Alors que rootDir sert principalement de jeton réutilisable, roots est utilisé en interne par Jest pour localiser les fichiers de test et le code source. Cela s'applique aussi aux simulacres manuels des modules node_modules (les __mocks__ doivent se trouver dans un des roots).

Par défaut, roots contient <rootDir>. Dans certains cas (ex: roots: ["<rootDir>/src/", "<rootDir>/tests/"]), vous pouvez avoir plusieurs racines.

runtime [chaîne]​

Par défaut : "jest-runtime"

Cette option permet d'utiliser un runtime personnalisé pour exécuter les fichiers de test. Un runtime personnalisé peut être fourni en spécifiant un chemin vers une implémentation de runtime.

Le module runtime doit exporter une classe qui étend la classe Runtime par défaut de Jest ou implémente une interface compatible avec la même signature de constructeur et les mêmes méthodes.

avertissement

La création d'un runtime personnalisé est un cas d'utilisation avancé. La plupart des utilisateurs ne devraient pas avoir besoin de personnaliser le runtime. Vérifiez si votre cas d'utilisation ne pourrait pas être mieux traité avec des transformers, des environnements de test ou des mocks de modules personnalisés.

Exemple :

custom-runtime.js
const {default: Runtime} = require('jest-runtime');

class CustomRuntime extends Runtime {
  //...custom logic
}

module.exports = CustomRuntime;
custom-runtime.ts
import Runtime from 'jest-runtime';

export default class CustomRuntime extends Runtime {
  //...custom logic
}

Ajoutez le runtime personnalisé à votre configuration Jest :

jest.config.js
module.exports = {
  runtime: './custom-runtime.js',
};

runner [string]​

Par défaut : "jest-runner"

Permet d'utiliser un exécuteur personnalisé plutôt que celui par défaut de Jest. Exemples :

info

La valeur de la propriété runner peut omettre le préfixe jest-runner- dans le nom du package.

Pour écrire un test-runner, exportez une classe qui accepte globalConfig dans son constructeur et possède une méthode runTests avec la signature :

async function runTests(
  tests: Array<Test>,
  watcher: TestWatcher,
  onStart: OnTestStart,
  onResult: OnTestSuccess,
  onFailure: OnTestFailure,
  options: TestRunnerOptions,
): Promise<void>;

Si vous devez restreindre votre test-runner à une exécution séquentielle plutôt que parallèle, votre classe doit avoir la propriété isSerial définie sur true.

sandboxInjectedGlobals [array<string>]​

astuce

Renommé à partir de extraGlobals dans Jest 28.

Par défaut : undefined

Les fichiers de test s'exécutent dans une vm, ce qui ralentit les appels aux propriétés du contexte global (par ex. Math). Cette option permet de spécifier des propriétés supplémentaires à définir dans la vm pour des recherches plus rapides.

Par exemple, si vos tests appellent souvent Math, vous pouvez le transmettre en définissant sandboxInjectedGlobals.

/** @type {import('jest').Config} */
const config = {
  sandboxInjectedGlobals: ['Math'],
};

module.exports = config;
note

Cette option n'a aucun effet si vous utilisez ESM natif.

setupFiles [array]​

Valeur par défaut : []

Liste de chemins vers des modules exécutant du code pour configurer l'environnement de test. Chaque fichier setup est exécuté une fois par fichier de test. Comme chaque test s'exécute dans son propre environnement, ces scripts sont lancés avant setupFilesAfterEnv et avant le code de test lui-même.

astuce

Si votre script de configuration est un module CJS, il peut exporter une fonction asynchrone. Jest appellera la fonction et attendra son résultat, ce qui est utile pour récupérer des données de manière asynchrone. Pour les modules ESM, utilisez simplement un await de haut niveau pour obtenir le même résultat.

setupFilesAfterEnv [array]​

Valeur par défaut : []

Liste de chemins vers des modules exécutant du code pour configurer le framework de test avant chaque fichier de test. Comme setupFiles s'exécute avant l'installation du framework, ces scripts permettent d'exécuter du code juste après son installation mais avant le code de test.

En d'autres termes, setupFilesAfterEnv sert pour le code répété dans chaque fichier de test. L'installation du framework rend accessibles les globals, l'objet jest et expect. Par exemple, ajoutez des matchers supplémentaires via jest-extended ou appelez des hooks de configuration et nettoyage :

setup-jest.js
const matchers = require('jest-extended');
expect.extend(matchers);

afterEach(() => {
  jest.useRealTimers();
});
/** @type {import('jest').Config} */
const config = {
  setupFilesAfterEnv: ['<rootDir>/setup-jest.js'],
};

module.exports = config;

showSeed [boolean]​

Par défaut : false

Équivalent du flag --showSeed pour afficher la graine dans le résumé du rapport de test.

slowTestThreshold [number]​

Par défaut : 5

Le nombre de secondes après lequel un test est considéré comme lent et signalé comme tel dans les résultats.

snapshotFormat [object]​

Par défaut : {escapeString: false, printBasicPrototype: false}

Permet de remplacer des options spécifiques de formatage des instantanés documentées dans le readme de pretty-format, à l'exception de compareKeys et plugins. Par exemple, cette configuration ferait que le formateur d'instantanés n'imprime pas de préfixe pour "Object" et "Array" :

/** @type {import('jest').Config} */
const config = {
  snapshotFormat: {
    printBasicPrototype: false,
  },
};

module.exports = config;
some.test.js
test('does not show prototypes for object and array inline', () => {
  const object = {
    array: [{hello: 'Danger'}],
  };
  expect(object).toMatchInlineSnapshot(`
    {
      "array": [
        {
          "hello": "Danger",
        },
      ],
    }
  `);
});

snapshotResolver [chaîne]​

Par défaut : undefined

Le chemin vers un module capable de résoudre le chemin test<->snapshot. Cette option de configuration vous permet de personnaliser l'emplacement où Jest stocke les fichiers snapshot sur le disque.

custom-resolver.js
module.exports = {
  // resolves from test to snapshot path
  resolveSnapshotPath: (testPath, snapshotExtension) =>
    testPath.replace('__tests__', '__snapshots__') + snapshotExtension,

  // resolves from snapshot to test path
  resolveTestPath: (snapshotFilePath, snapshotExtension) =>
    snapshotFilePath
      .replace('__snapshots__', '__tests__')
      .slice(0, -snapshotExtension.length),

  // Example test path, used for preflight consistency check of the implementation above
  testPathForConsistencyCheck: 'some/__tests__/example.test.js',
};

snapshotSerializers [array<string>]​

Valeur par défaut : []

Une liste de chemins vers les modules de sérialisation d'instantanés que Jest doit utiliser pour les tests d'instantanés.

Jest dispose de sérialiseurs par défaut pour les types JavaScript natifs, les éléments HTML (Jest 20.0.0+), ImmutableJS (Jest 20.0.0+) et les éléments React. Consultez le tutoriel sur les tests d'instantanés pour plus d'informations.

custom-serializer.js
module.exports = {
  serialize(val, config, indentation, depth, refs, printer) {
    return `Pretty foo: ${printer(val.foo, config, indentation, depth, refs)}`;
  },

  test(val) {
    return val && Object.prototype.hasOwnProperty.call(val, 'foo');
  },
};

printer est une fonction qui sérialise une valeur en utilisant les plugins existants.

Ajoutez custom-serializer à votre configuration Jest :

/** @type {import('jest').Config} */
const config = {
  snapshotSerializers: ['path/to/custom-serializer.js'],
};

module.exports = config;

Enfin, les tests ressembleraient à ceci :

test(() => {
  const bar = {
    foo: {
      x: 1,
      y: 2,
    },
  };

  expect(bar).toMatchSnapshot();
});

Instantané rendu :

Pretty foo: Object {
  "x": 1,
  "y": 2,
}
astuce

Pour rendre une dépendance explicite plutôt qu'implicite, vous pouvez appeler expect.addSnapshotSerializer pour ajouter un module à un fichier de test spécifique, au lieu d'ajouter son chemin à snapshotSerializers dans la configuration Jest.

Plus d'informations sur l'API des sérialiseurs sont disponibles ici.

testEnvironment [chaîne]​

Par défaut : "node"

L'environnement de test qui sera utilisé pour les tests. Par défaut dans Jest, l'environnement est un environnement Node.js. Si vous créez une application web, vous pouvez plutôt utiliser un environnement de type navigateur via jsdom.

En ajoutant un docblock @jest-environment en haut du fichier, vous pouvez spécifier un autre environnement à utiliser pour tous les tests de ce fichier :

/**
 * @jest-environment jsdom
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

Vous pouvez créer votre propre module qui sera utilisé pour configurer l'environnement de test. Le module doit exporter une classe avec les méthodes setup, teardown et getVmContext. Vous pouvez également transmettre des variables de ce module à vos suites de test en les assignant à l'objet this.global – cela les rendra disponibles dans vos suites de test en tant que variables globales. Le constructeur reçoit globalConfig et projectConfig comme premier argument, et testEnvironmentContext comme second.

La classe peut éventuellement exposer une méthode asynchrone handleTestEvent pour se lier aux événements déclenchés par jest-circus. Normalement, le runner de tests jest-circus se met en pause jusqu'à ce qu'une promesse renvoyée par handleTestEvent soit résolue, sauf pour les événements suivants : start_describe_definition, finish_describe_definition, add_hook, add_test ou error (pour la liste à jour, consultez le type SyncEvent dans les définitions de types). Cela est dû à des raisons de rétrocompatibilité et à la signature de process.on('unhandledRejection', callback), mais cela ne pose généralement pas de problème pour la plupart des cas d'usage.

Les pragmas docblock dans les fichiers de test seront transmis au constructeur de l'environnement et peuvent être utilisés pour une configuration par test. Si le pragma n'a pas de valeur, il sera présent dans l'objet avec une valeur vide. Si le pragma est absent, il ne figurera pas dans l'objet.

Pour utiliser cette classe comme environnement personnalisé, référencez-la par son chemin complet dans le projet. Par exemple, si votre classe est stockée dans my-custom-environment.js dans un sous-dossier de votre projet, l'annotation pourrait ressembler à ceci :

/**
 * @jest-environment ./src/test/my-custom-environment
 */
info

TestEnvironment est isolé (sandboxed). Chaque suite de tests déclenchera le setup/teardown dans son propre TestEnvironment.

Exemple :

// my-custom-environment
const NodeEnvironment = require('jest-environment-node').TestEnvironment;

class CustomEnvironment extends NodeEnvironment {
  constructor(config, context) {
    super(config, context);
    console.log(config.globalConfig);
    console.log(config.projectConfig);
    this.testPath = context.testPath;
    this.docblockPragmas = context.docblockPragmas;
  }

  async setup() {
    await super.setup();
    await someSetupTasks(this.testPath);
    this.global.someGlobalObject = createGlobalObject();

    // Will trigger if docblock contains @my-custom-pragma my-pragma-value
    if (this.docblockPragmas['my-custom-pragma'] === 'my-pragma-value') {
      // ...
    }
  }

  async teardown() {
    this.global.someGlobalObject = destroyGlobalObject();
    await someTeardownTasks();
    await super.teardown();
  }

  getVmContext() {
    return super.getVmContext();
  }

  async handleTestEvent(event, state) {
    if (event.name === 'test_start') {
      // ...
    }
  }
}

module.exports = CustomEnvironment;
// my-test-suite
/**
 * @jest-environment ./my-custom-environment
 */
let someGlobalObject;

beforeAll(() => {
  someGlobalObject = globalThis.someGlobalObject;
});

testEnvironmentOptions [Object]​

Par défaut : {}

Options d'environnement de test qui seront transmises au testEnvironment. Les options pertinentes dépendent de l'environnement.

Par exemple, vous pouvez surcharger les options passées à jsdom :

/** @type {import('jest').Config} */
const config = {
  testEnvironment: 'jsdom',
  testEnvironmentOptions: {
    html: '<html lang="zh-cmn-Hant"></html>',
    url: 'https://jestjs.io/',
    userAgent: 'Agent/007',
  },
};

module.exports = config;

jest-environment-jsdom et jest-environment-node permettent tous deux de spécifier customExportConditions, qui vous permet de contrôler quelles versions d'une bibliothèque sont chargées depuis les exports dans package.json. jest-environment-jsdom utilise par défaut ['browser']. jest-environment-node utilise par défaut ['node', 'node-addons'].

/** @type {import('jest').Config} */
const config = {
  testEnvironment: 'jsdom',
  testEnvironmentOptions: {
    customExportConditions: ['react-native'],
  },
};

module.exports = config;

Ces options peuvent également être passées dans un docblock, similairement à testEnvironment. La chaîne d'options doit être analysable par JSON.parse :

/**
 * @jest-environment jsdom
 * @jest-environment-options {"url": "https://jestjs.io/"}
 */

test('use jsdom and set the URL in this test file', () => {
  expect(window.location.href).toBe('https://jestjs.io/');
});

testFailureExitCode [number]​

Par défaut : 1

Code de sortie que Jest renvoie en cas d'échec d'un test.

info

Ceci ne modifie pas le code de sortie en cas d'erreurs de Jest (ex : configuration invalide).

testMatch [array<string>]​

(par défaut : [ "**/__tests__/**/*.[jt]s?(x)", "**/?(*.)+(spec|test).[jt]s?(x)" ])

Les motifs globaux utilisés par Jest pour détecter les fichiers de test. Par défaut, il recherche les fichiers .js, .jsx, .ts et .tsx dans les dossiers __tests__, ainsi que les fichiers avec les suffixes .test ou .spec (ex : Component.test.js ou Component.spec.js). Il trouvera aussi les fichiers nommés test.js ou spec.js.

Consultez le package micromatch pour les détails des motifs que vous pouvez spécifier.

Voir aussi testRegex [string | array<string>], mais notez que vous ne pouvez pas spécifier les deux options simultanément.

astuce

Chaque motif glob est appliqué dans l'ordre spécifié dans la configuration. Par exemple ["!**/__fixtures__/**", "**/__tests__/**/*.js"] n'exclura pas __fixtures__ car la négation est écrasée par le second motif. Pour que la négation fonctionne dans cet exemple, elle doit venir après **/__tests__/**/*.js.

testPathIgnorePatterns [array<string>]​

Par défaut : ["/node_modules/"]

Un tableau de motifs d'expression régulière qui sont comparés à tous les chemins de test avant leur exécution. Si le chemin correspond à l'un des motifs, le test est ignoré.

Ces motifs comparent le chemin complet. Utilisez le jeton <rootDir> pour inclure le chemin racine de votre projet et éviter d'ignorer accidentellement des fichiers dans différents environnements. Exemple : ["<rootDir>/build/", "<rootDir>/node_modules/"].

testRegex [string | array<string>]​

Par défaut : (/__tests__/.*|(\\.|/)(test|spec))\\.[jt]sx?$

Le ou les motifs utilisés par Jest pour détecter les fichiers de test. Par défaut, il recherche les fichiers .js, .jsx, .ts et .tsx dans les dossiers __tests__, ainsi que les fichiers suffixés par .test ou .spec (ex. Component.test.js ou Component.spec.js). Il inclut aussi les fichiers nommés test.js ou spec.js. Voir aussi testMatch [array<string>], mais notez que ces options sont mutuellement exclusives.

Visualisation du motif par défaut :

├── __tests__
│   └── component.spec.js # test
│   └── anything # test
├── package.json # not test
├── foo.test.js # test
├── bar.spec.jsx # test
└── component.js # not test
info

testRegex compare le chemin absolu des fichiers. Un dossier dont le nom correspond au motif exécutera tous ses fichiers comme tests.

testResultsProcessor [string]​

Par défaut : undefined

Cette option permet d'utiliser un processeur de résultats personnalisé. Ce processeur doit être un module Node exportant une fonction qui reçoit un objet avec la structure suivante en premier argument et le retourne :

{
  "success": boolean,
  "startTime": epoch,
  "numTotalTestSuites": number,
  "numPassedTestSuites": number,
  "numFailedTestSuites": number,
  "numRuntimeErrorTestSuites": number,
  "numTotalTests": number,
  "numPassedTests": number,
  "numFailedTests": number,
  "numPendingTests": number,
  "numTodoTests": number,
  "openHandles": Array<Error>,
  "testResults": [{
    "numFailingTests": number,
    "numPassingTests": number,
    "numPendingTests": number,
    "testResults": [{
      "title": string (message in it block),
      "status": "failed" | "pending" | "passed",
      "ancestorTitles": [string (message in describe blocks)],
      "failureMessages": [string],
      "numPassingAsserts": number,
      "location": {
        "column": number,
        "line": number
      },
      "duration": number | null
    },
    ...
    ],
    "perfStats": {
      "start": epoch,
      "end": epoch
    },
    "testFilePath": absolute path to test file,
    "coverage": {}
  },
  "testExecError:" (exists if there was a top-level failure) {
    "message": string
    "stack": string
  }
  ...
  ]
}

testResultsProcessor et reporters sont similaires, mais le processeur n'est appelé qu'après l'exécution de tous les tests, tandis qu'un reporter peut recevoir les résultats au fur et à mesure.

testRunner [string]​

Par défaut : jest-circus/runner

Cette option permet d'utiliser un exécuteur de tests personnalisé. La valeur par défaut est jest-circus. Spécifiez le chemin d'accès à l'implémentation de votre exécuteur.

Le module d'exécution doit exporter une fonction avec cette signature :

function testRunner(
  globalConfig: GlobalConfig,
  config: ProjectConfig,
  environment: Environment,
  runtime: Runtime,
  testPath: string,
): Promise<TestResult>;

Un exemple est disponible dans notre exécuteur jasmine2 par défaut.

testSequencer [string]​

Par défaut : @jest/test-sequencer

Cette option permet d'utiliser un séquenceur personnalisé à la place de celui par défaut de Jest.

astuce

sort et shard peuvent optionnellement retourner une Promise.

Exemple de tri alphabétique des chemins de test :

custom-sequencer.js
const Sequencer = require('@jest/test-sequencer').default;

class CustomSequencer extends Sequencer {
  /**
   * Select tests for shard requested via --shard=shardIndex/shardCount
   * Sharding is applied before sorting
   */
  shard(tests, {shardIndex, shardCount}) {
    const shardSize = Math.ceil(tests.length / shardCount);
    const shardStart = shardSize * (shardIndex - 1);
    const shardEnd = shardSize * shardIndex;

    return [...tests]
      .sort((a, b) => (a.path > b.path ? 1 : -1))
      .slice(shardStart, shardEnd);
  }

  /**
   * Sort test to determine order of execution
   * Sorting is applied after sharding
   */
  sort(tests) {
    // Test structure information
    // https://github.com/jestjs/jest/blob/6b8b1404a1d9254e7d5d90a8934087a9c9899dab/packages/jest-runner/src/types.ts#L17-L21
    const copyTests = [...tests];
    return copyTests.sort((testA, testB) => (testA.path > testB.path ? 1 : -1));
  }
}

module.exports = CustomSequencer;

Ajoutez custom-sequencer à votre configuration Jest :

/** @type {import('jest').Config} */
const config = {
  testSequencer: 'path/to/custom-sequencer.js',
};

module.exports = config;

testTimeout [number]​

Par défaut : 5000

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

transform [object<string, pathToTransformer | [pathToTransformer, object]>]​

Par défaut : {"\\.[jt]sx?$": "babel-jest"}

Une correspondance entre des expressions régulières et des chemins vers des transformateurs. Optionnellement, un tuple avec des options de configuration peut être passé en second argument : {filePattern: ['path-to-transformer', {options}]}. Par exemple, voici comment configurer babel-jest pour un comportement non par défaut : {'\\.js$': ['babel-jest', {rootMode: 'upward'}]}.

Jest exécute le code de votre projet en JavaScript, donc un transformateur est nécessaire si vous utilisez une syntaxe non prise en charge nativement par Node (comme JSX, TypeScript, templates Vue). Par défaut, Jest utilise le transformateur babel-jest, qui charge la configuration Babel de votre projet et transforme tout fichier correspondant à l'expression régulière /\.[jt]sx?$/ (autrement dit, tout fichier .js, .jsx, .ts ou .tsx). De plus, babel-jest injecte le plugin Babel nécessaire pour le hoisting des mocks abordé dans ES Module mocking.

Consultez la section Transformation de code pour plus de détails et des instructions sur la création de votre propre transformateur.

astuce

Gardez à l'esprit qu'un transformateur ne s'exécute qu'une fois par fichier sauf si ce dernier a été modifié.

N'oubliez pas d'inclure explicitement le transformateur par défaut babel-jest si vous souhaitez l'utiliser conjointement avec d'autres prétraitements de code :

/** @type {import('jest').Config} */
const config = {
  transform: {
    '\\.[jt]sx?$': 'babel-jest',
    '\\.css$': 'some-css-transformer',
  },
};

module.exports = config;

transformIgnorePatterns [array<string>]​

Default: ["/node_modules/", "\\.pnp\\.[^\\\/]+$"]

Un tableau de chaînes de motifs regex comparés à tous les chemins de fichiers avant transformation. Si le chemin correspond à l'un des motifs, le fichier ne sera pas transformé.

Fournir des motifs regex qui se chevauchent peut entraîner la non-transformation de fichiers que vous souhaitiez transformer. Par exemple :

/** @type {import('jest').Config} */
const config = {
  transformIgnorePatterns: ['/node_modules/(?!(foo|bar)/)', '/bar/'],
};

module.exports = config;

Le premier motif correspondra (et donc ne transformera pas) les fichiers dans /node_modules sauf ceux dans /node_modules/foo/ et /node_modules/bar/. Le second motif correspondra (et donc ne transformera pas) les fichiers dans tout chemin contenant /bar/. Combinés, les fichiers dans /node_modules/bar/ ne seront pas transformés car ils correspondent au second motif, même s'ils étaient exclus par le premier.

Il arrive parfois (surtout dans les projets React Native ou TypeScript) que des modules tiers soient publiés sous forme de code non transpilé. Comme tous les fichiers dans node_modules ne sont pas transformés par défaut, Jest ne comprendra pas leur code, provoquant des erreurs de syntaxe. Pour contourner ce problème, utilisez transformIgnorePatterns pour autoriser la transpilation de ces modules. Vous trouverez un bon exemple dans le Guide React Native.

Ces motifs regex sont comparés au chemin complet. Utilisez le jeton <rootDir> pour inclure le chemin racine de votre projet et éviter d'ignorer accidentellement vos fichiers dans différents environnements pouvant avoir des racines différentes.

/** @type {import('jest').Config} */
const config = {
  transformIgnorePatterns: [
    '<rootDir>/bower_components/',
    '<rootDir>/node_modules/',
  ],
};

module.exports = config;
astuce

Si vous utilisez pnpm et devez transformer certains packages sous node_modules, notez que ces packages (par ex. node_modules/package-a/) sont symboliquement liés au chemin sous .pnpm (par ex. node_modules/.pnpm/package-a@x.x.x/node_modules/package-a/). Ainsi, utiliser directement <rootDir>/node_modules/(?!(package-a|@scope/pkg-b)/) ne sera pas reconnu. Utilisez plutôt :

/** @type {import('jest').Config} */
const config = {
  transformIgnorePatterns: [
    '<rootDir>/node_modules/.pnpm/(?!(package-a|@scope\\+pkg-b)@)',
    /* if config file is under '~/packages/lib-a/' */
    `${path.join(
      __dirname,
      '../..',
    )}/node_modules/.pnpm/(?!(package-a|@scope\\+pkg-b)@)`,
    /* or using relative pattern to match the second 'node_modules/' in 'node_modules/.pnpm/@scope+pkg-b@x.x.x/node_modules/@scope/pkg-b/' */
    'node_modules/(?!.pnpm|package-a|@scope/pkg-b)',
  ],
};

module.exports = config;

Notez que les noms de dossiers sous .pnpm utilisent le format "nom-du-package@version". Écrire / ne sera pas reconnu, mais utiliser @ fonctionnera.

unmockedModulePathPatterns [array<string>]​

Valeur par défaut : []

Tableau de motifs regex qui seront comparés à tous les modules avant que le chargeur de modules ne retourne automatiquement un mock. Si le chemin d'un module correspond à l'un de ces motifs, il ne sera pas automatiquement mocké par le chargeur.

Ceci est utile pour les modules "utilitaire" couramment utilisés (comme underscore, lodash, etc.) qui sont presque toujours des détails d'implémentation. Il est préférable de garder cette liste aussi petite que possible et d'utiliser explicitement jest.mock()/jest.unmock() dans les tests individuels. Une configuration explicite par test est plus facile à comprendre pour les lecteurs.

Il est possible de surcharger ce paramètre dans des tests individuels en appelant explicitement jest.mock() en haut du fichier de test.

verbose [boolean]​

Valeur par défaut : false (ou true s'il n'y a qu'un seul fichier de test)

Indique si chaque test individuel doit être rapporté pendant l'exécution. Toutes les erreurs seront également affichées à la fin.

watchPathIgnorePatterns [array<string>]​

Valeur par défaut : []

Un tableau de motifs RegExp comparés à tous les chemins de fichiers sources avant de réexécuter les tests en mode watch. Si le chemin correspond à l'un des motifs, sa mise à jour ne déclenchera pas de réexécution des tests.

Ces motifs sont comparés au chemin complet. Utilisez le jeton <rootDir> pour inclure le chemin racine de votre projet et éviter d'ignorer accidentellement des fichiers dans différents environnements. Exemple : ["<rootDir>/node_modules/"].

Même si rien n'est spécifié ici, le watcher ignorera les dossiers de contrôle de version (.git, .hg, .sl). Les autres fichiers et dossiers cachés (commençant par un point .) sont surveillés par défaut. Pensez à échapper le point dans watchPathIgnorePatterns car c'est un caractère spécial RegExp.

/** @type {import('jest').Config} */
const config = {
  watchPathIgnorePatterns: ['<rootDir>/\\.tmp/', '<rootDir>/bar/'],
};

module.exports = config;

watchPlugins [array<string | [string, Object]>]​

Valeur par défaut : []

Cette option permet d'utiliser des plugins watch personnalisés. Plus d'informations ici.

Exemples de plugins watch :

info

Les valeurs dans watchPlugins peuvent omettre le préfixe jest-watch- des noms de packages.

watchman [boolean]​

Par défaut : true

Indique s'il faut utiliser watchman pour l'exploration des fichiers.

workerIdleMemoryLimit [number|string]​

Par défaut : undefined

Spécifie la limite mémoire des workers avant leur recyclement, solutionnant principalement ce problème.

Après l'exécution d'un test, l'utilisation mémoire du worker est vérifiée. Si elle dépasse la valeur spécifiée, le worker est terminé et relancé. La limite peut être spécifiée de plusieurs façons, Math.floor étant utilisé pour obtenir une valeur entière :

  • 0 - Redémarre toujours le worker entre les tests.

  • <= 1 - La valeur est considérée comme un pourcentage de la mémoire système. 0.5 limite donc le worker à la moitié de la mémoire totale.

  • \> 1 - Supposé être une valeur fixe en octets. En raison de la règle précédente, si vous vouliez une valeur de 1 octet (je ne vois pas l'utilité), vous pourriez utiliser 1.1.

  • Avec unités

    • 50% - Comme ci-dessus, pourcentage de la mémoire système totale
    • 100KB, 65MB, etc. - Avec unités pour indiquer une limite mémoire fixe
      • K / KB - Kilooctets (x1000)
      • KiB - Kibioctets (x1024)
      • M / MB - Mégaoctets
      • MiB - Mébioctets
      • G / GB - Gigaoctets
      • GiB - Gibioctets
attention

La limite mémoire basée sur un pourcentage ne fonctionne pas sur les workers Linux CircleCI en raison d'une mémoire système incorrectement rapportée.

/** @type {import('jest').Config} */
const config = {
  workerIdleMemoryLimit: 0.2,
};

module.exports = config;

// [string]​

Cette option permet d'ajouter des commentaires dans package.json. Incluez le texte du commentaire comme valeur de cette clé :

package.json
{
  "name": "my-project",
  "jest": {
    "//": "Comment goes here",
    "verbose": true
  }
}

workerThreads​

Par défaut : false

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

L'utilisation de worker threads peut aider à améliorer les performances.

attention

Il s'agit d'une fonctionnalité expérimentale. Notez que les worker threads utilisent le clonage structuré au lieu de JSON.stringify() pour sérialiser les messages. Cela signifie que les objets JavaScript natifs comme BigInt, Map ou Set seront sérialisés correctement. Cependant, les propriétés supplémentaires définies sur Error, Map ou Set ne seront pas transmises lors de la sérialisation. Pour plus de détails, consultez l'article sur le clonage structuré.