Référence de l'API de Test

Les types suivants sont utilisés dans les signatures de type ci-dessous :

type Awaitable<T> = T | PromiseLike<T>;
type TestFunction = () => Awaitable<void>;

interface TestOptions {
  /**
   * Fait échouer le test s'il prend trop de temps à s'exécuter.
   */
  timeout?: number;
  /**
   * Réessaie le test un nombre spécifique de fois s'il échoue.
   *
   * @default 0
   */
  retry?: number;
  /**
   * Répète le même test plusieurs fois, même s'il échoue à chaque fois.
   * Si l'option "retry" est activée et que le test échoue, chaque tentative sera utilisée dans chaque cycle.
   * Utile pour déboguer les échecs aléatoires.
   *
   * @default 0
   */
  repeats?: number;
}

Vitest 1.3.0 déprécie l'utilisation des options comme dernier paramètre. Vous verrez un message de dépréciation jusqu'à la version 2.0.0, date à laquelle cette syntaxe sera supprimée. Si vous devez transmettre des options, utilisez le deuxième argument de la fonction test.

import { test } from 'vitest';

test('flaky test', () => {}, { retry: 3 }); 
test('flaky test', { retry: 3 }, () => {}); 

Lorsqu'une fonction de test renvoie une promesse, l'exécuteur attend sa résolution pour recueillir les assertions asynchrones. Si la promesse est rejetée, le test échoue.

TIP

Dans Jest, TestFunction peut également être de type (done: DoneCallback) => void. Si cette forme est utilisée, le test ne sera pas considéré comme terminé tant que done n'est pas appelé. Vous pouvez obtenir le même résultat en utilisant une fonction async, voir la section Guide de migration Done Callback.

Depuis Vitest 1.3.0, la plupart des options prennent en charge à la fois la syntaxe point et la syntaxe objet, vous permettant d'utiliser le style que vous préférez.

dot-syntax

import { test } from 'vitest';

test.skip('skipped test', () => {
  // some logic that fails right now
});

object-syntax 1.3.0+

import { test } from 'vitest';

test('skipped test', { skip: true }, () => {
  // some logic that fails right now
});

test

• Alias : it

test définit un ensemble d'attentes liées. Il reçoit le nom du test et une fonction qui contient les assertions à tester.

En option, vous pouvez fournir un délai d'attente (en millisecondes) pour spécifier la durée maximale d'exécution. La valeur par défaut est de 5 secondes et peut être configurée globalement avec testTimeout.

import { expect, test } from 'vitest';

test('should work as expected', () => {
  expect(Math.sqrt(4)).toBe(2);
});

test.extend 0.32.3+

• Alias : it.extend

Utilisez test.extend pour étendre le contexte de test avec des fixtures personnalisées. Cela renverra une nouvelle fonction test, qui est également extensible. Vous pouvez ainsi composer davantage de fixtures ou remplacer celles existantes en l'étendant selon vos besoins. Voir Étendre le contexte de test pour plus d'informations.

import { expect, test } from 'vitest';

const todos = [];
const archive = [];

const myTest = test.extend({
  todos: async ({ task }, use) => {
    todos.push(1, 2, 3);
    await use(todos);
    todos.length = 0;
  },
  archive,
});

myTest('add item', ({ todos }) => {
  expect(todos.length).toBe(3);

  todos.push(4);
  expect(todos.length).toBe(4);
});

test.skip

• Alias : it.skip

Si vous souhaitez ignorer certains tests sans supprimer le code, vous pouvez utiliser test.skip pour éviter de les exécuter.

import { assert, test } from 'vitest';

test.skip('skipped test', () => {
  // Test ignoré, pas d'erreur
  assert.equal(Math.sqrt(4), 3);
});

Vous pouvez également ignorer le test de manière dynamique en appelant skip sur son contexte :

import { assert, test } from 'vitest';

test('skipped test', context => {
  context.skip();
  // Test ignoré, pas d'erreur
  assert.equal(Math.sqrt(4), 3);
});

test.skipIf

• Alias : it.skipIf

Dans certains cas, vous pourriez exécuter des tests plusieurs fois dans différents environnements, et certains des tests peuvent être spécifiques à un environnement particulier. Au lieu d'encapsuler le code de test avec if, vous pouvez utiliser test.skipIf pour ignorer le test chaque fois que la condition est vraie.

import { assert, test } from 'vitest';

