Extender Matchers

Como Vitest es compatible con Chai y Jest, puedes usar la API chai.use o expect.extend, según tu preferencia.

Esta guía explica cómo extender los matchers con expect.extend. Si te interesa la API de Chai, consulta su guía.

Para extender los matchers predeterminados, usa expect.extend con un objeto que contenga los nuevos matchers.

expect.extend({
  toBeFoo(received, expected) {
    const { isNot } = this;
    return {
      // No modifiques el valor de "pass" basándote en isNot. Vitest lo gestiona automáticamente.
      pass: received === 'foo',
      message: () => `${received} ${isNot ? 'no ' : ''}es foo`,
    };
  },
});

Si usas TypeScript, a partir de Vitest 0.31.0, puedes extender la interfaz Assertion predeterminada en un archivo de declaración de entorno (por ejemplo: vitest.d.ts) con el siguiente código:

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

No olvides incluir el archivo de declaración de tipo en tu tsconfig.json.

El valor que devuelve un matcher debe ser compatible con la siguiente interfaz:

interface MatcherResult {
  pass: boolean;
  message: () => string;
  // Si proporcionas estos valores, aparecerán automáticamente dentro de un diff cuando
  // el matcher falle, por lo que no necesitas imprimir el diff manualmente.
  actual?: unknown;
  expected?: unknown;
}

WARNING

Si creas un matcher asíncrono, no olvides usar await con el resultado (await expect('foo').toBeFoo()) en la prueba.

El primer argumento dentro de la función de un matcher es el valor recibido (el valor dentro de expect(received)). El resto son los argumentos pasados directamente al matcher.

La función matcher tiene acceso al contexto this, que contiene las siguientes propiedades:

• isNot

  Devuelve true si el matcher se invocó con not (expect(received).not.toBeFoo()).

• promise

  Si el matcher se invocó con resolved o rejected, este valor contendrá el nombre del modificador. De lo contrario, será una cadena vacía.

• equals

  Esta es una función de utilidad que permite comparar dos valores. Devuelve true si los valores son iguales y false en caso contrario. Esta función se utiliza internamente para casi todos los matchers. Soporta objetos con matchers asimétricos de forma predeterminada.

• utils

  Contiene un conjunto de funciones de utilidad que puedes usar para mostrar mensajes.

El contexto this también contiene información sobre la prueba actual, que puedes obtener llamando a expect.getState(). Las propiedades más útiles incluyen:

• currentTestName

  Nombre completo de la prueba actual (incluyendo el bloque describe).

• testPath

  Ruta al archivo de la prueba actual.