Contexte de Test

Inspiré par Playwright Fixtures, le contexte de test de Vitest vous permet de définir des utilitaires, des états et des fixtures utilisables dans vos tests.

Utilisation

Le premier argument de chaque fonction de test est un contexte de test.

import { it } from 'vitest';

it('should work', ctx => {
  // affiche le nom du test
  console.log(ctx.task.name);
});

Contexte de Test Intégré

context.task

Un objet en lecture seule contenant des métadonnées sur le test en cours.

context.expect

L'API expect liée au test actuel :

import { it } from 'vitest';

it('math is easy', ({ expect }) => {
  expect(2 + 2).toBe(4);
});

Cette API est utile pour exécuter des tests de snapshot en parallèle, car l'expect global ne peut pas les suivre correctement :

import { it } from 'vitest';

it.concurrent('math is easy', ({ expect }) => {
  expect(2 + 2).toMatchInlineSnapshot();
});

it.concurrent('math is hard', ({ expect }) => {
  expect(2 * 2).toMatchInlineSnapshot();
});

context.skip

Ignore l'exécution du test et le marque comme ignoré :

import { expect, it } from 'vitest';

it('math is hard', ({ skip }) => {
  skip();
  expect(2 + 2).toBe(5);
});

Étendre le Contexte de Test

Vitest fournit deux méthodes pour étendre le contexte de test.

test.extend

WARNING

Cette API est disponible depuis Vitest 0.32.3.

Comme Playwright, vous pouvez utiliser cette méthode pour définir votre propre API test avec des fixtures personnalisées et la réutiliser.

Par exemple, créons d'abord myTest avec deux fixtures, todos et archive.

// my-test.ts
import { test } from 'vitest';

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

export const myTest = test.extend({
  todos: async ({ task }, use) => {
    // configure la fixture avant chaque fonction de test
    todos.push(1, 2, 3);

    // utilise la valeur de la fixture
    await use(todos);

    // nettoie la fixture après chaque fonction de test
    todos.length = 0;
  },
  archive,
});

Ensuite, nous pouvons l'importer et l'utiliser.

import { expect } from 'vitest';
import { myTest } from './my-test.ts';

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

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

myTest('move items from todos to archive', ({ todos, archive }) => {
  expect(todos.length).toBe(3);
  expect(archive.length).toBe(0);

  archive.push(todos.pop());
  expect(todos.length).toBe(2);
  expect(archive.length).toBe(1);
});

Nous pouvons également ajouter d'autres fixtures ou remplacer les fixtures existantes en étendant myTest.

export const myTest2 = myTest.extend({
  settings: {
    // ...
  },
});

Initialisation des Fixtures

L'exécuteur de tests de Vitest initialise intelligemment vos fixtures et les injecte dans le contexte de test en fonction de leur utilisation.

import { test } from 'vitest';

async function todosFn({ task }, use) {
  await use([1, 2, 3]);
}

const myTest = test.extend({
  todos: todosFn,
  archive: [],
});

// todosFn ne sera pas exécuté
myTest('', () => {});
myTest('', ({ archive }) => {});

// todosFn sera exécuté
myTest('', ({ todos }) => {});

WARNING

Lorsque vous utilisez test.extend() avec des fixtures, vous devez toujours utiliser la déstructuration d'objet { todos } pour accéder au contexte, aussi bien dans la fonction de fixture que dans la fonction de test.

Fixture automatique

WARNING

Cette fonctionnalité est disponible depuis Vitest 1.3.0.

Vitest prend également en charge la syntaxe de tuple pour les fixtures, ce qui vous permet de passer des options pour chaque fixture. Par exemple, vous pouvez l'utiliser pour initialiser explicitement une fixture, même si elle n'est pas utilisée dans les tests.

import { test as base } from 'vitest';

const test = base.extend({
  fixture: [
    async ({}, use) => {
      // cette fonction sera exécutée
      setup();
      await use();
      teardown();
    },
    { auto: true }, // Marquer comme une fixture automatique
  ],
});

test('', () => {});

TypeScript

Pour fournir des types de fixtures pour tous vos contextes personnalisés, vous pouvez passer le type de fixtures en tant que paramètre générique.

interface MyFixtures {
  todos: number[];
  archive: number[];
}

const myTest = test.extend<MyFixtures>({
  todos: [],
  archive: [],
});

myTest('', context => {
  expectTypeOf(context.todos).toEqualTypeOf<number[]>();
  expectTypeOf(context.archive).toEqualTypeOf<number[]>();
});

beforeEach et afterEach

Chaque test a son propre contexte. Vous pouvez y accéder et l'étendre grâce aux hooks beforeEach et afterEach.

import { beforeEach, it } from 'vitest';

beforeEach(async context => {
  // étend le contexte
  context.foo = 'bar';
});

it('should work', ({ foo }) => {
  console.log(foo); // 'bar'
});

TypeScript

Pour définir les types de propriété pour tous vos contextes personnalisés, vous pouvez compléter le type TestContext en ajoutant :

declare module 'vitest' {
  export interface TestContext {
    foo?: string;
  }
}

Si vous souhaitez fournir des types de propriété uniquement pour des hooks beforeEach, afterEach, it et test spécifiques, vous pouvez passer le type en tant que paramètre générique.

interface LocalTestContext {
  foo: string;
}

beforeEach<LocalTestContext>(async context => {
  // typeof context is 'TestContext & LocalTestContext'
  context.foo = 'bar';
});

it<LocalTestContext>('should work', ({ foo }) => {
  // typeof foo is 'string'
  console.log(foo); // 'bar'
});