const isDev = process.env.NODE_ENV === 'development';

test.skipIf(isDev)('prod only test', () => {
  // ce test ne s'exécute qu'en production
});

WARNING

Vous ne pouvez pas utiliser cette syntaxe lorsque vous utilisez Vitest comme vérificateur de type.

test.runIf

• Alias : it.runIf

Opposé de test.skipIf.

import { assert, test } from 'vitest';

const isDev = process.env.NODE_ENV === 'development';

test.runIf(isDev)('dev only test', () => {
  // ce test ne s'exécute qu'en développement
});

WARNING

Vous ne pouvez pas utiliser cette syntaxe lorsque vous utilisez Vitest comme vérificateur de type.

test.only

• Alias : it.only

Utilisez test.only pour exécuter uniquement certains tests dans une suite donnée. Ceci est utile pour le débogage.

En option, vous pouvez fournir un délai d'attente (en millisecondes) pour spécifier la durée maximale d'exécution. La valeur par défaut est de 5 secondes et peut être configurée globalement avec testTimeout.

import { assert, test } from 'vitest';

test.only('test', () => {
  // Seul ce test (et les autres marqués avec only) est exécuté
  assert.equal(Math.sqrt(4), 2);
});

Parfois, il est très utile d'exécuter des tests only dans un certain fichier, en ignorant tous les autres tests de l'ensemble de la suite de tests, qui polluent la sortie.

Pour ce faire, exécutez vitest avec le fichier spécifique contenant les tests en question.

# vitest interesting.test.ts

test.concurrent

• Alias : it.concurrent

test.concurrent marque les tests consécutifs pour être exécutés en parallèle. Il reçoit le nom du test, une fonction asynchrone avec les tests à exécuter et un délai d'attente optionnel (en millisecondes).

import { describe, test } from 'vitest';

// The two tests marked with concurrent will be run in parallel
describe('suite', () => {
  test('serial test', async () => {
    /* ... */
  });
  test.concurrent('concurrent test 1', async () => {
    /* ... */
  });
  test.concurrent('concurrent test 2', async () => {
    /* ... */
  });
});

test.skip, test.only et test.todo fonctionnent avec les tests concurrents. Toutes les combinaisons suivantes sont valides :

test.concurrent(/* ... */);
test.skip.concurrent(/* ... */); // or test.concurrent.skip(/* ... */)
test.only.concurrent(/* ... */); // or test.concurrent.only(/* ... */)
test.todo.concurrent(/* ... */); // or test.concurrent.todo(/* ... */)

Lors de l'exécution de tests concurrents, les instantanés et les assertions doivent utiliser expect du contexte de test local pour garantir que le bon test est détecté.

test.concurrent('test 1', async ({ expect }) => {
  expect(foo).toMatchSnapshot();
});
test.concurrent('test 2', async ({ expect }) => {
  expect(foo).toMatchSnapshot();
});

WARNING

Vous ne pouvez pas utiliser cette syntaxe lorsque vous utilisez Vitest comme vérificateur de type.

test.sequential

• Alias : it.sequential

test.sequential marque un test comme séquentiel. Ceci est utile si vous souhaitez exécuter des tests en séquence au sein de describe.concurrent ou avec l'option de commande --sequence.concurrent.

import { describe, test } from 'vitest';

// ---cut---
// avec l'option de configuration { sequence: { concurrent: true } }
test('concurrent test 1', async () => {
  /* ... */
});
test('concurrent test 2', async () => {
  /* ... */
});

test.sequential('sequential test 1', async () => {
  /* ... */
});
test.sequential('sequential test 2', async () => {
  /* ... */
});

// au sein d'une suite concurrente
describe.concurrent('suite', () => {
  test('concurrent test 1', async () => {
    /* ... */
  });
  test('concurrent test 2', async () => {
    /* ... */
  });

  test.sequential('sequential test 1', async () => {
    /* ... */
  });
  test.sequential('sequential test 2', async () => {
    /* ... */
  });
});

test.todo

• Alias : it.todo

Utilisez test.todo pour créer des stubs de tests à implémenter ultérieurement. Une entrée apparaîtra dans le rapport pour ces tests afin que vous sachiez combien de tests vous devez encore implémenter.

// Une entrée sera affichée dans le rapport pour ce test
test.todo('unimplemented test');

test.fails

• Alias : it.fails

