Version : 30.0

Globales

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 →

Dans vos fichiers de test, Jest place chacune de ces méthodes et objets dans l'environnement global. Vous n'avez rien à importer pour les utiliser. Cependant, si vous préférez des imports explicites, vous pouvez utiliser import {describe, expect, test} from '@jest/globals'.

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 →

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';

Consultez le guide Premiers pas pour plus de détails sur la configuration de Jest avec TypeScript.

Référence

`afterAll(fn, timeout)`

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

Optionnellement, vous pouvez spécifier un timeout (en millisecondes) pour définir le temps d'attente maximum avant abandon. Le délai par défaut est de 5 secondes.

C'est souvent utile pour nettoyer des états globaux partagés entre plusieurs tests.

Par exemple :

const globalDatabase = makeGlobalDatabase();

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

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

test('can find things', () => {
  return globalDatabase.find('thing', {}, results => {
    expect(results.length).toBeGreaterThan(0);
  });
});

test('can insert a thing', () => {
  return globalDatabase.insert('thing', makeThing(), response => {
    expect(response.success).toBeTruthy();
  });
});

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

Si afterAll se trouve dans un bloc describe, elle s'exécute à la fin de ce bloc.

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

`afterEach(fn, timeout)`

Exécute une fonction après chaque test 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.

Optionnellement, vous pouvez spécifier un timeout (en millisecondes) pour définir le temps d'attente maximum avant abandon. Le délai par défaut est de 5 secondes.

C'est souvent utile pour nettoyer des états temporaires créés par chaque test.

Par exemple :

const globalDatabase = makeGlobalDatabase();

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

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

test('can find things', () => {
  return globalDatabase.find('thing', {}, results => {
    expect(results.length).toBeGreaterThan(0);
  });
});

test('can insert a thing', () => {
  return globalDatabase.insert('thing', makeThing(), response => {
    expect(response.success).toBeTruthy();
  });
});

Ici, afterEach garantit que cleanUpDatabase est appelée après chaque test.

Si afterEach se trouve dans un bloc describe, elle ne s'exécute qu'après les tests de ce bloc.

Si vous souhaitez exécuter un nettoyage une seule fois après tous les tests, utilisez afterAll.

`beforeAll(fn, timeout)`

Exécute une fonction avant l'exécution 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 d'exécuter les tests.

Optionnellement, vous pouvez spécifier un timeout (en millisecondes) pour définir le temps d'attente maximum avant abandon. Le délai par défaut est de 5 secondes.

C'est souvent utile pour configurer des états globaux utilisés par plusieurs tests.

Par exemple :

const globalDatabase = makeGlobalDatabase();

beforeAll(() => {
  // Clears the database and adds some testing data.
  // Jest will wait for this promise to resolve before running tests.
  return globalDatabase.clear().then(() => {
    return globalDatabase.insert({testData: 'foo'});
  });
});

// Since we only set up the database once in this example, it's important
// that our tests don't modify it.
test('can find things', () => {
  return globalDatabase.find('thing', {}, results => {
    expect(results.length).toBeGreaterThan(0);
  });
});

Ici, beforeAll garantit que la base de données est configurée avant les tests. Si la configuration était synchrone, vous pourriez le faire sans beforeAll. L'essentiel est que Jest attend la résolution d'une promesse, permettant aussi des configurations asynchrones.

Si beforeAll se trouve dans un bloc describe, elle s'exécute au début de ce bloc.

Si vous souhaitez exécuter quelque chose avant chaque test plutôt qu'avant tous les tests, utilisez beforeEach.

`beforeEach(fn, timeout)`

Exécute une fonction avant chaque test 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 le test.

Optionnellement, vous pouvez spécifier un timeout (en millisecondes) pour définir le temps d'attente maximum avant abandon. Le délai par défaut est de 5 secondes.

C'est souvent utile pour réinitialiser des états globaux utilisés par plusieurs tests.

Par exemple :

const globalDatabase = makeGlobalDatabase();

beforeEach(() => {
  // Clears the database and adds some testing data.
  // Jest will wait for this promise to resolve before running tests.
  return globalDatabase.clear().then(() => {
    return globalDatabase.insert({testData: 'foo'});
  });
});

test('can find things', () => {
  return globalDatabase.find('thing', {}, results => {
    expect(results.length).toBeGreaterThan(0);
  });
});

