Aller au contenu principal
Version : Suivant

Globals

Dans vos fichiers de test, Jest place chacune de ces méthodes et objets dans l'environnement global. You don't have to require or import anything to use them. Cependant, si vous préférez les importations explicites, vous pouvez faire import {describe, expect, test} from '@jest/globals'.

info

Les exemples TypeScript de cette page ne fonctionneront comme documenté que si vous importez explicitement les API Jest :

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

Consult the Getting Started guide for details on how to setup Jest with TypeScript.

Méthodes


Référence

afterAll(fn, timeout)

Exécute une fonction une fois que tous les tests de ce fichier sont terminés. Si la fonction retourne une promesse ou est un générateur, Jest attend que cette promesse soit résolue avant de continuer.

En option, vous pouvez fournir un timeout (en millisecondes) pour spécifier le temps d'attente avant l'abandon. The default timeout is 5 seconds.

Cela est très souvent utile pour réinitialiser des configurations globales, partagées par différents tests.

Par exemple :

const globalDatabase = makeGlobalDatabase();

function cleanUpDatabase(db) {
db.cleanUp();
}

afterAll(() => {
cleanUpDatabase(globalDatabase);
});

test('peut trouver des choses', () => {
return globalDatabase.find('thing', {}, results => {
expect(results.length).toBeGreaterThan(0);
});
});

test('peut insérer un truc', () => {
return globalDatabase.insert('thing', makeThing(), response => {
expect(response.success).toBeTruthy();
});
});

Ici afterAll s'assure que cleanUpDatabase est appelé après l'exécution de tous les tests.

Si afterAll se trouve à l'intérieur d'un bloc describe , il s'exécute à la fin du bloc describe.

Si vous voulez exécuter un nettoyage après chaque test plutôt qu'après tous les tests, utilisez plutôt afterEach.

afterEach(fn, timeout)

Exécute une fonction après l'achèvement de chacun des tests de ce fichier. Si la fonction retourne une promesse ou est un générateur, Jest attend que cette promesse soit résolue avant de continuer.

En option, vous pouvez fournir un timeout (en millisecondes) pour spécifier le temps d'attente avant l'abandon. The default timeout is 5 seconds.

Ceci est souvent utile si vous voulez nettoyer un état temporaire qui est créé par chaque test.

Par exemple :

const globalDatabase = makeGlobalDatabase();

function cleanUpDatabase(db) {
db.cleanUp();
}

afterEach(() => {
cleanUpDatabase(globalDatabase);
});

test('peut trouver des choses', () => {
return globalDatabase.find('thing', {}, results => {
expect(results.length).toBeGreaterThan(0);
});
});

test('peut insérer un truc', () => {
return globalDatabase.insert('thing', makeThing(), response => {
expect(response.success).toBeTruthy();
});
});

Ici afterEach s'assure que cleanUpDatabase est appelé après chaque exécution du test.

Si afterEach est à l'intérieur d'un bloc describe, il s'exécute uniquement après les tests qui sont à l'intérieur de ce bloc describe.

Si vous voulez exécuter un nettoyage une seule fois, après l'exécution de tous les tests, utilisez plutôt afterAll.

beforeAll(fn, timeout)

Exécute une fonction avant l'exécution de tous les tests de ce fichier. Si la fonction retourne une promesse ou est un générateur, Jest attend que cette promesse soit résolue avant d'exécuter des tests.

En option, vous pouvez fournir un timeout (en millisecondes) pour spécifier le temps d'attente avant l'abandon. The default timeout is 5 seconds.

Ceci est souvent utile si vous voulez mettre en place un état global qui sera utilisé par de nombreux tests.

Par exemple :

const globalDatabase = makeGlobalDatabase();

beforeAll(() => {
// Efface la base de données et ajoute des données de test.
// Jest attendra que cette promesse soit résolue avant d'exécuter des tests.
return globalDatabase.clear().then(() => {
return globalDatabase.insert({testData: 'foo'});
});
});

// Puisque nous ne configurons la base de données qu'une seule fois dans cet exemple, il est important
// que nos tests ne la modifient pas.
test('peut trouver des choses', () => {
return globalDatabase.find('thing', {}, results => {
expect(results.length).toBeGreaterThan(0);
});
});

Ici beforeAll s'assure que la base de données est configurée avant que les tests ne s'exécutent. Si la configuration était synchrone, vous pourriez le faire sans beforeAll. La clé, c'est que Jest attendra la résolution d'une promesse, de sorte que vous puissiez également avoir une configuration asynchrone.