Utilisez test.fails pour indiquer qu'une assertion est censée échouer.

import { expect, test } from 'vitest';

function myAsyncFunc() {
  return new Promise(resolve => resolve(1));
}
test.fails('fail test', async () => {
  await expect(myAsyncFunc()).rejects.toBe(1);
});

WARNING

Vous ne pouvez pas utiliser cette syntaxe lorsque vous utilisez Vitest comme vérificateur de type.

test.each

• Alias : it.each

Utilisez test.each lorsque vous devez exécuter le même test avec différentes variables. Vous pouvez insérer des paramètres avec le formatage printf dans le nom du test, dans l'ordre des paramètres de la fonction de test.

• %s : chaîne de caractères
• %d : nombre
• %i : entier
• %f : valeur à virgule flottante
• %j : JSON
• %o : objet
• %# : index du cas de test
• %% : signe de pourcentage unique ('%')

import { expect, test } from 'vitest';

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

// ceci retournera
// ✓ add(1, 1) -> 2
// ✓ add(1, 2) -> 3
// ✓ add(2, 1) -> 3

Vous pouvez également accéder aux propriétés de l'objet avec le préfixe $, si vous utilisez des objets comme arguments :

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

// ceci retournera
// ✓ add(1, 1) -> 2
// ✓ add(1, 2) -> 3
// ✓ add(2, 1) -> 3

Vous pouvez également accéder aux attributs d'objet avec ., si vous utilisez des objets comme arguments :

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

// ceci retournera
// ✓ add(1, b) -> 1b
// ✓ add(2, b) -> 2b
// ✓ add(3, b) -> 3b

À partir de Vitest 0.25.3, vous pouvez également utiliser un tableau de chaînes de modèles.

• La première ligne doit contenir les noms de colonnes, séparés par | ;
• Une ou plusieurs lignes de données suivantes fournies sous forme d'expressions littérales de modèle utilisant la syntaxe ${value}.

import { expect, test } from 'vitest';

// ---cut---
test.each`
  a             | b      | expected
  ${1}          | ${1}   | ${2}
  ${'a'}        | ${'b'} | ${'ab'}
  ${[]}         | ${'b'} | ${'b'}
  ${{}}         | ${'b'} | ${'[object Object]b'}
  ${{ asd: 1 }} | ${'b'} | ${'[object Object]b'}
`('returns $expected when $a is added $b', ({ a, b, expected }) => {
  expect(a + b).toBe(expected);
});

Si vous souhaitez avoir accès à TestContext, utilisez describe.each avec un seul test.

TIP

Vitest traite les $values avec la méthode format de chai. Si la valeur est trop tronquée, vous pouvez augmenter chaiConfig.truncateThreshold dans votre fichier de configuration.

WARNING

Vous ne pouvez pas utiliser cette syntaxe lorsque vous utilisez Vitest comme vérificateur de type.

bench

• Type : (name: string | Function, fn: BenchFunction, options?: BenchOptions) => void

bench définit un benchmark. En termes Vitest, un benchmark est une fonction qui définit une série d'opérations. Vitest exécute cette fonction plusieurs fois afin d'afficher différents résultats de performance.

Vitest utilise la bibliothèque tinybench sous le capot, héritant de toutes ses options qui peuvent être utilisées comme troisième argument.

import { bench } from 'vitest';

bench(
  'normal sorting',
  () => {
    const x = [1, 5, 4, 2, 3];
    x.sort((a, b) => {
      return a - b;
    });
  },
  { time: 1000 }
);

export interface Options {
  /**
   * Temps nécessaire à l'exécution d'une tâche de *benchmark* (en millisecondes)
   * @default 500
   */
  time?: number;

  /**
   * Nombre de fois qu'une tâche doit être exécutée, même si le temps imparti est écoulé
   * @default 10
   */
  iterations?: number;

  /**
   * Fonction permettant d'obtenir l'horodatage actuel (en millisecondes)
   */
  now?: () => number;

  /**
   * Un `AbortSignal` permettant d'abandonner le *benchmark*
   */
  signal?: AbortSignal;

  /**
   * Temps de préparation (en millisecondes)
   * @default 100ms
   */
  warmupTime?: number;

  /**
   * Itérations de préparation
   * @default 5
   */
  warmupIterations?: number;

  /**
   * Fonction de configuration à exécuter avant chaque cycle de tâche de *benchmark*
   */
  setup?: Hook;