test('can insert a thing', () => {
  return globalDatabase.insert('thing', makeThing(), response => {
    expect(response.success).toBeTruthy();
  });
});

Ici, beforeEach garantit 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 dans ce bloc.

Si vous n'avez besoin d'exécuter du code de configuration qu'une seule fois avant l'exécution des 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 censé être délicieux mais pas acide, vous pourriez le tester avec :

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

describe('my beverage', () => {
  test('is delicious', () => {
    expect(myBeverage.delicious).toBeTruthy();
  });

  test('is not sour', () => {
    expect(myBeverage.sour).toBeFalsy();
  });
});

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

Vous pouvez également imbriquer des 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 dupliquez constamment les mêmes suites de tests avec des données différentes. describe.each vous permet d'écrire la suite de tests une fois et d'y passer des données.

describe.each est disponible avec deux API :

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

table : Array de tableaux contenant les arguments passés à fn pour chaque ligne. Si vous passez un tableau 1D de primitives, il sera converti en tableau 2D, ex: [1, 2, 3] -> [[1], [2], [3]].
name : String titre de la suite de tests.
- Générez des titres uniques en injectant des paramètres positionnels avec le formatage printf :
  - %p - pretty-format.
  - %s - Chaîne de caractères.
  - %d - Nombre.
  - %i - Entier.
  - %f - Valeur à virgule flottante.
  - %j - JSON.
  - %o - Objet.
  - %# - Index du cas de test.
  - %$ - Numéro du cas de test.
  - %% - Signe pourcentage unique ('%'). Ne consomme pas d'argument.
- Ou générez des titres uniques en injectant des propriétés d'objet avec $variable :
  - Pour les valeurs d'objets imbriqués, utilisez un chemin de clés comme $variable.path.to.value (fonctionne uniquement pour les propriétés propres, e.g. $variable.constructor.name ne fonctionnerait pas)
  - Utilisez $# pour injecter l'index du cas de test
  - $variable n'est pas compatible avec le formatage printf sauf pour %%
fn : Function suite de tests à exécuter, recevant les paramètres de chaque ligne comme arguments.
Optionnellement, vous pouvez spécifier un timeout (en millisecondes) pour définir le temps d'attente maximum par ligne avant abandon. Le délai par défaut est de 5 secondes.

Exemple :

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

  test(`returned value not be greater than ${expected}`, () => {
    expect(a + b).not.toBeGreaterThan(expected);
  });

  test(`returned value not be less than ${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(`returns ${expected}`, () => {
    expect(a + b).toBe(expected);
  });

  test(`returned value not be greater than ${expected}`, () => {
    expect(a + b).not.toBeGreaterThan(expected);
  });

  test(`returned value not be less than ${expected}`, () => {
    expect(a + b).not.toBeLessThan(expected);
  });
});

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

table : Tagged Template Literal
- Première ligne : en-têtes de colonnes de noms de variables séparés par |
- Lignes suivantes : données fournies via des expressions de littéral de modèle ${value}
name : String titre de la suite de tests, utilisez $variable pour injecter des données dans le titre et $# pour l'index de la ligne.
- Pour injecter des valeurs d'objets imbriqués, utilisez un chemin de clés comme $variable.path.to.value (fonctionne uniquement pour les propriétés propres, par exemple $variable.constructor.name ne fonctionnerait pas)
fn : Function suite de tests à exécuter, recevant les données sous forme d'objet.
Optionnellement, vous pouvez spécifier un timeout (en millisecondes) pour définir le temps d'attente maximum par ligne avant abandon. Le délai par défaut est de 5 secondes.

Exemple :

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

  test(`returned value not be greater than ${expected}`, () => {
    expect(a + b).not.toBeGreaterThan(expected);
  });

  test(`returned value not be less than ${expected}`, () => {
    expect(a + b).not.toBeLessThan(expected);
  });
});

`describe.only(name, fn)`

Également sous l'alias : fdescribe(name, fn)

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

describe.only('my beverage', () => {
  test('is delicious', () => {
    expect(myBeverage.delicious).toBeTruthy();
  });

  test('is not sour', () => {
    expect(myBeverage.sour).toBeFalsy();
  });
});

describe('my other beverage', () => {
  // ... will be skipped
});

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

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

Utilisez describe.only.each pour exécuter uniquement des suites de tests spécifiques basées sur des 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(`returns ${expected}`, () => {
    expect(a + b).toBe(expected);
  });
});

test('will not be run', () => {
  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}
`('returns $expected when $a is added to $b', ({a, b, expected}) => {
  test('passes', () => {
    expect(a + b).toBe(expected);
  });
});

test('will not be run', () => {
  expect(1 / 0).toBe(Infinity);
});

`describe.skip(name, fn)`

Également sous l'alias : xdescribe(name, fn)

Utilisez describe.skip pour ignorer les tests d'un bloc describe spécifique :

describe('my beverage', () => {
  test('is delicious', () => {
    expect(myBeverage.delicious).toBeTruthy();
  });

  test('is not sour', () => {
    expect(myBeverage.sour).toBeFalsy();
  });
});

describe.skip('my other beverage', () => {
  // ... will be skipped
});

describe.skip est souvent une alternative plus propre que de commenter temporairement des tests. Attention : le bloc describe sera tout de même exécuté. Pour ignorer du code de configuration, utilisez beforeAll ou beforeEach.

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

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

Utilisez describe.skip.each pour arrêter l'exécution d'une suite de tests basée sur des données.

describe.skip.each 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(`returns ${expected}`, () => {
    expect(a + b).toBe(expected); // will not be run
  });
});

