Rozšíření matcherů

Jelikož je Vitest kompatibilní s Chai i Jest, můžete pro rozšíření matcherů použít buď API chai.use, nebo expect.extend, podle vaší preference.

Tato příručka se zaměří na rozšíření matcherů pomocí expect.extend. Pokud vás zajímá API Chai, podívejte se na jejich příručku.

Pro rozšíření výchozích matcherů zavolejte expect.extend s objektem, který obsahuje vaše vlastní matchery.

expect.extend({
  toBeFoo(received, expected) {
    const { isNot } = this;
    return {
      // Neměňte hodnotu "pass" na základě isNot. Vitest to provede automaticky.
      pass: received === 'foo',
      message: () => `${received} is${isNot ? ' not' : ''} foo`,
    };
  },
});

Pokud používáte TypeScript, můžete rozšířit výchozí rozhraní Assertion v ambientním deklaračním souboru (např. vitest.d.ts) pomocí následujícího kódu:

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 můžete rozšířit rozhraní Matchers pro typově bezpečná tvrzení v metodách expect.extend, expect().* a expect.* současně. Dříve bylo nutné definovat samostatná rozhraní pro každou z nich.

WARNING

Nezapomeňte zahrnout ambientní deklarační soubor do svého tsconfig.json.

Návratová hodnota matcheru by měla být kompatibilní s následujícím rozhraním:

interface ExpectationResult {
  pass: boolean;
  message: () => string;
  // Pokud jsou zadány, automaticky se objeví uvnitř rozdílového zobrazení, když
  // matcher selže, takže nemusíte rozdíly zobrazovat sami.
  actual?: unknown;
  expected?: unknown;
}

WARNING

Pokud vytváříte asynchronní matcher, nezapomeňte na výsledek použít await (await expect('foo').toBeFoo()) přímo v testu:

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

await expect().toBeAsyncAssertion();

První argument uvnitř funkce matcheru je přijatá hodnota (ta uvnitř expect(received)). Zbytek jsou argumenty, které jsou předány přímo matcheru.

Funkce matcheru má přístup ke kontextu this s následujícími vlastnostmi:

isNot

Vrací true, pokud byl matcher zavolán s not (expect(received).not.toBeFoo()).

promise

Pokud byl matcher volán s resolved nebo rejected, tato hodnota obsahuje název modifikátoru. Jinak bude prázdný řetězec.

equals

Jedná se o pomocnou funkci, která vám umožňuje porovnávat dvě hodnoty. Vrátí true, pokud jsou hodnoty stejné, jinak false. Tato funkce se interně používá pro téměř každý matcher. Ve výchozím nastavení podporuje objekty s asymetrickými matchery.

utils

Obsahuje sadu užitečných funkcí, které můžete použít k zobrazení zpráv.

Kontext this také obsahuje informace o aktuálním testu. Můžete je také získat zavoláním expect.getState(). Nejužitečnější vlastnosti jsou:

currentTestName

Celý název aktuálního testu (včetně popisujícího bloku).

testPath

Cesta k souboru aktuálního testu.