Matcher erweitern

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

Dieser Leitfaden konzentriert sich auf die Erweiterung von Matchern mit expect.extend. Wenn Sie an der Chai-API interessiert sind, 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 {
      // Ändern Sie den Wert von "pass" nicht basierend auf isNot. Vitest übernimmt dies für Sie.
      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) mit dem folgenden Code erweitern:

3.2.0+

import 'vitest';

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

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

3.0.0+

import 'vitest';

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

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

TIP

Seit Vitest 3.2 können Sie die Matchers-Schnittstelle erweitern, um gleichzeitig typsichere Zusicherungen in expect.extend, expect().* und expect.*-Methoden zu ermöglichen. Zuvor mussten Sie separate Schnittstellen für jede davon definieren.

WARNING

Vergessen Sie nicht, die globale Deklarationsdatei in Ihre tsconfig.json aufzunehmen.

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

interface ExpectationResult {
  pass: boolean;
  message: () => string;
  // Werden diese Werte übergeben, erscheinen sie automatisch in einem Diff, 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, das Ergebnis (await expect('foo').toBeFoo()) im Test selbst abzuwarten:

expect.extend({
  async toBeAsyncAssertion() {
    // ...
  },
});

await expect().toBeAsyncAssertion();

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

Die Matcher-Funktion kann über den this-Kontext auf die folgenden Eigenschaften zugreifen:

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 handelt es sich um einen leeren String.

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. Sie unterstützt Objekte mit asymmetrischen Matchern standardmäßig.

utils

Es enthält eine Reihe von Hilfsfunktionen, die Sie zum Anzeigen von Nachrichten verwenden können.

Der this-Kontext enthält auch Informationen über den aktuellen Test. Sie können diese auch erhalten, indem Sie expect.getState() aufrufen. Die nützlichsten Eigenschaften sind:

currentTestName

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

testPath

Pfad zur aktuellen Testdatei.