test('will be run', () => {
  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}
`('returns $expected when $a is added to $b', ({a, b, expected}) => {
  test('will not be run', () => {
    expect(a + b).toBe(expected); // will not be run
  });
});

test('will be run', () => {
  expect(1 / 0).toBe(Infinity);
});

`test(name, fn, timeout)`

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

La seule méthode nécessaire dans un fichier de test est test, qui exécute un test. Par exemple, pour vérifier qu'une fonction inchesOfRain() retourne zéro :

test('did not rain', () => {
  expect(inchesOfRain()).toBe(0);
});

Le premier argument est le nom du test ; le second est une fonction contenant les assertions. Le troisième argument (optionnel) est le timeout (en millisecondes) spécifiant le délai avant abandon. Le délai par défaut est de 5 secondes.

Si test retourne une promesse, Jest attend sa résolution avant de terminer le test. Par exemple, si fetchBeverageList() retourne une promesse résolue avec une liste contenant lemon :

test('has lemon in it', () => {
  return fetchBeverageList().then(list => {
    expect(list).toContain('lemon');
  });
});

Bien que test retourne immédiatement, le test ne se termine qu'après résolution de la promesse. Pour plus de détails, consultez Testing Asynchronous Code.

astuce

Jest attendra également si vous fournissez un argument à la fonction de test, généralement appelé done. Utile pour tester les callbacks.

`test.concurrent(name, fn, timeout)`

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

attention

test.concurrent est expérimental - voir les détails sur les fonctionnalités manquantes.

Utilisez test.concurrent pour exécuter des tests en concurrence.

Le premier argument est le nom du test ; le deuxième argument est une fonction asynchrone contenant les vérifications à tester. Le troisième argument (optionnel) est timeout (en millisecondes) pour spécifier le délai d'attente avant abandon. Le délai par défaut est de 5 secondes.

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

test.concurrent('subtraction 2 numbers', async () => {
  expect(5 - 3).toBe(2);
});

astuce

Utilisez l'option de configuration maxConcurrency pour empêcher Jest d'exécuter plus que le nombre spécifié de tests simultanément.

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

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

Utilisez test.concurrent.each si vous dupliquez constamment le même test avec différentes données. test.each vous permet d'écrire le test une fois et d'y injecter les données, tous les tests s'exécutant de manière asynchrone.

test.concurrent.each est disponible via deux API :

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

table : Array de tableaux contenant les arguments passés à la fonction de test fn pour chaque ligne. Si vous passez un tableau 1D de valeurs primitives, il sera converti en tableau 2D (ex: [1, 2, 3] -> [[1], [2], [3]])
name : String titre du bloc de test
- Générez des titres uniques en injectant des paramètres positionnels via le formatage printf :
  - %p - pretty-format
  - %s - Chaîne de caractères
  - %d - Nombre
  - %i - Entier
  - %f - Valeur flottante
  - %j - JSON
  - %o - Objet
  - %# - Index du cas de test
  - %$ - Numéro du cas de test
  - %% - signe pourcent simple ('%') (ne consomme pas d'argument)
fn : Function test à exécuter, recevant les paramètres de chaque ligne comme arguments. Doit être une fonction asynchrone.
Optionnellement, vous pouvez spécifier un timeout (en millisecondes) pour définir le temps d'attente maximum par ligne avant abandon. Le délai par défaut est de 5 secondes.

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 : Tagged Template Literal
- Première ligne : en-têtes de colonnes de noms de variables séparés par |
- Lignes suivantes : données fournies via des expressions de littéral de modèle ${value}
name : String titre du test, utilisez $variable pour injecter les données dans le titre depuis les expressions de modèle balisées
- Pour injecter les valeurs d'objets imbriqués, vous pouvez fournir un chemin de clés, par exemple $variable.path.to.value (fonctionne uniquement pour les "propriétés propres", par exemple $variable.constructor.name ne fonctionnerait pas)
fn : Function test à exécuter, recevant l'objet de données de test. Doit être une fonction asynchrone.
Optionnellement, vous pouvez spécifier un timeout (en millisecondes) pour définir le temps d'attente maximum par ligne avant abandon. Le délai par défaut est de 5 secondes.

Exemple :

test.concurrent.each`
  a    | b    | expected
  ${1} | ${1} | ${2}
  ${1} | ${2} | ${3}
  ${2} | ${1} | ${3}
`('returns $expected when $a is added to $b', async ({a, b, expected}) => {
  expect(a + b).toBe(expected);
});

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

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

Utilisez test.concurrent.only.each pour exécuter uniquement des tests spécifiques avec différentes données de manière concurrente.

test.concurrent.only.each est disponible via 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('will not be run', () => {
  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}
`('returns $expected when $a is added to $b', async ({a, b, expected}) => {
  expect(a + b).toBe(expected);
});

test('will not be run', () => {
  expect(1 / 0).toBe(Infinity);
});

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

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

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

test.concurrent.skip.each 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); // will not be run
});