Si beforeAll est à l'intérieur d'un bloc describe, il s'exécute au début du bloc describe.

Si vous voulez exécuter quelque chose avant chaque test au lieu d'une seule exécution avant tous les tests, utilisez plutôt beforeEach.

beforeEach(fn, timeout)

Exécute une fonction avant que chaque test de ce fichier ne s'exécute. Si la fonction retourne une promesse ou est un générateur, Jest attend que cette promesse soit résolue avant de lancer le test.

En option, vous pouvez fournir un timeout (en millisecondes) pour spécifier le temps d'attente avant l'abandon. The default timeout is 5 seconds.

Ceci est souvent utile si vous voulez réinitialiser un état global qui sera utilisé par de nombreux tests.

Par exemple :

const globalDatabase = makeGlobalDatabase();

beforeEach(() => {
// Efface la base de données et ajoute des données de test.
// Jest attendra que cette promesse soit résolue avant d'exécuter des tests.
return globalDatabase.clear().then(() => {
return globalDatabase.insert({testData: 'foo'});
});
});

test('peut trouver des choses', () => {
return globalDatabase.find('thing', {}, results => {
expect(results.length).toBeGreaterThan(0);
});
});

test('peut insérer un truc', () => {
return globalDatabase.insert('thing', makeThing(), response => {
expect(response.success).toBeTruthy();
});
});

Ici, le beforeEach assure que la base de données est réinitialisée pour chaque test.

Si beforeEach est à l'intérieur d'un bloc describe, il s'exécute pour chaque test du bloc describe.

Si vous n'avez besoin d'exécuter un code de configuration qu'une seule fois, avant l'exécution de tous les tests, utilisez plutôt beforeAll.

describe(name, fn)

describe(name, fn) crée un bloc qui regroupe plusieurs tests liés. Par exemple, si vous avez un objet myBeverage qui est censé être délicieux mais pas amer, vous pouvez le tester ainsi :

const myBeverage = {
delicious: true,
sour: false,
};

describe('ma boisson', () => {
test('est délicieuse', () => {
expect(myBeverage.delicious).toBeTruthy();
});

test('n\'est pas amer', () => {
expect(myBeverage.sour).toBeFalsy();
});
});

Ce n'est pas nécessaire - vous pouvez écrire les blocs test directement au niveau supérieur. Mais cela peut être pratique si vous préférez que vos tests soient organisés en groupes.

Vous pouvez également imbriquer les blocs describe si vous avez une hiérarchie de tests :

const binaryStringToNumber = binString => {
if (!/^[01]+$/.test(binString)) {
throw new CustomError('Not a binary number.');
}

return parseInt(binString, 2);
};

describe('binaryStringToNumber', () => {
describe('given an invalid binary string', () => {
test('composed of non-numbers throws CustomError', () => {
expect(() => binaryStringToNumber('abc')).toThrow(CustomError);
});

test('with extra whitespace throws CustomError', () => {
expect(() => binaryStringToNumber(' 100')).toThrow(CustomError);
});
});

describe('given a valid binary string', () => {
test('returns the correct number', () => {
expect(binaryStringToNumber('100')).toBe(4);
});
});
});

describe.each(table)(name, fn, timeout)

Utilisez describe.each si vous continuez à dupliquer les mêmes suites de tests avec des données différentes. describe.each permet d'écrire la suite de tests une fois et de lui passer les données.

describe.each est disponible avec deux API :

1. describe.each(table)(name, fn, timeout)

  • table : Array de tableaux avec les arguments qui sont passés dans le fn pour chaque ligne. If you pass in a 1D array of primitives, internally it will be mapped to a table i.e. [1, 2, 3] -> [[1], [2], [3]].

  • name : String le titre de la suite de test.

    • Générez des titres de test uniques en injectant de manière placée des paramètres avec le formatage de printf :
      • %p - pretty-format.
      • %s- Chaîne.
      • %d- Nombre.
      • %i - Entier.
      • %f - Valeur à virgule flottante.
      • %j - JSON.
      • %o - Objet.
      • %# - Index du cas de test.
      • %% - unique signe de pourcentage ('%'). Cela ne sert pas d'argument.
    • Ou générez des titres de test uniques en injectant les propriétés de l'objet du cas de test avec $variable
      • Pour injecter des valeurs d'objets imbriqués, vous pouvez fournir un keyPath, c'est-à-dire $variable.path.to.value
      • Vous pouvez utiliser $# pour injecter l'index du cas de test
      • Vous ne pouvez pas utiliser $variable avec le formatage printf sauf pour %%
  • fn : Function la suite de tests à exécuter, c'est la fonction qui recevra les paramètres de chaque ligne comme arguments de fonction.

  • En option, vous pouvez fournir un timeout (en millisecondes) pour spécifier combien de temps attendre pour chaque ligne avant d'abandonner. The default timeout is 5 seconds.

