Расширение проверок (matchers)

Поскольку Vitest совместим как с Chai, так и с Jest, вы можете использовать API chai.use или expect.extend по вашему выбору.

В этом руководстве мы рассмотрим, как расширять проверки с помощью expect.extend. Если вас интересует API Chai, обратитесь к официальной документации Chai.

Чтобы расширить стандартные проверки, вызовите expect.extend с объектом, содержащим ваши собственные проверки.

expect.extend({
  toBeFoo(received, expected) {
    const { isNot } = this;
    return {
      // Не изменяйте "pass" в зависимости от isNot. Vitest сделает это за вас.
      pass: received === 'foo',
      message: () => `${received} is${isNot ? ' not' : ''} foo`,
    };
  },
});

Начиная с версии Vitest 0.31.0, при использовании TypeScript вы можете расширить интерфейс Assertion по умолчанию в файле объявлений типов (например, vitest.d.ts) следующим образом:

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

Убедитесь, что файл объявлений типов включен в ваш tsconfig.json.

Матчер должен возвращать объект, совместимый со следующим интерфейсом:

interface MatcherResult {
  pass: boolean;
  message: () => string;
  // Если вы передадите эти значения, они автоматически появятся в diff, когда
  // матчер не пройдет, поэтому вам не нужно выводить diff самостоятельно.
  actual?: unknown;
  expected?: unknown;
}

WARNING

Если вы создаете асинхронный матчер, не забудьте использовать await для получения результата (await expect('foo').toBeFoo()) в самом тесте.

Первый аргумент функции матчера — это полученное значение (значение внутри expect(received)). Остальные аргументы — это аргументы, переданные непосредственно матчеру.

Функция матчера имеет доступ к контексту this со следующими свойствами:

• isNot

  Возвращает true, если матчер был вызван с модификатором not (expect(received).not.toBeFoo()).

• promise

  Если матчер был вызван с модификаторами resolved или rejected, это значение будет содержать название модификатора. В противном случае это будет пустая строка.

• equals

  Это вспомогательная функция, которая позволяет сравнивать два значения. Она возвращает true, если значения равны, и false в противном случае. Эта функция используется внутри почти каждой проверки. Она поддерживает объекты, содержащие асимметричные матчеры.

• utils

  Он включает в себя набор утилитных функций, которые можно использовать для форматирования сообщений.

Контекст this также содержит информацию о текущем тесте, которую можно получить, вызвав expect.getState(). Наиболее полезные свойства:

• currentTestName

  Полное имя текущего теста (включая блоки describe).

• testPath

  Путь к файлу текущего теста.