test('will be run', () => {
  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 to $b', async ({a, b, expected}) => {
  expect(a + b).toBe(expected); // will not be run
});

test('will be run', () => {
  expect(1 / 0).toBe(Infinity);
});

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

Également disponible sous les alias : it.each(table)(name, fn) et it.each`table`(name, fn)

Utilisez test.each lorsque vous dupliquez le même test avec différentes données. test.each vous permet d'écrire le test une fois et d'injecter les données.

test.each est disponible avec deux API :

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

table : Array de tableaux contenant les arguments passés à la fonction de test fn pour chaque ligne. Si vous passez un tableau 1D de valeurs primitives, il sera converti en tableau 2D (ex: [1, 2, 3] -> [[1], [2], [3]])
name : String titre du bloc de test
- Générez des titres uniques en injectant des paramètres avec le formatage printf :
  - %p - pretty-format
  - %s - Chaîne de caractères
  - %d - Nombre
  - %i - Entier
  - %f - Valeur à virgule flottante
  - %j - JSON
  - %o - Objet
  - %# - Index du cas de test
  - %$ - Numéro du cas de test
  - %% - Signe pourcentage unique ('%'), ne consomme pas d'argument
- Ou générez des titres via les propriétés d'objet avec $variable :
  - Pour injecter des valeurs d'objet imbriquées, fournissez un chemin de clés comme $variable.path.to.value (fonctionne uniquement pour les propriétés propres, par exemple $variable.constructor.name ne fonctionnerait pas)
  - Utilisez $# pour injecter l'index du cas de test
  - $variable est incompatible avec le formatage printf sauf pour %%
fn : Function fonction de test à exécuter, recevant les paramètres de chaque ligne comme arguments
Optionnellement, vous pouvez spécifier un timeout (en millisecondes) pour définir le temps d'attente maximum par ligne avant abandon. Le délai par défaut est de 5 secondes.

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 : Tagged Template Literal
- Première ligne : en-têtes de colonnes de noms de variables séparés par |
- Lignes suivantes : données fournies via des expressions de littéral de modèle ${value}
name : String titre du test, utilisez $variable pour injecter les données dans le titre depuis les expressions de modèle balisées
- Pour injecter les valeurs d'objets imbriqués, vous pouvez fournir un chemin de clés, par exemple $variable.path.to.value (fonctionne uniquement pour les "propriétés propres", par exemple $variable.constructor.name ne fonctionnerait pas)
fn : Function fonction de test recevant l'objet de données
Optionnellement, vous pouvez spécifier un timeout (en millisecondes) pour définir le temps d'attente maximum par ligne avant abandon. Le délai par défaut est de 5 secondes.