  /**
   * Fonction de démontage à exécuter après chaque cycle de tâche de *benchmark*
   */
  teardown?: Hook;
}

bench.skip

• Type : (name: string | Function, fn: BenchFunction, options?: BenchOptions) => void

Vous pouvez utiliser la syntaxe bench.skip pour ignorer l'exécution de certains benchmarks.

import { bench } from 'vitest';

bench.skip('normal sorting', () => {
  const x = [1, 5, 4, 2, 3];
  x.sort((a, b) => {
    return a - b;
  });
});

bench.only

• Type : (name: string | Function, fn: BenchFunction, options?: BenchOptions) => void

Utilisez bench.only pour exécuter uniquement certains benchmarks dans une suite donnée. Ceci est utile pour le débogage.

import { bench } from 'vitest';

bench.only('normal sorting', () => {
  const x = [1, 5, 4, 2, 3];
  x.sort((a, b) => {
    return a - b;
  });
});

bench.todo

• Type : (name: string | Function) => void

Utilisez bench.todo pour créer des stubs de benchmarks à implémenter ultérieurement.

import { bench } from 'vitest';

bench.todo('unimplemented test');

describe

Lorsque vous utilisez test ou bench au niveau supérieur d'un fichier, ils sont regroupés dans la suite implicite de ce fichier. En utilisant describe, vous pouvez définir une nouvelle suite dans le contexte actuel, servant à organiser un ensemble de tests ou de benchmarks associés, ainsi que d'autres suites imbriquées. Une suite vous permet d'organiser vos tests et benchmarks pour des rapports plus clairs et plus lisibles.

// basic.spec.ts
// organising tests

import { describe, expect, test } from 'vitest';

const person = {
  isActive: true,
  age: 32,
};

describe('person', () => {
  test('person is defined', () => {
    expect(person).toBeDefined();
  });

  test('is active', () => {
    expect(person.isActive).toBeTruthy();
  });

  test('age limit', () => {
    expect(person.age).toBeLessThanOrEqual(32);
  });
});

// basic.bench.ts
// organising benchmarks

import { bench, describe } from 'vitest';

describe('sort', () => {
  bench('normal', () => {
    const x = [1, 5, 4, 2, 3];
    x.sort((a, b) => {
      return a - b;
    });
  });

  bench('reverse', () => {
    const x = [1, 5, 4, 2, 3];
    x.reverse().sort((a, b) => {
      return a - b;
    });
  });
});

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

import { describe, expect, test } from 'vitest';

function numberToCurrency(value: number | string) {
  if (typeof value !== 'number') throw new Error('Value must be a number');

  return value
    .toFixed(2)
    .toString()
    .replace(/\B(?=(\d{3})+(?!\d))/g, ',');
}

describe('numberToCurrency', () => {
  describe('avec un nombre invalide', () => {
    test('doit lever une erreur avec des non-nombres', () => {
      expect(() => numberToCurrency('abc')).toThrowError();
    });
  });

  describe('avec un nombre valide', () => {
    test('retourne le format de devise correct', () => {
      expect(numberToCurrency(10000)).toBe('10,000.00');
    });
  });
});

describe.skip

• Alias: suite.skip

Utilisez describe.skip pour empêcher l'exécution d'un bloc describe spécifique.

import { assert, describe, test } from 'vitest';

describe.skip('skipped suite', () => {
  test('test de racine carrée', () => {
    // Suite ignorée, pas d'erreur
    assert.equal(Math.sqrt(4), 3);
  });
});

describe.skipIf

• Alias: suite.skipIf

Dans certains cas, vous pouvez exécuter des suites plusieurs fois dans différents environnements, et certaines suites peuvent être spécifiques à un environnement. Au lieu d'encapsuler la suite avec if, utilisez describe.skipIf pour ignorer la suite lorsque la condition est vraie.

import { describe, test } from 'vitest';

const isDev = process.env.NODE_ENV === 'development';

describe.skipIf(isDev)('prod only test', () => {
  // ce test ne s'exécute qu'en production
});

WARNING

Vous ne pouvez pas utiliser cette syntaxe lorsque vous utilisez Vitest comme vérificateur de type.

describe.runIf

• Alias : suite.runIf

Opposé de describe.skipIf.

import { assert, describe, test } from 'vitest';

const isDev = process.env.NODE_ENV === 'development';