Exemple :

describe.each([
[1, 1, 2],
[1, 2, 3],
[2, 1, 3],
])('.add(%i, %i)', (a, b, expected) => {
test(`retourne ${expected}`, () => {
expect(a + b).toBe(expected);
});

test(`la valeur retournée ne doit pas être supérieure à ${expected}`, () => {
expect(a + b).not.toBeGreaterThan(expected);
});

test(`la valeur retournée ne doit pas être inférieure à ${expected}`, () => {
expect(a + b).not.toBeLessThan(expected);
});
});
describe.each([
{a: 1, b: 1, expected: 2},
{a: 1, b: 2, expected: 3},
{a: 2, b: 1, expected: 3},
])('.add($a, $b)', ({a, b, expected}) => {
test(`retourne ${expected}`, () => {
expect(a + b).toBe(expected);
});

test(`la valeur retournée ne doit pas être supérieure à ${expected}`, () => {
expect(a + b).not.toBeGreaterThan(expected);
});

test(`la valeur retournée ne doit pas être inférieure à ${expected}`, () => {
expect(a + b).not.toBeLessThan(expected);
});
});

2. describe.each`table`(name, fn, timeout)

  • table: Littéral de template étiqueté
    • La première ligne contient l'entêtes des colonnes avec les noms de variables séparés par |
    • Une ou plusieurs lignes de données successives sont fournies sous forme d'expressions littérales de template utilisant la syntaxe ${value}.
  • name : String le titre de la suite de test, utilisez $variable pour injecter des données de test dans le titre de la suite à partir des expressions du template étiqueté, et $# pour l'index de la ligne.
    • Pour injecter des valeurs d'objets imbriqués, vous pouvez fournir un keyPath, c'est-à-dire $variable.path.to.value
  • fn : Function la suite de tests à exécuter, c'est la fonction qui recevra l'objet de données de test.
  • En option, vous pouvez fournir un timeout (en millisecondes) pour spécifier combien de temps attendre pour chaque ligne avant d'abandonner. The default timeout is 5 seconds.

Exemple :

describe.each`
a | b | expected
${1} | ${1} | ${2}
${1} | ${2} | ${3}
${2} | ${1} | ${3}
`('$a + $b', ({a, b, expected}) => {
test(`retourne ${expected}`, () => {
expect(a + b).toBe(expected);
});

test(`valeur retournée ne pas être supérieure à ${expected}`, () => {
expect(a + b).not.toBeGreaterThan(expected);
});

test(`valeur retournée ne pas être inférieure à ${expected}`, () => {
expect(a + b).not.toBeLessThan(expected);
});
});

describe.only(name, fn)

Aussi sous l'alias : fdescribe(name, fn)

Vous pouvez utiliser describe.only si vous voulez exécuter un seul bloc describe :

describe.only('ma boisson', () => {
test('est délicieuse', () => {
expect(myBeverage.delicious).toBeTruthy();
});

test('n\'est pas amer (sour)', () => {
expect(myBeverage.sour).toBeFalsy();
});
});

describe('mon autre boisson', () => {
// ... sera ignoré
});

describe.only.each(table)(name, fn)

Aussi sous les alias : fdescribe.each(table)(name, fn) et fdescribe.each`table`(name, fn)

Utilisez describe.only.each si vous voulez seulement exécuter des suites de tests spécifiques de tests pilotés par les données.

describe.only.each est disponible avec deux API :

describe.only.each(table)(name, fn)

describe.only.each([
[1, 1, 2],
[1, 2, 3],
[2, 1, 3],
])('.add(%i, %i)', (a, b, expected) => {
test(`retourne ${expected}`, () => {
expect(a + b).toBe(expected);
});
});

test('ne sera pas exécuté', () => {
expect(1 / 0).toBe(Infinity);
});

describe.only.each`table`(name, fn)

describe.only.each`
a | b | expected
${1} | ${1} | ${2}
${1} | ${2} | ${3}
${2} | ${1} | ${3}
`('retourne $expected quand $a est ajouté à $b', ({a, b, expected}) => {
test('passe', () => {
expect(a + b).toBe(expected);
});
});

test('ne sera pas exécuté', () => {
expect(1 / 0).toBe(Infinity);
});

describe.skip(name, fn)

Aussi sous l'alias : xdescribe(name, fn)

