Estendendo Matchers

Como o Vitest é compatível com Chai e Jest, você pode usar a API chai.use ou expect.extend, a que você preferir.

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.

expect.extend({
  toBeFoo(received, expected) {
    const { isNot } = this;
    return {
      // não altere o seu "pass" com base em isNot. O Vitest faz isso por você
      pass: received === 'foo',
      message: () => `${received} is${isNot ? ' not' : ''} foo`,
    };
  },
});

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

import '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 tipo global em seu tsconfig.json.

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

interface ExpectationResult {
  pass: boolean;
  message: () => string;
  // Se você fornecer estes, eles aparecerão automaticamente em um diff quando
  // o matcher não passar, então você não precisará gerar o diff manualmente
  actual?: unknown;
  expected?: unknown;
}

WARNING

Se você criar um matcher assíncrono, não se esqueça de aplicar await ao resultado (await expect('foo').toBeFoo()) no próprio teste.

O primeiro argumento da função de um matcher é o valor recebido (o valor passado para expect(received)). Os demais são argumentos passados diretamente para o matcher.

As funções de matcher têm 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 com 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. Retornará true se os valores forem iguais, false caso contrário. É usada internamente para quase todos os matchers e suporta objetos com matchers assimétricos por padrão.

• utils

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

O contexto this também contém informações sobre o teste atual, que podem ser obtidas chamando expect.getState(). As propriedades mais úteis são:

• currentTestName

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

• testPath

  Caminho do teste atual.