Estendere i Matcher

Vitest supporta sia Chai che Jest, offrendo la flessibilità di estendere i matcher tramite l'API chai.use o expect.extend, a seconda delle proprie preferenze.

Questa guida si concentrerà sull'estensione dei matcher con expect.extend. Per informazioni sull'API di Chai, si prega di consultare la loro guida.

Per estendere i matcher predefiniti, è sufficiente chiamare expect.extend passando un oggetto contenente le proprie implementazioni dei matcher.

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

Se si utilizza TypeScript, è possibile estendere l'interfaccia Assertion predefinita in un file di dichiarazione ambientale (ad esempio: vitest.d.ts) con il seguente codice:

import '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 di ritorno di un matcher deve essere compatibile con la seguente interfaccia:

interface ExpectationResult {
  pass: boolean;
  message: () => string;
  // Se questi valori sono forniti, appariranno automaticamente in un diff quando
  // il matcher fallisce, eliminando la necessità di stampare il diff manualmente.
  actual?: unknown;
  expected?: unknown;
}

WARNING

Se si crea un matcher asincrono, è necessario await il risultato (await expect('foo').toBeFoo()) all'interno del 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.

All'interno della funzione del matcher, il contesto this è accessibile e contiene le seguenti proprietà:

• isNot

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

• promise

  Se il matcher è stato chiamato con resolved o rejected, questo valore conterrà il nome del modificatore. Altrimenti, sarà una stringa vuota.

• equals

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

• utils

  Contiene un set di funzioni di utilità che possono essere utilizzate per formattare i messaggi.

Il contesto this contiene anche informazioni sul test corrente, che possono essere ottenute anche chiamando expect.getState(). Le proprietà più utili sono:

• currentTestName

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

• testPath

  Percorso del file del test corrente.