Extensión de Matchers

Dado que Vitest es compatible tanto con Chai como con Jest, puedes optar por usar la API chai.use o expect.extend, según tu preferencia.

Esta guía se centrará en cómo extender los matchers utilizando expect.extend. Si te interesa la API de Chai, puedes consultar su guía.

Para extender los matchers predeterminados, simplemente llama a expect.extend y pásale un objeto que contenga tus matchers personalizados.

expect.extend({
  toBeFoo(received, expected) {
    const { isNot } = this;
    return {
      // No modifiques tu propiedad "pass" en función de 'isNot'. Vitest lo gestiona automáticamente.
      pass: received === 'foo',
      message: () => `${received} is${isNot ? ' not' : ''} foo`,
    };
  },
});

Si estás utilizando TypeScript, puedes extender la interfaz Assertion predeterminada en un archivo de declaración global (por ejemplo: vitest.d.ts) con el siguiente código:

import 'vitest';

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

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

WARNING

Asegúrate de incluir el archivo de declaración global en tu tsconfig.json.

El valor de retorno de un matcher debe ser compatible con la siguiente interfaz:

interface ExpectationResult {
  pass: boolean;
  message: () => string;
  // Si proporcionas 'actual' y 'expected', aparecerán automáticamente en un diff
  // cuando el matcher falle, eliminando la necesidad de imprimir el diff manualmente.
  actual?: unknown;
  expected?: unknown;
}

WARNING

Si creas un matcher asíncrono, recuerda usar await con el resultado (await expect('foo').toBeFoo()) dentro de tu test.

El primer argumento de la función de un matcher es el valor received (el que se pasa a expect(received)). Los argumentos subsiguientes se pasan directamente al matcher.

La función del matcher puede acceder al contexto this con las siguientes propiedades:

• isNot

  Devuelve true si el matcher fue llamado con not (ej: expect(received).not.toBeFoo()).

• promise

  Si el matcher fue llamado 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 te permite comparar dos valores. Devolverá true si los valores son iguales y false en caso contrario. Esta función se utiliza internamente en casi todos los matchers y, por defecto, soporta objetos con matchers asimétricos.

• utils

  Incluye un conjunto de funciones de utilidad que puedes usar para formatear mensajes.

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

• currentTestName

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

• testPath

  La ruta del archivo de la prueba actual.