Étendre les Matchers

Depuis Vitest est compatible avec Chai et Jest, vous pouvez utiliser l’API chai.use ou expect.extend, selon votre préférence.

Ce guide explorera l’extension des matchers avec expect.extend. Si vous êtes intéressé par l’API de Chai, consultez leur guide.

Pour étendre les matchers par défaut, appelez expect.extend avec un objet contenant vos matchers.

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

Si vous utilisez TypeScript, vous pouvez étendre l’interface Assertion par défaut dans un fichier de déclaration ambiante (par exemple : vitest.d.ts) avec 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 {}
}

Attention

N’oubliez pas d’inclure le fichier de déclaration ambiante dans votre tsconfig.json.

La valeur de retour d’un matcher doit être compatible avec l’interface suivante :

interface ExpectationResult {
  pass: boolean
  message: () => string
  // Si vous passez ces valeurs, elles apparaîtront automatiquement dans un diff lorsque
  // le matcher ne passe pas, donc vous n'avez pas besoin d'imprimer le diff vous-même
  actual?: unknown
  expected?: unknown
}

Attention

Si vous créez un matcher asynchrone, n’oubliez pas de await le résultat (await expect('foo').toBeFoo()) dans le test lui-même.

Le premier argument à l’intérieur d’une fonction de matcher est la valeur reçue (celle à l’intérieur de expect(received)). Le reste sont des arguments passés directement au matcher.

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

• isNot

  Retourne vrai, si le matcher a été appelé sur not (expect(received).not.toBeFoo()).

• promise

  Si le matcher a été appelé sur resolved/rejected, cette valeur contiendra le nom du modificateur. Sinon, ce sera une chaîne vide.

• equals

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

• utils

  Cela contient un ensemble de fonctions utilitaires que vous pouvez utiliser pour afficher des messages.

Le contexte this contient é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 vers le test en cours.