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

Поскольку 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) с помощью следующего кода:

3.2.0+

import 'vitest';

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

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

3.0.0+

import 'vitest';

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

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

TIP

Начиная с Vitest 3.2, вы можете расширить интерфейс Matchers, чтобы иметь типизированные утверждения в методах expect.extend, expect().* и expect.*. Ранее требовалось определять отдельные интерфейсы для каждого из них.

WARNING

Не забудьте включить файл декларации типов в ваш tsconfig.json.

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

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

WARNING

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

expect.extend({
  async toBeAsyncAssertion() {
    // ...
  },
});

await expect().toBeAsyncAssertion();

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

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

isNot

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

promise

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

equals

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

utils

Содержит набор служебных функций для отображения сообщений.

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

currentTestName

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

testPath

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