Exemple :

test.each`
  a    | b    | expected
  ${1} | ${1} | ${2}
  ${1} | ${2} | ${3}
  ${2} | ${1} | ${3}
`('returns $expected when $a is added to $b', ({a, b, expected}) => {
  expect(a + b).toBe(expected);
});

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

Également disponible sous l'alias : it.failing(name, fn, timeout)

note

Disponible uniquement avec le runner par défaut jest-circus.

Utilisez test.failing lorsque vous écrivez un test dont vous attendez un échec. Ces tests se comportent à l'inverse des tests normaux : si un test failing génère une erreur, il est considéré comme réussi. S'il n'en génère pas, il échoue.

astuce

Utile notamment dans une approche BDD : les tests n'apparaîtront comme échoués qu'une fois réussis. Il suffira alors de supprimer le modificateur failing.

Cette méthode permet aussi de contribuer des tests en échec à un projet sans connaître le correctif.

Exemple :

test.failing('it is not equal', () => {
  expect(5).toBe(6); // this test will pass
});

test.failing('it is equal', () => {
  expect(10).toBe(10); // this test will fail
});

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

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

note

Disponible uniquement avec le runner par défaut jest-circus.

L'ajout de each après failing permet d'exécuter plusieurs tests simultanément.

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)`

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

note

Disponible uniquement avec le runner par défaut jest-circus.

Utilisez test.only.failing pour exécuter spécifiquement un test en échec.

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

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

note

Disponible uniquement avec le runner par défaut jest-circus.

Utilisez test.skip.failing pour ignorer l'exécution d'un test en échec spécifique.

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

Également sous les alias : it.only(name, fn, timeout), et fit(name, fn, timeout)

Lors du débogage d'un fichier de test volumineux, .only permet de n'exécuter qu'un sous-ensemble de tests spécifiques.

Optionnellement, vous pouvez spécifier un timeout (en millisecondes) pour définir le temps d'attente maximum avant abandon. Le délai par défaut est de 5 secondes.

Par exemple, supposons que vous ayez ces tests :

test.only('it is raining', () => {
  expect(inchesOfRain()).toBeGreaterThan(0);
});

test('it is not snowing', () => {
  expect(inchesOfSnow()).toBe(0);
});

Seul le test "it is raining" sera exécuté dans ce fichier, grâce à test.only.

En pratique, n'utilisez pas test.only dans le code versionné - réservez-le au débogage, puis supprimez-le une fois les tests corrigés.

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

Également disponible sous les alias : it.only.each(table)(name, fn), fit.each(table)(name, fn), it.only.each`table`(name, fn) et fit.each`table`(name, fn)

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

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('will not be run', () => {
  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}
`('returns $expected when $a is added to $b', ({a, b, expected}) => {
  expect(a + b).toBe(expected);
});

test('will not be run', () => {
  expect(1 / 0).toBe(Infinity);
});

`test.skip(name, fn)`

Également disponible sous les alias : it.skip(name, fn), xit(name, fn), et xtest(name, fn)

Lorsque vous maintenez une base de code importante, vous pouvez parfois trouver un test temporairement cassé pour une raison quelconque. Si vous souhaitez ignorer l'exécution de ce test sans supprimer son code, utilisez test.skip pour spécifier les tests à sauter.

Par exemple, supposons que vous ayez ces tests :

test('it is raining', () => {
  expect(inchesOfRain()).toBeGreaterThan(0);
});

test.skip('it is not snowing', () => {
  expect(inchesOfSnow()).toBe(0);
});

Seul le test "il pleut" s'exécutera, car l'autre test utilise test.skip.

Vous pourriez commenter le test, mais il est souvent plus élégant d'utiliser test.skip car cela préservera l'indentation et la coloration syntaxique.

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

Également disponible 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) et xtest.each`table`(name, fn)

Utilisez test.skip.each si vous souhaitez arrêter l'exécution d'une série de tests pilotés par des données.

test.skip.each 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); // will not be run
});

