npm package: @open-xchange/vitest-plugin-extended
Description: Vitest plugin with additional useful test assertions
Latest version: 1.6.0

# @open-xchange/vitest-plugin-extended

A plugin for [Vitest](https://vitest.dev/) that bundles the package [jest-extended](https://jest-extended.jestcommunity.dev/) 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:

  ```sh
  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:

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

- Register the setup script in the Vitest configuration:

  ```ts
  // 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:

  ```ts
  // 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.

```ts
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<sup>-51</sup> 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.

```ts
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.

```ts
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`.

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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.

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