Vous pouvez utiliser describe.skip si vous ne voulez pas exécuter les tests d'un bloc particulier describe :

describe('ma boisson', () => {
test('est délicieuse', () => {
expect(myBeverage.delicious).toBeTruthy();
});

test('n\'est pas amer (sour)', () => {
expect(myBeverage.sour).toBeFalsy();
});
});

describe.skip('mon autre boisson', () => {
// ... sera ignoré
});

L'utilisation de describe.skip est souvent une alternative plus propre que la mise en commentaire temporaire d'une partie des tests. Attention, le bloc describe s'exécutera quand même. Si vous avez une configuration qui doit également être ignorée, faites-le dans un bloc beforeAll ou beforeEach.

describe.skip.each(table)(name, fn)

Aussi sous les alias : xdescribe.each(table)(name, fn) et xdescribe.each`table`(name, fn)

Utilisez describe.skip.each si vous voulez arrêter d'exécuter une suite de tests pilotés par les données.

describe.skip.chaque est disponible avec deux API :

describe.skip.each(table)(name, fn)

describe.skip.each([
[1, 1, 2],
[1, 2, 3],
[2, 1, 3],
])('.add(%i, %i)', (a, b, expected) => {
test(`retourne ${expected}`, () => {
expect(a + b).toBe(expected); // will not be ran
});
});

test('sera exécuté', () => {
expect(1 / 0).toBe(Infinity);
});

describe.skip.each`table`(name, fn)

describe.skip.each`
a | b | expected
${1} | ${1} | ${2}
${1} | ${2} | ${3}
${2} | ${1} | ${3}
`('retourne $expected quand $a est ajouté à $b', ({a, b, expected}) => {
test('ne sera pas exécuté', () => {
expect(a + b).toBe(expected); // e sera pas exécuté
});
});

test('sera exécuté', () => {
expect(1 / 0).toBe(Infinity);
});

test(name, fn, timeout)

Aussi sous l'alias : it(name, fn, timeout)

Tout ce dont vous avez besoin dans un fichier de test est la méthode test qui exécute un test. Par exemple, supposons qu'il existe une fonction inchesOfRain() qui devrait être égale à zéro. Votre test complet pourrait être :

test('il n\'a pas plu', () => {
expect(inchesOfRain()).toBe(0);
});

Le premier argument est le nom du test ; le deuxième argument est une fonction qui contient les attentes à tester. Le troisième argument (facultatif) est timeout (en millisecondes) pour spécifier combien de temps il faut attendre avant d'abandonner. The default timeout is 5 seconds.

Si une promesse est retournée à partir de test, Jest attendra que la promesse soit résolue avant de laisser le test se terminer. Par exemple, supposons que fetchBeverageList() renvoie une promesse qui est censée résoudre une liste qui contient lemon. Vous pouvez tester ceci avec :

test('contient du lemon', () => {
return fetchBeverageList().then(list => {
expect(list).toContain('lemon');
});
});

Même si l'appel à test retournera immédiatement, le test n'est pas terminé tant que la promesse n'est pas résolue. Pour plus de détails, consultez la page Tester le code asynchrone.

astuce

Jest attendra également si vous fournissez un argument à la fonction de test, généralement appelé done. Cela pourrait être pratique lorsque vous voulez tester les callbacks.

test.concurrent(name, fn, timeout)

Aussi sous l'alias : it.concurrent(name, fn, timeout)

attention

test.concurrent est considéré comme expérimental - consultez ceci pour des détails sur les fonctionnalités manquantes et d'autres problèmes.

Utilisez test.concurrent si vous voulez que le test s'exécute de manière simultanée.

Le premier argument est le nom du test ; le deuxième argument est une fonction asynchrone qui contient les attentes à tester. Le troisième argument (facultatif) est timeout (en millisecondes) pour spécifier combien de temps il faut attendre avant d'abandonner. The default timeout is 5 seconds.

test.concurrent('addition de 2 nombres', async () => {
expect(5 + 3).toBe(8);
});

test.concurrent('soustraction de 2 nombres', async () => {
expect(5 - 3).toBe(2);
});
astuce

Utilisez maxConcurrency dans la configuration pour empêcher Jest d'exécuter plus que le nombre spécifié de tests en même temps.

test.concurrent.each(table)(name, fn, timeout)

Aussi sous l'alias : it.concurrent.each(table)(name, fn, timeout)

Utilisez test.concurrent.each si vous continuez à dupliquer les mêmes tests avec des données différentes. test.each vous permet d'écrire le test une fois et de passer des données, les tests sont tous exécutés de manière asynchrone.

