Estensione dei Matchers

Vitest è compatibile sia con Chai che con Jest, quindi puoi utilizzare l'API chai.use o expect.extend, a seconda della tua preferenza.

Questa guida illustra come estendere i matcher utilizzando expect.extend. Se sei interessato all'API di Chai, consulta la loro guida.

Per estendere i matcher predefiniti, invoca expect.extend passando un oggetto contenente i tuoi matcher personalizzati.

expect.extend({
  toBeFoo(received, expected) {
    const { isNot } = this;
    return {
      // Non modificare il valore di "pass" in base a isNot. Vitest lo gestisce automaticamente.
      pass: received === 'foo',
      message: () => `${received} è${isNot ? ' non' : ''} foo`,
    };
  },
});

Se utilizzi TypeScript, a partire da Vitest 0.31.0, puoi estendere l'interfaccia Assertion predefinita in un file di dichiarazione ambientale (ad esempio: vitest.d.ts) con il codice seguente:

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

Non dimenticare di includere il file di dichiarazione ambientale nel tuo tsconfig.json.

Il valore restituito da un matcher deve essere conforme alla seguente interfaccia:

interface MatcherResult {
  pass: boolean;
  message: () => string;
  // Se fornisci questi valori, appariranno automaticamente all'interno di un diff quando
  // il matcher fallisce, quindi non è necessario stampare il diff manualmente.
  actual?: unknown;
  expected?: unknown;
}

WARNING

Se crei un matcher asincrono, ricordati di utilizzare await sul risultato (await expect('foo').toBeFoo()) nel test stesso.

Il primo argomento della funzione di un matcher è il valore ricevuto (quello all'interno di expect(received)). Gli argomenti successivi sono quelli passati direttamente al matcher.

Il matcher ha accesso al contesto this con le seguenti proprietà:

• isNot

  Restituisce true se il matcher è stato invocato con not (expect(received).not.toBeFoo()).

• promise

  Se il matcher è stato chiamato con resolved/rejected, questa proprietà conterrà il nome del modificatore. Altrimenti, sarà una stringa vuota.

• equals

  Questa funzione di utilità permette di confrontare due valori. Restituirà true se i valori sono uguali, false altrimenti. Questa funzione è utilizzata internamente da quasi tutti i matcher. Supporta gli oggetti con matcher asimmetrici per impostazione predefinita.

• utils

  Questo oggetto contiene un insieme di utility che puoi utilizzare per formattare i messaggi.

Il contesto this contiene anche informazioni sul test corrente. Puoi anche ottenerle chiamando expect.getState(). Le proprietà più utili includono:

• currentTestName

  Nome completo del test corrente (incluso il blocco describe).

• testPath

  Percorso del file di test corrente.