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

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.

La plupart des options prennent en charge la syntaxe par points et la syntaxe d'objets, ce qui vous permet d'utiliser le style que vous préférez.

dot-syntaxobject-syntax

import { test } from 'vitest';

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

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

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.

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

// 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

TIP

Alors que test.each est fourni pour la compatibilité avec Jest, Vitest possède également test.for avec une fonctionnalité supplémentaire pour intégrer TestContext.

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

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

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

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.

test.for

Alias : it.for

Alternative de test.each pour fournir TestContext.

La différence avec test.each réside dans la façon dont le cas des tableaux est fourni dans les arguments. Les autres cas non array (y compris l'utilisation de chaînes de modèles) fonctionnent exactement de la même manière.

// `each` étend le cas de tableau
test.each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
])('add(%i, %i) -> %i', (a, b, expected) => { 
  expect(a + b).toBe(expected);
});

// `for` n'étend pas le cas de tableau
test.for([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
])('add(%i, %i) -> %i', ([a, b, expected]) => { 
  expect(a + b).toBe(expected);
});

Le 2ème argument est TestContext et peut être utilisé pour un instantané concurrent, par exemple,

test.concurrent.for([
  [1, 1],
  [1, 2],
  [2, 1],
])('add(%i, %i)', ([a, b], { expect }) => {
  expect(a + b).matchSnapshot();
});

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;

  /**
   * Lance une erreur si une tâche échoue (les événements ne fonctionneront pas si vrai)
   */
  throws?: boolean;

  /**
   * 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;
}

Après l'exécution du cas de test, les informations sur la structure de sortie sont les suivantes :

  name                      hz     min     max    mean     p75     p99    p995    p999     rme  samples
· normal sorting  6,526,368.12  0.0001  0.3638  0.0002  0.0002  0.0002  0.0002  0.0004  ±1.41%   652638

export interface TaskResult {
  /*
   * la dernière erreur levée lors de l'exécution de la tâche
   */
  error?: unknown;

  /**
   * Le temps en millisecondes pour exécuter la tâche de benchmark (cycle).
   */
  totalTime: number;

  /**
   * la valeur minimale dans les échantillons
   */
  min: number;
  /**
   * la valeur maximale dans les échantillons
   */
  max: number;

  /**
   * le nombre d'opérations par seconde
   */
  hz: number;

  /**
   * combien de temps chaque opération prend (ms)
   */
  period: number;

  /**
   * les échantillons de temps d'itération de chaque tâche (ms)
   */
  samples: number[];

  /**
   * moyenne/moyenne des échantillons (estimation de la moyenne de la population)
   */
  mean: number;

  /**
   * variance des échantillons (estimation de la variance de la population)
   */
  variance: number;

  /**
   * écart-type des échantillons (estimation de l'écart-type de la population)
   */
  sd: number;

  /**
   * erreur standard de la moyenne (a.k.a. l'écart-type de la distribution d'échantillonnage de la moyenne de l'échantillon)
   */
  sem: number;

  /**
   * degrés de liberté
   */
  df: number;

  /**
   * valeur critique des échantillons
   */
  critical: number;

  /**
   * marge d'erreur
   */
  moe: number;

  /**
   * marge d'erreur relative
   */
  rme: number;

  /**
   * écart absolu médian
   */
  mad: number;

  /**
   * p50/centile médian
   */
  p50: number;

  /**
   * centile p75
   */
  p75: number;

  /**
   * centile p99
   */
  p99: number;

  /**
   * centile p995
   */
  p995: number;

  /**
   * centile p999
   */
  p999: number;
}

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

// 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 exécute toutes les suites et tous les tests internes en parallèle

import { describe, test } from 'vitest';

// Toutes les suites et tests au sein de cette suite seront exécutés en parallèle
describe.concurrent('suite', () => {
  test('concurrent test 1', async () => {
    /* ... */
  });
  describe('concurrent suite 2', async () => {
    test('concurrent test inner 1', async () => {
      /* ... */
    });
    test('concurrent test inner 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';

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

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

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

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.

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.

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

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')
})

Référence de l'API de Test ​

test ​

test.extend ​

test.skip ​

test.skipIf ​

test.runIf ​

test.only ​

test.concurrent ​

test.sequential ​

test.todo ​

test.fails ​

test.each ​

test.for ​

bench ​

bench.skip ​

bench.only ​

bench.todo ​

describe ​

describe.skip ​

describe.skipIf ​

describe.runIf ​

describe.only ​

describe.concurrent ​

describe.sequential ​

describe.shuffle ​

describe.todo ​

describe.each ​

Configuration et démontage ​

beforeEach ​

afterEach ​

beforeAll ​

afterAll ​

Hooks de test ​

onTestFinished ​

onTestFailed ​

Référence de l'API de Test

test

test.extend

test.skip

test.skipIf

test.runIf

test.only

test.concurrent

test.sequential

test.todo

test.fails

test.each

test.for

bench

bench.skip

bench.only

bench.todo

describe

describe.skip

describe.skipIf

describe.runIf

describe.only

describe.concurrent

describe.sequential

describe.shuffle

describe.todo

describe.each

Configuration et démontage

beforeEach

afterEach

beforeAll

afterAll

Hooks de test

onTestFinished

onTestFailed