test.concurrent.each est disponible avec deux API :

1. test.concurrent.each(table)(name, fn, timeout)

  • table : Array de tableaux avec les arguments qui sont passés dans le test fn pour chaque ligne. If you pass in a 1D array of primitives, internally it will be mapped to a table i.e. [1, 2, 3] -> [[1], [2], [3]]
  • name : String le titre du bloc de test.
    • Générez des titres de test uniques en injectant de manière placée des paramètres avec le formatage de printf :
      • %p - pretty-format.
      • %s- Chaîne.
      • %d- Nombre.
      • %i - Entier.
      • %f - Valeur à virgule flottante.
      • %j - JSON.
      • %o - Objet.
      • %# - Index du cas de test.
      • %% - unique signe de pourcentage ('%'). Cela ne sert pas d'argument.
  • fn : Function le test à exécuter, c'est la fonction qui recevra les paramètres de chaque ligne comme arguments de fonction, cette fonction devra être une fonction asynchrone.
  • En option, vous pouvez fournir un timeout (en millisecondes) pour spécifier combien de temps attendre pour chaque ligne avant d'abandonner. The default timeout is 5 seconds.

Exemple :

test.concurrent.each([
[1, 1, 2],
[1, 2, 3],
[2, 1, 3],
])('.add(%i, %i)', async (a, b, expected) => {
expect(a + b).toBe(expected);
});

2. test.concurrent.each`table`(name, fn, timeout)

  • table: Littéral de template étiqueté
    • La première ligne contient l'entêtes des colonnes avec les noms de variables séparés par |
    • Une ou plusieurs lignes de données successives sont fournies sous forme d'expressions littérales de template utilisant la syntaxe ${value}.
  • name : String le titre du test, utilisez $variable pour injecter des données de test dans le titre à partir des expressions de template étiquetées.
    • Pour injecter des valeurs d'objets imbriqués, vous pouvez fournir un keyPath, c'est-à-dire $variable.path.to.value
  • fn : Function le test à exécuter, c'est la fonction qui recevra l'objet de données du test, cette fonction devra être une fonction asynchrone.
  • En option, vous pouvez fournir un timeout (en millisecondes) pour spécifier combien de temps attendre pour chaque ligne avant d'abandonner. The default timeout is 5 seconds.

Exemple :

test.concurrent.each`
a | b | expected
${1} | ${1} | ${2}
${1} | ${2} | ${3}
${2} | ${1} | ${3}
`('retourne $expected lorsque $a est ajouté à $b', async ({a, b, expected}) => {
expect(a + b).toBe(expected);
});

test.concurrent.only.each(table)(name, fn)

Aussi sous l'alias : it.concurrent.only.each(table)(name, fn)

Utilisez test.concurrent.only.each si vous souhaitez uniquement exécuter simultanément des tests spécifiques avec des données de test différentes.

test.concurrent.only.each est disponible avec deux API :

test.concurrent.only.each(table)(name, fn)

test.concurrent.only.each([
[1, 1, 2],
[1, 2, 3],
[2, 1, 3],
])('.add(%i, %i)', async (a, b, expected) => {
expect(a + b).toBe(expected);
});

test('ne sera pas exécuté', () => {
expect(1 / 0).toBe(Infinity);
});

test.only.each`table`(name, fn)

test.concurrent.only.each`
a | b | expected
${1} | ${1} | ${2}
${1} | ${2} | ${3}
${2} | ${1} | ${3}
`('retourne $expected quand $a est ajouté à $b', async ({a, b, expected}) => {
expect(a + b).toBe(expected);
});

test('ne sera pas exécuté', () => {
expect(1 / 0).toBe(Infinity);
});

test.concurrent.skip.each(table)(name, fn)

Aussi sous l'alias : it.concurrent.skip.each(table)(name, fn)

Utilisez test.concurrent.skip.each si vous voulez arrêter l'exécution d'une collection de tests asynchrones pilotés par les données.

test.concurrent.skip.chaque est disponible avec deux API :

test.concurrent.skip.each(table)(name, fn)

test.concurrent.skip.each([
[1, 1, 2],
[1, 2, 3],
[2, 1, 3],
])('.add(%i, %i)', async (a, b, expected) => {
expect(a + b).toBe(expected); // ne sera pas exécuté
});

test('sera exécuté', () => {
expect(1 / 0).toBe(Infinity);
});

test.concurrent.skip.each`table`(name, fn)

