Расширение матчеров

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

В этом руководстве будет рассмотрено расширение матчеров с помощью expect.extend. Если вас интересует API Chai, ознакомьтесь с их руководством.

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

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

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

import '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 ExpectationResult {
  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

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