Erweiterung von Matchern

Da Vitest sowohl mit Chai als auch mit Jest kompatibel ist, können Sie entweder die chai.use-API oder expect.extend verwenden, je nachdem, welche Ihnen besser gefällt.

Dieser Leitfaden behandelt die Erweiterung von Matchern mit expect.extend. Wenn Sie sich für die API von Chai interessieren, lesen Sie deren Leitfaden.

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

expect.extend({
  toBeFoo(received, expected) {
    const { isNot } = this;
    return {
      // Verändern Sie das Ergebnis ("pass") nicht basierend auf isNot. Vitest kümmert sich darum.
      pass: received === 'foo',
      message: () => `${received} ist${isNot ? ' nicht' : ''} foo`,
    };
  },
});

Wenn Sie TypeScript verwenden, können Sie seit Vitest 0.31.0 die Standard-Assertion-Schnittstelle in einer Ambient Declaration-Datei (z. B.: vitest.d.ts) mit dem folgenden Code erweitern:

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

Vergessen Sie nicht, die Ambient Declaration-Datei in Ihre tsconfig.json aufzunehmen.

Der Rückgabewert eines Matchers sollte mit der folgenden Schnittstelle kompatibel sein:

interface MatcherResult {
  pass: boolean;
  message: () => string;
  // Wenn Sie diese angeben, werden sie automatisch in einem Diff angezeigt, wenn
  // der Matcher fehlschlägt, sodass Sie den Diff nicht selbst ausgeben müssen
  actual?: unknown;
  expected?: unknown;
}

WARNING

Wenn Sie einen asynchronen Matcher erstellen, vergessen Sie nicht, im Test selbst await für das Ergebnis zu verwenden (await expect('foo').toBeFoo()).

Das erste Argument in der Funktion eines Matchers ist der empfangene Wert (der Wert innerhalb von expect(received)). Die weiteren Argumente sind Argumente, die direkt an den Matcher übergeben werden.

Matcher-Funktionen haben Zugriff auf this 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 Modifikators. Andernfalls ist es eine leere Zeichenkette.

• equals

  Dies ist eine Hilfsfunktion, mit der Sie zwei Werte vergleichen können. 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 Anzeige 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 nützlichsten Eigenschaften sind:

• currentTestName

  Vollständiger Name des aktuellen Tests (einschließlich describe-Block).

• testPath

  Pfad zum aktuellen Test.