test.concurrent.skip.each`
a | b | expected
${1} | ${1} | ${2}
${1} | ${2} | ${3}
${2} | ${1} | ${3}
`('returns $expected when $a is added $b', async ({a, b, expected}) => {
expect(a + b).toBe(expected); // ne sera pas exécuté
});

test('sera exécuté', () => {
expect(1 / 0).toBe(Infinity);
});

test.each(table)(name, fn, timeout)

Aussi sous les alias : it.each(table)(name, fn) et it.each`table`(name, fn)

Utilisez test.each si vous continuez à dupliquer les mêmes tests avec des données différentes. test.each permet d'écrire le test une fois et de lui passer les données.

test.each est disponible avec deux API :

1. test.each(table)(name, fn, timeout)

  • table : Array de tableaux avec les arguments qui sont passés dans le test fn pour chaque ligne. If you pass in a 1D array of primitives, internally it will be mapped to a table i.e. [1, 2, 3] -> [[1], [2], [3]]
  • name : String le titre du bloc de test.
    • Générez des titres de test uniques en injectant de manière placée des paramètres avec le formatage de printf :
      • %p - pretty-format.
      • %s- Chaîne.
      • %d- Nombre.
      • %i - Entier.
      • %f - Valeur à virgule flottante.
      • %j - JSON.
      • %o - Objet.
      • %# - Index du cas de test.
      • %% - unique signe de pourcentage ('%'). Cela ne sert pas d'argument.
    • Ou générez des titres de test uniques en injectant les propriétés de l'objet du cas de test avec $variable
      • Pour injecter des valeurs d'objets imbriqués, vous pouvez fournir un keyPath, c'est-à-dire $variable.path.to.value
      • Vous pouvez utiliser $# pour injecter l'index du cas de test
      • Vous ne pouvez pas utiliser $variable avec le formatage printf sauf pour %%
  • fn : Function le test à exécuter, c'est la fonction qui recevra les paramètres de chaque ligne comme arguments de fonction.
  • En option, vous pouvez fournir un timeout (en millisecondes) pour spécifier combien de temps attendre pour chaque ligne avant d'abandonner. The default timeout is 5 seconds.

Exemple :

test.each([
[1, 1, 2],
[1, 2, 3],
[2, 1, 3],
])('.add(%i, %i)', (a, b, expected) => {
expect(a + b).toBe(expected);
});
test.each([
{a: 1, b: 1, expected: 2},
{a: 1, b: 2, expected: 3},
{a: 2, b: 1, expected: 3},
])('.add($a, $b)', ({a, b, expected}) => {
expect(a + b).toBe(expected);
});

2. test.each`table`(name, fn, timeout)

  • table: Littéral de template étiqueté
    • La première ligne contient l'entêtes des colonnes avec les noms de variables séparés par |
    • Une ou plusieurs lignes de données successives sont fournies sous forme d'expressions littérales de template utilisant la syntaxe ${value}.
  • name : String le titre du test, utilisez $variable pour injecter des données de test dans le titre à partir des expressions de template étiquetées.
    • Pour injecter des valeurs d'objets imbriqués, vous pouvez fournir un keyPath, c'est-à-dire $variable.path.to.value
  • fn : Function le test à exécuter, c'est la fonction qui recevra l'objet de données de test.
  • En option, vous pouvez fournir un timeout (en millisecondes) pour spécifier combien de temps attendre pour chaque ligne avant d'abandonner. The default timeout is 5 seconds.

Exemple :

test.each`
a | b | expected
${1} | ${1} | ${2}
${1} | ${2} | ${3}
${2} | ${1} | ${3}
`('retourne $expected quand $a est ajouté à $b', ({a, b, expected}) => {
expect(a + b).toBe(expected);
});

test.failing(name, fn, timeout)

Aussi sous l'alias : it.failing(name, fn, timeout)

remarque

Cela n'est disponible qu'avec l'exécuteur par défaut jest-circus.

Utilisez test.fail lorsque vous écrivez un test et que vous attendez qu'il échoue. Ces tests se comporteront de la même manière que les tests normaux. Si le test failing lève n'importe quelle erreur, il passe. S'il n'en lève pas, il échouera.

astuce

Vous pouvez utiliser ce type de tests, par exemple lorsque vous écrivez du code de manière BDD. Dans ce cas, les tests n'apparaîtront pas comme ayant échoué tant qu'ils n'auront pas réussi. Ensuite, vous pouvez simplement supprimer le modificateur failling pour les faire passer.

Cela peut aussi être un bon moyen de contribuer à un projet par des tests défaillants, même si vous ne savez pas comment corriger le bogue.

Exemple :

