Expandindo Matchers

Como o Vitest é compatível com Chai e Jest, você pode usar a API chai.use ou expect.extend, dependendo da sua preferência.

Este guia explorará como estender matchers com expect.extend. Se você estiver interessado na API do Chai, consulte o guia deles.

Para estender os matchers padrão, chame expect.extend com um objeto contendo seus matchers personalizados.

expect.extend({
  toBeFoo(received, expected) {
    const { isNot } = this;
    return {
      // Não altere o valor de 'pass' com base em isNot, pois o Vitest lida com isso automaticamente
      pass: received === 'foo',
      message: () => `${received} ${isNot ? 'não é ' : 'é '}foo`,
    };
  },
});

Se você estiver usando TypeScript, a partir do Vitest 0.31.0, você pode estender a interface Assertion padrão em um arquivo de declaração de ambiente (por exemplo: vitest.d.ts) com o código abaixo:

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

Não se esqueça de incluir o arquivo de declaração de ambiente no seu tsconfig.json.

O valor de retorno de um matcher deve ser compatível com a seguinte interface:

interface MatcherResult {
  pass: boolean;
  message: () => string;
  // Se você fornecer estes valores, eles aparecerão automaticamente dentro de um diff quando
  // o matcher falhar, então você não precisa imprimir o diff manualmente
  actual?: unknown;
  expected?: unknown;
}

WARNING

Se você criar um matcher assíncrono, não se esqueça de usar await ao chamar o matcher (await expect('foo').toBeFoo()) no teste em si.

O primeiro argumento dentro da função do matcher é o valor recebido (aquele dentro de expect(received)). Os demais argumentos são os valores passados diretamente para o matcher.

A função do matcher tem acesso ao contexto this com as seguintes propriedades:

• isNot

  Retorna true se o matcher foi chamado com .not (expect(received).not.toBeFoo()).

• promise

  Se o matcher foi chamado em resolved/rejected, este valor conterá o nome do modificador; caso contrário, será uma string vazia.

• equals

  Esta é uma função utilitária que permite comparar dois valores. Ela retornará true se os valores forem iguais e false caso contrário. Essa função é usada internamente na maioria dos matchers. Ela suporta objetos com matchers assimétricos por padrão.

• utils

  Contém um conjunto de funções utilitárias que você pode usar para formatar mensagens.

O contexto this também contém informações sobre o teste atual. Você também pode obtê-lo chamando expect.getState(). As propriedades mais úteis são:

• currentTestName

  Nome completo do teste atual (incluindo o bloco de describe).

• testPath

  Caminho para o arquivo de teste atual.