describe.runIf(isDev)('dev only test suite', () => {
  // this test suite only runs in development
});

WARNING

Vous ne pouvez pas utiliser cette syntaxe lorsque vous utilisez Vitest comme vérificateur de type.

describe.only

• Type : (name: string | Function, fn: TestFunction, options?: number | TestOptions) => void

Utilisez describe.only pour exécuter uniquement certaines suites.

import { assert, describe, test } from 'vitest';
// ---cut---
// Seule cette suite (et les autres marquées avec only) sont exécutées
describe.only('suite', () => {
  test('sqrt', () => {
    assert.equal(Math.sqrt(4), 3);
  });
});

describe('other suite', () => {
  // ... sera ignoré
});

Il est parfois très utile d'exécuter des tests only dans un fichier spécifique, en ignorant tous les autres tests de l'ensemble de la suite de tests, qui pourraient polluer la sortie.

Pour ce faire, exécutez vitest avec le fichier spécifique contenant les tests en question.

# vitest interesting.test.ts

describe.concurrent

• Alias: suite.concurrent

describe.concurrent dans une suite marque chaque test comme concurrent.

import { describe, test } from 'vitest';
// ---cut---
// Tous les tests de cette suite seront exécutés en parallèle
describe.concurrent('suite', () => {
  test('concurrent test 1', async () => {
    /* ... */
  });
  test('concurrent test 2', async () => {
    /* ... */
  });
  test.concurrent('concurrent test 3', async () => {
    /* ... */
  });
});

.skip, .only et .todo fonctionnent avec les suites concurrentes. Toutes les combinaisons suivantes sont valides :

describe.concurrent(/* ... */);
describe.skip.concurrent(/* ... */); // or describe.concurrent.skip(/* ... */)
describe.only.concurrent(/* ... */); // or describe.concurrent.only(/* ... */)
describe.todo.concurrent(/* ... */); // or describe.concurrent.todo(/* ... */)

Lors de l'exécution de tests concurrents, les instantanés et les assertions doivent utiliser expect du contexte de test local pour garantir que le bon test est détecté.

describe.concurrent('suite', () => {
  test('concurrent test 1', async ({ expect }) => {
    expect(foo).toMatchSnapshot();
  });
  test('concurrent test 2', async ({ expect }) => {
    expect(foo).toMatchSnapshot();
  });
});

WARNING

Vous ne pouvez pas utiliser cette syntaxe lorsque vous utilisez Vitest comme vérificateur de type.

describe.sequential

• Alias: suite.sequential

describe.sequential dans une suite marque chaque test comme séquentiel. Ceci est utile si vous souhaitez exécuter des tests de manière séquentielle dans describe.concurrent ou avec l'option de commande --sequence.concurrent.

import { describe, test } from 'vitest';
// ---cut---
describe.concurrent('suite', () => {
  test('concurrent test 1', async () => {
    /* ... */
  });
  test('concurrent test 2', async () => {
    /* ... */
  });

  describe.sequential('', () => {
    test('sequential test 1', async () => {
      /* ... */
    });
    test('sequential test 2', async () => {
      /* ... */
    });
  });
});

describe.shuffle

• Alias: suite.shuffle

Vitest fournit un moyen d'exécuter tous les tests dans un ordre aléatoire via l'indicateur CLI --sequence.shuffle ou l'option de configuration sequence.shuffle, mais si vous souhaitez qu'une partie seulement de votre suite de tests exécute les tests dans un ordre aléatoire, vous pouvez la marquer avec cet indicateur.

import { describe, test } from 'vitest';
// ---cut---
describe.shuffle('suite', () => {
  test('random test 1', async () => {
    /* ... */
  });
  test('random test 2', async () => {
    /* ... */
  });
  test('random test 3', async () => {
    /* ... */
  });
});
// l'ordre dépend de l'option sequence.seed dans la configuration (Date.now() par défaut)

.skip, .only et .todo fonctionnent avec les suites aléatoires.

WARNING

Vous ne pouvez pas utiliser cette syntaxe lorsque vous utilisez Vitest comme vérificateur de type.

describe.todo

• Alias: suite.todo

Utilisez describe.todo pour marquer les suites à implémenter ultérieurement. Une entrée sera affichée dans le rapport pour ces tests, vous permettant de savoir combien de tests vous devez encore implémenter.

// Une entrée sera affichée dans le rapport pour cette suite
describe.todo('unimplemented suite');