test.failing('il n\'est pas égal', () => {
expect(5).toBe(6); // ce test passera
});

test.failing('il est égal', () => {
expect(10).toBe(10); // ce test échouera
});

test.failing.each(name, fn, timeout)

Aussi sous les alias : it.failing.each(table)(name, fn) et it.failing.each`table`(name, fn)

remarque

Cela n'est disponible qu'avec l'exécuteur par défaut jest-circus.

Vous pouvez également exécuter plusieurs tests à la fois en ajoutant each après failing.

Exemple :

test.failing.each([
{a: 1, b: 1, expected: 2},
{a: 1, b: 2, expected: 3},
{a: 2, b: 1, expected: 3},
])('.add($a, $b)', ({a, b, expected}) => {
expect(a + b).toBe(expected);
});

test.only.failing(name, fn, timeout)

Aussi sous les alias : it.only.failing(name, fn, timeout), fit.failing(name, fn, timeout)

remarque

Cela n'est disponible qu'avec l'exécuteur par défaut jest-circus.

Utilisez test.only.failed si vous voulez seulement exécuter un test spécifique défaillant.

test.skip.failing(name, fn, timeout)

Aussi sous les alias : it.skip.failing(name, fn, timeout), xit.failing(name, fn, timeout), xtest.failing(name, fn, timeout)

remarque

Cela n'est disponible qu'avec l'exécuteur par défaut jest-circus.

Utilisez test.skip.failed si vous voulez seulement ignorer un test spécifique défaillant.

test.only(name, fn, timeout)

Aussi sous les alias : it.only(name, fn, timeout), and fit(name, fn, timeout)

Lorsque vous déboguez un grand fichier de test, vous ne souhaitez souvent exécuter qu'un sous-ensemble de tests. Vous pouvez utiliser .only pour spécifier les tests qui sont les seuls que vous voulez exécuter dans ce fichier de test.

En option, vous pouvez fournir un timeout (en millisecondes) pour spécifier le temps d'attente avant l'abandon. The default timeout is 5 seconds.

Par exemple, supposons que vous ayez ces tests :

test.only('il pleut', () => {
expect(inchesOfRain()).toBeGreaterThan(0);
});

test('Il ne neige pas', () => {
expect(inchesOfSnow()).toBe(0);
});

Seul le test "il pleut" sera exécuté dans ce fichier de test, puisqu'il est exécuté avec test.only.

Habituellement, vous ne vérifiez pas le code utilisant test.only dans le contrôle de la source - vous l'utilisez pour le débogage, et le supprimez une fois que vous avez corrigé les tests défectueux.

test.only.each(table)(name, fn)

Aussi sous les alias : it.only.each(table)(name, fn), fit.each(table)(name, fn), it.only.each`table`(name, fn) and fit.each`table`(name, fn)

Utilisez test.only.each si vous souhaitez uniquement exécuter des tests spécifiques avec des données de test différentes.

test.only.each est disponible avec deux API :

test.only.each(table)(name, fn)

test.only.each([
[1, 1, 2],
[1, 2, 3],
[2, 1, 3],
])('.add(%i, %i)', (a, b, expected) => {
expect(a + b).toBe(expected);
});

test('ne sera pas exécuté', () => {
expect(1 / 0).toBe(Infinity);
});

test.only.each`table`(name, fn)

test.only.each`
a | b | expected
${1} | ${1} | ${2}
${1} | ${2} | ${3}
${2} | ${1} | ${3}
`('retourne $expected quand $a est ajouté à $b', ({a, b, expected}) => {
expect(a + b).toBe(expected);
});

test('ne sera pas exécuté', () => {
expect(1 / 0).toBe(Infinity);
});

test.skip(name, fn)

Aussi sous les alias : it.skip(name, fn), xit(name, fn), and xtest(name, fn)

Lorsque vous maintenez une large base de code, vous pouvez parfois trouver un test qui est temporairement défectueux pour une raison quelconque. Si vous voulez éviter d'exécuter ce test, mais que vous ne voulez pas supprimer ce code, vous pouvez utiliser test.skip pour spécifier certains tests à ignorer.

Par exemple, supposons que vous ayez ces tests :

test('il pleut', () => {
expect(inchesOfRain()).toBeGreaterThan(0);
});

test.skip('il ne neige pas', () => {
expect(inchesOfSnow()).toBe(0);
});

Seul le test "il pleut" sera exécuté, puisque l'autre test est exécuté avec test.skip.

Vous pouvez commenter le test, mais il est souvent un peu plus agréable d'utiliser test.skip car il maintiendra l'indentation et la coloration syntaxique.

