Rozszerzanie Matcherów

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

W tym przewodniku pokażemy, jak rozszerzać matchery za pomocą expect.extend. Jeśli interesuje Cię API Chai, zapoznaj się z ich przewodnikiem.

Aby rozszerzyć standardowe matchery, wywołaj expect.extend z obiektem zawierającym Twoje własne matchery.

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

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

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

Pamiętaj, aby dołączyć plik deklaracji ambient do swojego tsconfig.json.

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

interface MatcherResult {
  pass: boolean;
  message: () => string;
  // Jeśli je przekażesz, automatycznie pojawią się w różnicy, gdy
  // matcher nie przejdzie, więc nie musisz sam drukować różnic.
  actual?: unknown;
  expected?: unknown;
}

WARNING

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

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

Funkcja matchera ma dostęp do kontekstu this z następującymi właściwościami:

• isNot

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

• promise

  Jeśli matcher został wywołany na resolved/rejected, ta wartość będzie zawierała nazwę modyfikatora. W przeciwnym razie będzie to pusty string.

• equals

  Jest to funkcja pomocnicza, która pozwala porównać dwie wartości. Zwróci true, jeśli wartości są równe, false w przeciwnym razie. Ta funkcja jest używana wewnętrznie przez większość matcherów. Domyślnie obsługuje obiekty z asymetrycznymi matcherami.

• utils

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

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

• currentTestName

  Pełna nazwa bieżącego testu (wraz z blokami describe).

• testPath

  Ścieżka do pliku z bieżącym testem.