test('will be run', () => {
  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}
`('returns $expected when $a is added to $b', ({a, b, expected}) => {
  expect(a + b).toBe(expected); // will not be run
});

test('will be run', () => {
  expect(1 / 0).toBe(Infinity);
});

`test.todo(name)`

Également disponible 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é final pour indiquer combien de tests restent à implémenter.

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

test.todo('add should be associative');

astuce

test.todo générera une erreur si vous lui passez une fonction de callback de test. Utilisez plutôt test.skip si vous avez déjà implémenté le test mais ne souhaitez pas l'exécuter.

Utilisation avec TypeScript

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 →

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';

Consultez le guide Premiers pas pour plus de détails sur la configuration de Jest avec TypeScript.

`.each`

Le modificateur .each propose plusieurs façons de définir un tableau de cas de test. Certaines API présentent des particularités liées à l'inférence de type des arguments passés aux fonctions de callback describe ou test. Examinons chacune d'elles.

note

Pour simplifier, test.each est utilisé dans les exemples, mais l'inférence de type est identique dans tous les cas où le modificateur .each peut être utilisé : describe.each, test.concurrent.only.each, test.skip.each, etc.

Tableau d'objets

L'API avec tableau d'objets est la plus verbeuse, mais elle facilite l'inférence de type. Un table peut être défini inline :

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`
});

Ou déclaré séparément comme 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

Le style avec tableau de tableaux fonctionne parfaitement avec les tables inline :

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`
});

Cependant, si une table est déclarée comme variable séparée, elle doit être typée comme un tableau de tuples pour une inférence de type correcte (ceci n'est nécessaire que si les éléments d'une ligne sont de types différents) :

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éraux de gabarit

Si toutes les valeurs d'entrée sont du même type, l'API des templates littéraux typera correctement les arguments :

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

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

Si les entrées ont des types différents, les arguments seront typés comme une union de tous les types d'entrée (c'est-à-dire le type des variables à l'intérieur du template littéral) :

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

test.each`
  a    | b    | expected
  ${1} | ${2} | ${'three'}
  ${3} | ${4} | ${'seven'}
  ${5} | ${6} | ${'eleven'}
`('template literal example different types', ({a, b, expected}) => {
  // all arguments are of type `number | string` because some inputs (a, b) are of type `number` and some others (expected) are of type `string`
});

Sinon, si vous souhaitez que chaque argument ait le bon type, vous devez explicitement fournir l'argument de type générique :

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}) => {
  // all arguments are typed as expected, e.g. `a: number`, `expected: string`, `extra: boolean | undefined`
});

attention

Gardez à l'esprit que les variables à l'intérieur du template littéral ne sont pas vérifiées par le système de types, vous devez donc vous assurer que leurs types sont corrects.

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

test.each<{a: number; expected: string}>`
  a                            | expected
  ${1}                         | ${'one'}
  ${'will not raise TS error'} | ${'two'}
  ${3}                         | ${'three'}
`('template literal with wrongly typed input', ({a, expected}) => {
  // all arguments are typed as stated in the generic: `a: number`, `expected: string`
  // WARNING: `a` is of type `number` but will be a string in the 2nd test case.
});

Méthodes​

Référence​

afterAll(fn, timeout)​

afterEach(fn, timeout)​

beforeAll(fn, timeout)​

beforeEach(fn, timeout)​

describe(name, fn)​

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

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

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

describe.only(name, fn)​

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

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

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

describe.skip(name, fn)​

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

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

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

test(name, fn, timeout)​

test.concurrent(name, fn, timeout)​

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

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

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

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

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

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

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

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

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

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

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

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

test.failing(name, fn, timeout)​

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

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

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

test.only(name, fn, timeout)​

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

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

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

test.skip(name, fn)​

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

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

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

test.todo(name)​

Utilisation avec TypeScript​

.each​

Tableau d'objets​

Tableau de tableaux​

Littéraux de gabarit​

Méthodes

Référence

`afterAll(fn, timeout)`

`afterEach(fn, timeout)`

`beforeAll(fn, timeout)`

`beforeEach(fn, timeout)`

`describe(name, fn)`

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

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

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

`describe.only(name, fn)`

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

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

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

`describe.skip(name, fn)`

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

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

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

`test(name, fn, timeout)`

`test.concurrent(name, fn, timeout)`

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`test.skip(name, fn)`

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

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

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

`test.todo(name)`

Utilisation avec TypeScript

`.each`

Tableau d'objets

Tableau de tableaux

Littéraux de gabarit