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 swoich preferencji.

Ten przewodnik opisuje, jak rozszerzać matchery za pomocą expect.extend. Jeśli interesuje Cię API Chai, sprawdź ich przewodnik.

Aby rozszerzyć domyślne matchery, wywołaj 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 automatycznie to obsługuje.
      pass: received === 'foo',
      message: () => `${received} is${isNot ? ' not' : ''} foo`,
    };
  },
});

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

import 'vitest';

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

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

WARNING

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

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

interface ExpectationResult {
  pass: boolean;
  message: () => string;
  // Jeśli te właściwości zostaną przekazane, automatycznie pojawią się w różnicach, gdy
  // matcher nie przejdzie, eliminując potrzebę ręcznego wyświetlania różnic.
  actual?: unknown;
  expected?: unknown;
}

WARNING

Jeśli tworzysz asynchroniczny matcher, pamiętaj o użyciu await na wyniku (await expect('foo').toBeFoo()) w samym teście.

Pierwszy argument w funkcji matchera to otrzymana wartość (ta w expect(received)). Pozostałe argumenty to te przekazane 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 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, w przeciwnym razie false. Ta funkcja jest używana wewnętrznie przez prawie każdy matcher. Domyślnie obsługuje obiekty z asymetrycznymi matcherami.

• utils

  Zawiera zestaw funkcji pomocniczych, których można użyć do formatowania 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 (wraz z blokiem describe).

• testPath

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