Étendre les Matchers

Vitest étant compatible avec Chai et Jest, vous avez la flexibilité d'utiliser soit l'API chai.use, soit expect.extend.

Ce guide se concentrera sur l'extension des matchers avec expect.extend. Si vous êtes intéressé par l'API de Chai, veuillez consulter le guide dédié.

Pour étendre les matchers par défaut, appelez expect.extend en lui passant un objet contenant vos matchers personnalisés.

expect.extend({
  toBeFoo(received, expected) {
    const { isNot } = this;
    return {
      // Ne modifiez pas la valeur de "pass" en fonction de isNot. Vitest gère cela automatiquement.
      pass: received === 'foo',
      message: () => `${received} is${isNot ? ' not' : ''} foo`,
    };
  },
});

Si vous utilisez TypeScript, vous pouvez étendre l'interface Assertion par défaut dans un fichier de déclaration global (par exemple, vitest.d.ts) en utilisant le code ci-dessous :

import 'vitest';

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

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

WARNING

Assurez-vous d'inclure le fichier de déclaration global dans votre tsconfig.json.

La valeur de retour d'un matcher doit être conforme à l'interface suivante :

interface ExpectationResult {
  pass: boolean;
  message: () => string;
  // Si ces propriétés sont fournies, elles apparaîtront automatiquement dans un diff
  // lorsque le matcher échoue, vous évitant ainsi d'afficher le diff manuellement.
  actual?: unknown;
  expected?: unknown;
}

WARNING

Si vous créez un matcher asynchrone, n'oubliez pas d'utiliser await pour le résultat (await expect('foo').toBeFoo()) directement dans votre test.

Le premier argument de la fonction d'un matcher est la valeur received (celle passée à expect(received)). Les arguments suivants sont ceux passés directement au matcher lui-même.

Les fonctions de matcher ont accès au contexte this qui contient les propriétés suivantes :

• isNot

  Retourne true si le matcher a été appelé avec le modificateur not (expect(received).not.toBeFoo()).

• promise

  Si le matcher a été appelé avec les modificateurs resolved ou rejected, cette valeur contiendra le nom du modificateur. Sinon, il s'agira d'une chaîne vide.

• equals

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

• utils

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

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

• currentTestName

  Nom complet du test actuel (incluant le bloc describe).

• testPath

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