test.skip.each(table)(name, fn)

Aussi sous les alias : it.skip.each(table)(name, fn), xit.each(table)(name, fn), xtest.each(table)(name, fn), it.skip.each`table`(name, fn), xit.each`table`(name, fn) and xtest.each`table`(name, fn)

Utilisez test.skip.each si vous voulez arrêter d'exécuter une collection de tests pilotés par les données.

test.skip.chaque est disponible avec deux API :

test.skip.each(table)(name, fn)

test.skip.each([
[1, 1, 2],
[1, 2, 3],
[2, 1, 3],
])('.add(%i, %i)', (a, b, expected) => {
expect(a + b).toBe(expected); // ne sera pas exécuté
});

test('sera exécuté', () => {
expect(1 / 0).toBe(Infinity);
});

test.skip.each`table`(name, fn)

test.skip.each`
a | b | expected
${1} | ${1} | ${2}
${1} | ${2} | ${3}
${2} | ${1} | ${3}
`('retourne $expected quand $a es ajouté à $b', ({a, b, expected}) => {
expect(a + b).toBe(expected); // ne sera pas exécuté
});

test('sera exécuté', () => {
expect(1 / 0).toBe(Infinity);
});

test.todo(name)

Aussi sous l'alias : it.todo(name)

Utilisez test.todo lorsque vous prévoyez d'écrire des tests. Ces tests seront mis en évidence dans le résumé de la sortie à la fin, afin que vous sachiez combien de tests il vous reste à faire.

const add = (a, b) => a + b;

test.todo('add doit être associatif');
astuce

test.todo will throw an error, if you will pass it a test callback function. Use test.skip instead, if you already implemented the test, but do not want it to run.

Utilisation de TypeScript

info

Les exemples TypeScript de cette page ne fonctionneront comme documenté que si vous importez explicitement les API Jest :

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

Consult the Getting Started guide for details on how to setup Jest with TypeScript.

.each

The .each modifier offers few different ways to define a table of the test cases. Some of the APIs have caveats related with the type inference of the arguments which are passed to describe or test callback functions. Let's take a look at each of them.

remarque

For simplicity test.each is picked for the examples, but the type inference is identical in all cases where .each modifier can be used: describe.each, test.concurrent.only.each, test.skip.each, etc.

Tableau d'objets

The array of objects API is most verbose, but it makes the type inference a painless task. A table can be inlined:

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

test.each([
{name: 'a', path: 'path/to/a', count: 1, write: true},
{name: 'b', path: 'path/to/b', count: 3},
])('inline table', ({name, path, count, write}) => {
// arguments are typed as expected, e.g. `write: boolean | undefined`
});

Or declared separately as a variable:

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

const table = [
{a: 1, b: 2, expected: 'three', extra: true},
{a: 3, b: 4, expected: 'seven', extra: false},
{a: 5, b: 6, expected: 'eleven'},
];

test.each(table)('table as a variable', ({a, b, expected, extra}) => {
// again everything is typed as expected, e.g. `extra: boolean | undefined`
});

Tableau de tableaux

The array of arrays style will work smoothly with inlined tables:

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

test.each([
[1, 2, 'three', true],
[3, 4, 'seven', false],
[5, 6, 'eleven'],
])('inline table example', (a, b, expected, extra) => {
// arguments are typed as expected, e.g. `extra: boolean | undefined`
});

However, if a table is declared as a separate variable, it must be typed as an array of tuples for correct type inference (this is not needed only if all elements of a row are of the same type):

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

const table: Array<[number, number, string, boolean?]> = [
[1, 2, 'three', true],
[3, 4, 'seven', false],
[5, 6, 'eleven'],
];

test.each(table)('table as a variable example', (a, b, expected, extra) => {
// without the annotation types are incorrect, e.g. `a: number | string | boolean`
});

Littéral de gabarit

If all values are of the same type, the template literal API will type the arguments correctly:

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

test.each`
a | b | expected
${1} | ${2} | ${3}
${3} | ${4} | ${7}
${5} | ${6} | ${11}
`('template literal example', ({a, b, expected}) => {
// all arguments are of type `number`
});

Otherwise it will require a generic type argument:

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

test.each<{a: number; b: number; expected: string; extra?: boolean}>`
a | b | expected | extra
${1} | ${2} | ${'three'} | ${true}
${3} | ${4} | ${'seven'} | ${false}
${5} | ${6} | ${'eleven'}
`('template literal example', ({a, b, expected, extra}) => {
// without the generic argument in this case types would default to `unknown`
});