Matcher erweitern

Da Vitest sowohl mit Chai als auch mit Jest kompatibel ist, können Sie Matcher entweder über die chai.use-API oder expect.extend erweitern, je nach Ihrer Präferenz.

Dieser Leitfaden konzentriert sich auf die Erweiterung von Matchern mit expect.extend. Wenn Sie die Chai-API bevorzugen, finden Sie weitere Informationen in deren Leitfaden.

Um Standard-Matcher zu erweitern, rufen Sie expect.extend mit einem Objekt auf, das Ihre benutzerdefinierten Matcher enthält.

expect.extend({
  toBeFoo(received, expected) {
    const { isNot } = this;
    return {
      // Der Wert von "pass" sollte nicht in Abhängigkeit von isNot geändert werden. Vitest übernimmt dies automatisch.
      pass: received === 'foo',
      message: () => `${received} is${isNot ? ' not' : ''} foo`,
    };
  },
});

Wenn Sie TypeScript verwenden, können Sie die Standard-Schnittstelle Assertion in einer globalen Deklarationsdatei (z. B. vitest.d.ts) wie folgt erweitern:

import 'vitest';

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

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

WARNING

Stellen Sie sicher, dass die globale Deklarationsdatei in Ihrer tsconfig.json enthalten ist.

Der Rückgabewert eines Matchers muss mit dem folgenden Interface kompatibel sein:

interface ExpectationResult {
  pass: boolean;
  message: () => string;
  // Wenn diese Eigenschaften übergeben werden, werden sie bei einem Fehlschlag des Matchers automatisch in einem Diff angezeigt.
  // Sie müssen den Diff also nicht manuell ausgeben.
  actual?: unknown;
  expected?: unknown;
}

WARNING

Wenn Sie einen asynchronen Matcher erstellen, vergessen Sie nicht, im Test selbst auf das Ergebnis zu warten (await expect('foo').toBeFoo()).

Das erste Argument innerhalb der Matcher-Funktion ist der empfangene Wert (der Wert innerhalb von expect(received)). Alle weiteren Argumente werden direkt an den Matcher übergeben.

Matcher-Funktionen haben Zugriff auf den this-Kontext mit den folgenden Eigenschaften:

• isNot

  Gibt true zurück, wenn der Matcher mit not aufgerufen wurde (expect(received).not.toBeFoo()).

• promise

  Wenn der Matcher mit resolved oder rejected aufgerufen wurde, enthält dieser Wert den Namen des Modifizierers. Andernfalls ist er ein leerer String.

• equals

  Dies ist eine Hilfsfunktion zum Vergleichen von zwei Werten. Sie gibt true zurück, wenn die Werte gleich sind, andernfalls false. Diese Funktion wird intern für fast jeden Matcher verwendet und unterstützt standardmäßig Objekte mit asymmetrischen Matchern.

• utils

  Dies enthält eine Reihe von Hilfsfunktionen, die Sie zur Formatierung von Nachrichten verwenden können.

Der this-Kontext enthält auch Informationen über den aktuellen Test. Diese können auch durch Aufrufen von expect.getState() abgerufen werden. Die wichtigsten Eigenschaften sind:

• currentTestName

  Der vollständige Name des aktuellen Tests (einschließlich des describe-Blocks).

• testPath

  Der Pfad zur aktuellen Testdatei.