Rozszerzanie matcherów

Ponieważ Vitest jest kompatybilny zarówno z Chai, jak i Jest, możesz używać API chai.use lub expect.extend, w zależności od Twoich preferencji.

Ten przewodnik omówi rozszerzanie matcherów za pomocą expect.extend. Jeśli interesuje Cię API Chai, sprawdź ich przewodnik.

Aby rozszerzyć domyślne matchery, należy wywołać expect.extend z obiektem zawierającym Twoje niestandardowe matchery.

expect.extend({
  toBeFoo(received, expected) {
    const { isNot } = this;
    return {
      // Nie zmieniaj wartości "pass" w zależności od isNot. Vitest robi to za Ciebie.
      pass: received === 'foo',
      message: () => `${received} is${isNot ? ' not' : ''} foo`,
    };
  },
});

Jeśli używasz TypeScript, możesz rozszerzyć domyślny interfejs Assertion w pliku deklaracji globalnych (np. vitest.d.ts) za pomocą poniższego kodu:

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

Od Vitest 3.2, możesz rozszerzyć interfejs Matchers, aby uzyskać bezpieczeństwo typów dla asercji w metodach expect.extend, expect().* i expect.* jednocześnie. Wcześniej wymagane było definiowanie oddzielnych interfejsów dla każdej z nich.

WARNING

Nie zapomnij dołączyć pliku deklaracji środowiskowej do swojego tsconfig.json.

Wartość zwracana przez matcher powinna być kompatybilna z następującym interfejsem:

interface ExpectationResult {
  pass: boolean;
  message: () => string;
  // Jeśli je podasz, automatycznie pojawią się w raporcie różnic, gdy
  // matcher nie przejdzie, więc nie musisz samodzielnie wyświetlać różnic.
  actual?: unknown;
  expected?: unknown;
}

WARNING

Jeśli tworzysz asynchroniczny matcher, nie zapomnij użyć await na wyniku (await expect('foo').toBeFoo()) w samym teście:

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

await expect().toBeAsyncAssertion();

Pierwszym argumentem w funkcji matchera jest otrzymana wartość (ta w expect(received)). Pozostałe argumenty są przekazywane bezpośrednio do matchera.

Funkcja matchera ma dostęp do kontekstu this, który zawiera następujące właściwości:

isNot

Zwraca true, jeśli matcher został wywołany z użyciem not (expect(received).not.toBeFoo()).

promise

Jeśli matcher został wywołany z modyfikatorem resolved lub rejected, ta wartość będzie zawierać nazwę modyfikatora. W przeciwnym razie będzie to pusty ciąg znaków.

equals

Jest to funkcja pomocnicza, która pozwala porównywać dwie wartości. Zwróci true, jeśli wartości są równe, false w przeciwnym wypadku. Ta funkcja jest używana wewnętrznie dla prawie każdego matchera. Domyślnie obsługuje obiekty z asymetrycznymi matcherami.

utils

Zawiera zestaw funkcji pomocniczych, których możesz użyć do wyświetlania komunikatów.

Kontekst this zawiera również informacje o bieżącym teście. Możesz je również uzyskać, wywołując expect.getState(). Najbardziej przydatne właściwości to:

currentTestName

Pełna nazwa bieżącego testu (łącznie z blokiem describe).

testPath

Ścieżka do pliku bieżącego testu.