Extension des vérificateurs (Matchers)

Vitest étant compatible avec Chai et Jest, vous pouvez utiliser soit l'API chai.use, soit expect.extend, selon votre préférence.

Ce guide explique comment étendre les vérificateurs avec expect.extend. Si l'API de Chai vous intéresse, consultez leur guide.

Pour étendre les vérificateurs par défaut, appelez expect.extend avec un objet contenant vos vérificateurs personnalisés.

expect.extend({
  toBeFoo(received, expected) {
    const { isNot } = this;
    return {
      // Ne modifiez pas votre "pass" en fonction de isNot. Vitest le gère pour vous.
      pass: received === 'foo',
      message: () => `${received} n'est${isNot ? ' pas' : ''} foo`,
    };
  },
});

Si vous utilisez TypeScript, à partir de Vitest 0.31.0, vous pouvez étendre l'interface Assertion par défaut dans un fichier de déclaration globale (par exemple : vitest.d.ts) avec le code ci-dessous :

import type { Assertion, AsymmetricMatchersContaining } from 'vitest';

interface CustomMatchers<R = unknown> {
  toBeFoo: () => R;
}

declare module 'vitest' {
  interface Assertion<T = any> extends CustomMatchers<T> {}
  interface AsymmetricMatchersContaining extends CustomMatchers {}
}

WARNING

N'oubliez pas d'inclure le fichier de déclaration d'environnement dans votre tsconfig.json.

La valeur retournée par un vérificateur doit correspondre à l'interface suivante :

interface MatcherResult {
  pass: boolean;
  message: () => string;
  // Si vous les passez, ils apparaîtront automatiquement dans une diff lorsque
  // le vérificateur échoue, vous n'avez donc pas besoin d'afficher la diff vous-même.
  actual?: unknown;
  expected?: unknown;
}

WARNING

Si vous créez un vérificateur asynchrone, n'oubliez pas d'utiliser await pour le résultat (await expect('foo').toBeFoo()) dans le test lui-même.

Le premier argument d'une fonction de vérificateur est la valeur reçue (celle passée à expect(received)). Les arguments suivants sont passés directement au vérificateur.

La fonction de vérification a accès au contexte this avec les propriétés suivantes :

• isNot

  Retourne true si le vérificateur est appelé avec not (expect(received).not.toBeFoo()).

• promise

  Si le vérificateur a été appelé avec resolved ou rejected, cette valeur contiendra le nom du modificateur. Sinon, ce sera une chaîne vide.

• equals

  Une fonction utilitaire qui vous permet de comparer deux valeurs. Elle renvoie true si les valeurs sont égales, et false sinon. Cette fonction est utilisée en interne pour presque tous les vérificateurs. Elle prend en charge les objets avec des vérificateurs asymétriques par défaut.

• utils

  Contient un ensemble de fonctions utilitaires que vous pouvez utiliser pour formater les messages.

Le contexte this comprend également des informations sur le test en cours. Vous pouvez également l'obtenir en appelant expect.getState(). Les propriétés les plus utiles sont :

• currentTestName

  Nom complet du test en cours (y compris le bloc describe).

• testPath

  Chemin d'accès au fichier de test actuel.