describe.each

• Alias: suite.each

Utilisez describe.each si vous avez plusieurs tests qui dépendent des mêmes données.

import { describe, expect, test } from 'vitest';
// ---cut---
describe.each([
  { a: 1, b: 1, expected: 2 },
  { a: 1, b: 2, expected: 3 },
  { a: 2, b: 1, expected: 3 },
])("tester l'addition ($a, $b)", ({ a, b, expected }) => {
  test(`returns ${expected}`, () => {
    expect(a + b).toBe(expected);
  });

  test(`le résultat ne doit pas dépasser ${expected}`, () => {
    expect(a + b).not.toBeGreaterThan(expected);
  });

  test(`le résultat ne doit pas être inférieur à ${expected}`, () => {
    expect(a + b).not.toBeLessThan(expected);
  });
});

À partir de Vitest 0.25.3, vous pouvez également utiliser une table de chaînes de modèle.

• La première ligne doit contenir les noms de colonnes, séparés par | ;
• Une ou plusieurs lignes de données suivantes fournies sous forme d'expressions littérales de modèle utilisant la syntaxe ${value}.

import { describe, expect, test } from 'vitest';
// ---cut---
describe.each`
  a             | b      | expected
  ${1}          | ${1}   | ${2}
  ${'a'}        | ${'b'} | ${'ab'}
  ${[]}         | ${'b'} | ${'b'}
  ${{}}         | ${'b'} | ${'[object Object]b'}
  ${{ asd: 1 }} | ${'b'} | ${'[object Object]b'}
`('tester avec des templates', ({ a, b, expected }) => {
  test(`returns ${expected}`, () => {
    expect(a + b).toBe(expected);
  });
});

WARNING

Vous ne pouvez pas utiliser cette syntaxe lorsque vous utilisez Vitest comme vérificateur de type.

Configuration et démontage

Ces fonctions permettent d'intervenir dans le cycle de vie des tests, évitant ainsi la répétition du code de configuration et de démontage. Elles s'appliquent au contexte actuel : le fichier s'ils sont utilisés au niveau supérieur ou la suite actuelle s'ils se trouvent dans un bloc describe. Ces hooks ne sont pas appelés lorsque vous exécutez Vitest en tant que vérificateur de type.

beforeEach

• Type : beforeEach(fn: () => Awaitable<void>, timeout?: number)

Enregistrez une fonction de rappel à appeler avant l'exécution de chaque test dans le contexte actuel. Si la fonction renvoie une promesse, Vitest attend sa résolution avant d'exécuter le test.

Vous pouvez éventuellement passer un délai d'attente (en millisecondes) définissant la durée maximale d'attente avant d'interrompre l'exécution. La valeur par défaut est de 5 secondes.

import { beforeEach } from 'vitest';

beforeEach(async () => {
  // Effacer les mocks et ajouter des données de test avant chaque exécution de test
  await stopMocking();
  await addUser({ name: 'John' });
});

Ici, beforeEach garantit que l'utilisateur est ajouté pour chaque test.

À partir de Vitest v0.10.0, beforeEach accepte également une fonction de nettoyage optionnelle (équivalente à afterEach).

import { beforeEach } from 'vitest';

beforeEach(async () => {
  // appelée une fois avant chaque exécution de test
  await prepareSomething();

  // fonction de nettoyage, appelée une fois après chaque exécution de test
  return async () => {
    await resetSomething();
  };
});

afterEach

• Type : afterEach(fn: () => Awaitable<void>, timeout?: number)

Enregistrez une fonction de rappel à exécuter après chaque test dans le contexte actuel. Si la fonction renvoie une promesse, Vitest attend que la promesse se résolve avant de continuer.

Vous pouvez éventuellement fournir un délai d'attente (en millisecondes) pour spécifier la durée maximale d'attente avant d'interrompre l'exécution. La valeur par défaut est de 5 secondes.

import { afterEach } from 'vitest';

afterEach(async () => {
  await clearTestingData(); // effacer les données de test après chaque exécution de test
});

Ici, afterEach garantit que les données de test sont effacées après chaque exécution de test.

TIP

Vitest 1.3.0 a ajouté le hook onTestFinished. Vous pouvez l'appeler pendant l'exécution du test pour nettoyer tout état une fois le test terminé.

beforeAll

• Type : beforeAll(fn: () => Awaitable<void>, timeout?: number)

