@open-xchange/vitest-plugin-extended

A plugin for Vitest that bundles the package jest-extended with additional useful test matchers.

Installation

The plugin will take care of everything. It will add all test matchers to the expect object, and it will register all type definitions for test scripts written in TypeScript.

• Install the plugin as development dependency:

  npm install -D @open-xchange/vitest-plugin-extended
  # or
  pnpm add -D @open-xchange/vitest-plugin-extended
  # or
  yarn add -D @open-xchange/vitest-plugin-extended

• Create a setup script for Vitest (if not already existing, file name and path do not matter), and import the package:

  // test/setup.ts
  import '@open-xchange/vitest-plugin-extended'

• Register the setup script in the Vitest configuration:

  // vitest.config.ts
  import { defineConfig } from 'vitest/config'
  
  export default defineConfig({
    test: {
      globals: true,
      setupFiles: ['./test/setup.ts'],
    },
  })

That's it. The matchers can be used in test scripts:

// test/simple.test.ts
it('should work', () => {
  expect(true).toBeTrue()   // from 'jest-extended'
  expect([]).toBeIterable() // extra matchers from this plugin
})

Matchers

toBeInteger

Asserts that the received value is a safe integer.

expect(0).toBeInteger()
expect(-1e10).toBeInteger()
expect(Number.MAX_SAFE_INTEGER).toBeInteger()

expect(Number.MAX_SAFE_INTEGER + 1).not.toBeInteger()
expect(0.5).not.toBeInteger()
expect('0').not.toBeInteger()

toBeAlmost

Asserts that a floating-point number is almost equal to an expected number, with a relative error less than or equal to 2-51 which is twice the number of Number.EPSILON. If the number is expected to be zero, this method will check the absolute value of the received number instead of the relative error.

expect(Math.sin(Math.PI/2)).not.toBe(1)   // not exactly 1
expect(Math.sin(Math.PI/2)).toBeAlmost(1)

expect(Math.sin(Math.PI)).not.toBe(0)     // not exactly 0
expect(Math.sin(Math.PI)).toBeAlmost(0)

toStringifyTo

Asserts whether the tested value, converted to a string, equals the expectation.

expect([1, 2]).toStringifyTo('1,2')
expect({ toString: () => 42 }).toStringifyTo('42')

toThrowValue

Asserts whether the tested function will throw an exception with the exact value. The value does not need to be an instance of class Error.

function throws() { throw 42 }
expect(throws).toThrowValue(42)

toBeIterable

Asserts that a value is an iterable object (it responds to the well-known symbol @@iterator). The method will not be called.

expect([]).toBeIterable()
expect([].values()).toBeIterable()
expect('').toBeIterable()
expect({}).not.toBeIterable()

toBeIterator

Asserts that a value is an iterator object (it responds to next). The method will not be called.

expect([].values()).toBeIterator()
expect([]).not.toBeIterator()
expect({}).not.toBeIterator()

toHaveBeenCalledOn

Asserts that a mock function was called at least once with the specified calling context.

const spy = vi.fn()
spy.call(window)
spy.call(document)
expect(spy).toHaveBeenCalledOn(window)
expect(spy).not.toHaveBeenCalledOn(null)

toHaveBeenAlwaysCalledOn

Asserts that a mock function was always called with the specified calling context.

const spy = vi.fn()
spy.call(window)
spy.call(window)
expect(spy).toHaveBeenAlwaysCalledOn(window)
spy.call(document)
expect(spy).not.toHaveBeenAlwaysCalledOn(window)

toHaveAllBeenCalledTimes

Asserts that the call counts of all mock functions match the specified call counts.

const spies = [vi.fn(), vi.fn(), vi.fn()]
spies[1]()
spies[0]()
spies[1]()
expect(spies).toHaveAllBeenCalledTimes(1, 2, 0)

toHaveAllBeenCalledInOrder

Asserts that the the call order of the mock functions matches the specified call order.

const spies = [vi.fn(), vi.fn(), vi.fn()]
spies[2]()
spies[0]()
spies[1]()
expect(spies).toHaveAllBeenCalledInOrder(2, 0, 1)

toHaveDescendants

Asserts that a DOM element contains at least one descendant element that will be selected by a query string.

expect(document.body).toHaveDescendants('.my-element')