Enregistrez une fonction de rappel à appeler une seule fois avant de commencer à exécuter tous les tests dans le contexte actuel. Si la fonction renvoie une promesse, Vitest attend sa résolution avant d'exécuter les tests.

Vous pouvez éventuellement fournir un délai d'attente (en millisecondes) pour spécifier la durée maximale d'attente avant d'interrompre l'exécution. La valeur par défaut est de 5 secondes.

import { beforeAll } from 'vitest';

beforeAll(async () => {
  await startMocking(); // appelée une fois avant l'exécution de tous les tests
});

Ici, beforeAll garantit que les données mock sont configurées avant l'exécution des tests.

À partir de Vitest v0.10.0, beforeAll accepte également une fonction de nettoyage optionnelle (équivalente à afterAll).

import { beforeAll } from 'vitest';

beforeAll(async () => {
  // appelée une fois avant l'exécution de tous les tests
  await startMocking();

  // fonction de nettoyage, appelée une fois après l'exécution de tous les tests
  return async () => {
    await stopMocking();
  };
});

afterAll

• Type : afterAll(fn: () => Awaitable<void>, timeout?: number)

Enregistrez une fonction de rappel à appeler une seule fois après que tous les tests ont été exécutés dans le contexte actuel. Si la fonction renvoie une promesse, Vitest attend sa résolution avant de continuer.

Vous pouvez éventuellement fournir un délai d'attente (en millisecondes) pour spécifier la durée maximale d'attente avant d'interrompre l'exécution. La valeur par défaut est de 5 secondes.

import { afterAll } from 'vitest';

afterAll(async () => {
  await stopMocking(); // cette méthode est appelée après l'exécution de tous les tests
});

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

Hooks de test

Vitest fournit quelques hooks que vous pouvez appeler pendant l'exécution du test afin de nettoyer l'état une fois le test terminé.

WARNING

Ces hooks généreront une erreur s'ils sont appelés en dehors du corps du test.

onTestFinished 1.3.0+

Ce hook est toujours appelé après la fin de l'exécution du test. Il est appelé après les hooks afterEach car ils peuvent influencer le résultat du test. Il reçoit un objet TaskResult avec le résultat actuel du test.

import { onTestFinished, test } from 'vitest';

test('effectue une requête', () => {
  const db = connectDb();
  onTestFinished(() => db.close());
  db.query('SELECT * FROM users');
});

WARNING

Si vous exécutez des tests simultanément, vous devez toujours utiliser le hook onTestFinished à partir du contexte de test, car Vitest ne suit pas les tests simultanés dans les hooks globaux :

import { test from 'vitest'

test.concurrent('effectue une requête', ({ onTestFinished }) => {
  const db = connectDb()
  onTestFinished(() => db.close())
  db.query('SELECT * FROM users')
})

Ce hook est particulièrement utile lors de la création d'une logique réutilisable :

// ceci peut être dans un fichier séparé
function getTestDb() {
  const db = connectMockedDb()
  onTestFinished(() => db.close())
  return db
}

test('effectue une requête utilisateur', async () => {
  const db = getTestDb()
  expect(await db.query('SELECT * from users').perform()).toEqual([])
})

test('effectue une requête d'organisation', async () => {
  const db = getTestDb()
  expect(await db.query('SELECT * from organizations').perform()).toEqual([])
})

TIP

Ce hook est toujours appelé dans l'ordre inverse et n'est pas affecté par l'option sequence.hooks.

onTestFailed

Ce hook n'est appelé qu'une fois le test échoué. Il est appelé après les hooks afterEach car ils peuvent influencer le résultat du test. Il reçoit un objet TaskResult avec le résultat actuel du test. Ce hook est utile pour le débogage.

import { onTestFailed, test } from 'vitest';

test('effectue une requête', () => {
  const db = connectDb();
  onTestFailed(e => {
    console.log(e.result.errors);
  });
  db.query('SELECT * FROM users');
});

WARNING

Si vous exécutez des tests simultanément, vous devez toujours utiliser le hook onTestFailed à partir du contexte de test, car Vitest ne suit pas les tests simultanés dans les hooks globaux :

import { test from 'vitest'

test.concurrent('effectue une requête', ({ onTestFailed }) => {
  const db = connectDb()
  onTestFailed((result) => {
    console.log(result.errors)
  })
  db.query('SELECT * FROM users')
})