### Start Local Development Server

Source: https://github.com/jest-community/jest-extended/blob/main/website/README.md

Start a local development server for live preview. Changes are reflected without restarting.

```bash
$ yarn start
```

--------------------------------

### Install Dependencies with Yarn

Source: https://github.com/jest-community/jest-extended/blob/main/CONTRIBUTING.md

Run this command to install all project dependencies after cloning the repository.

```bash
yarn install
```

--------------------------------

### Configure Jest Setup Files

Source: https://github.com/jest-community/jest-extended/blob/main/examples/typescript/all/README.md

Add 'jest-extended/all' to the setupFilesAfterEnv field in your Jest configuration to enable global setup.

```javascript
module.exports = {
  setupFilesAfterEnv: ['jest-extended/all'],
};
```

--------------------------------

### Configure Vitest setupFiles

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/getting-started/setup.md

Add your Vitest setup script to the `setupFiles` array in your `vitest.config.js`.

```javascript
export default defineConfig({
  test: {
    setupFiles: ['./testSetup.js'],
  },
});
```

--------------------------------

### Install Jest Extended

Source: https://github.com/jest-community/jest-extended/blob/main/website/README.md

Install Jest Extended using yarn.

```bash
$ yarn
```

--------------------------------

### Create Jest Setup Script

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/getting-started/setup.md

Create a setup script to import and extend Jest's `expect` with jest-extended matchers. You can import all matchers or specific ones.

```javascript
// add all jest-extended matchers
import * as matchers from 'jest-extended';
expect.extend(matchers);

// or just add specific matchers
import { toBeArray, toBeSealed } from 'jest-extended';
expect.extend({ toBeArray, toBeSealed });
```

--------------------------------

### Vitest Setup Script

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/getting-started/setup.md

Use this setup script for `jest-extended` with Vitest, as their `expect.extend` API is compatible. Ensure you import `expect` from `vitest`.

```javascript
import { expect } from 'vitest';
import * as matchers from 'jest-extended';
expect.extend(matchers);
```

--------------------------------

### Vitest Custom Matcher TypeScript types setup (< 0.31.0)

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/getting-started/setup.md

Example of combining jest-extended types with your own custom matchers for Vitest versions older than 0.31.0, using the 'vi' module.

```typescript
import type CustomMatchers from 'jest-extended';
import 'vi';

interface MyCustomMatchers {
  toBeFoo(): any;
}

declare module 'vi' {
  interface Assertion<T = any> extends CustomMatchers<T>, MyCustomMatchers {}
  interface AsymmetricMatchersContaining<T = any> extends CustomMatchers<T>, MyCustomMatchers {}
  interface ExpectStatic extends CustomMatchers, MyCustomMatchers {}
}
```

--------------------------------

### Install ESLint and Jest Extended Plugin (npm)

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/getting-started/eslint.md

Use this command to install ESLint and the jest-extended plugin as development dependencies using npm.

```bash
npm install --save-dev eslint eslint-plugin-jest-extended
```

--------------------------------

### Install Jest Extended with npm

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/getting-started/install.md

Use this command to install Jest Extended as a dev dependency with npm.

```sh
npm install --save-dev jest-extended
```

--------------------------------

### Install Jest Extended with yarn

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/getting-started/install.md

Use this command to install Jest Extended as a dev dependency with yarn.

```sh
yarn add -D jest-extended
```

--------------------------------

### Configure Jest setupFilesAfterEnv in package.json

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/getting-started/setup.md

Alternatively, specify your setup script in the `setupFilesAfterEnv` array within your `package.json`.

```json
"jest": {
  "setupFilesAfterEnv": ["./testSetup.js"]
}
```

--------------------------------

### Install ESLint and Jest Extended Plugin (Yarn)

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/getting-started/eslint.md

Use this command to install ESLint and the jest-extended plugin as development dependencies using Yarn.

```bash
yarn add --dev eslint eslint-plugin-jest-extended
```

--------------------------------

### Vitest Custom Matcher TypeScript types setup (>= 0.31.0)

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/getting-started/setup.md

Example of combining jest-extended types with your own custom matchers for Vitest versions 0.31.0 and newer.

```typescript
import type CustomMatchers from 'jest-extended';
import 'vitest';

interface MyCustomMatchers {
  toBeFoo(): any;
}

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

--------------------------------

### Check if string starts with a prefix

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/string.mdx

Use `.toStartWith` to verify if a string begins with a specified prefix. This is a direct check for the beginning of the string.

```javascript
test('passes when value is starts with given string', () => {
  expect('hello world').toStartWith('hello');
  expect('hello world').not.toStartWith('world');
});
```

--------------------------------

### Run Tests with Yarn

Source: https://github.com/jest-community/jest-extended/blob/main/CONTRIBUTING.md

Execute this command to validate that your project setup is working correctly by running the test suite.

```bash
yarn test
```

--------------------------------

### Vitest TypeScript types setup (>= 0.31.0)

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/getting-started/setup.md

For Vitest versions 0.31.0 and newer, use this TypeScript declaration file to integrate jest-extended types.

```typescript
import type CustomMatchers from 'jest-extended';
import 'vitest';

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

--------------------------------

### Vitest TypeScript types setup (< 0.31.0)

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/getting-started/setup.md

For Vitest versions older than 0.31.0, use this TypeScript declaration file to integrate jest-extended types with the 'vi' module.

```typescript
import type CustomMatchers from 'jest-extended';
import 'vi';

declare module 'vi' {
  interface Assertion<T = any> extends CustomMatchers<T> {}
  interface AsymmetricMatchersContaining<T = any> extends CustomMatchers<T> {}
  interface ExpectStatic<T = any> extends CustomMatchers<T> {}
}
```

--------------------------------

### toBeWithin

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/number.mdx

Checks if a number is within a specified range (inclusive start, exclusive end).

```APIDOC
## .toBeWithin(start, end)

### Description
Use `.toBeWithin` when checking if a number is in between the given bounds of: start (inclusive) and end (exclusive).

### Method
`expect(value).toBeWithin(start, end)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "expect(1).toBeWithin(1, 3)"
}
```

### Response
#### Success Response (200)
- **value** (Number) - The number being tested.
- **start** (Number) - The inclusive start of the range.
- **end** (Number) - The exclusive end of the range.

#### Response Example
```json
{
  "example": "expect(1).toBeWithin(1, 3)"
}
```
```

--------------------------------

### Use .toBeWithin() for range checks

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/number.mdx

Use `.toBeWithin` to check if a number falls between a start (inclusive) and end (exclusive) bound. It does not support `BigInt`.

```javascript
test('passes when number is within given bounds', () => {
  expect(1).toBeWithin(1, 3);
  expect(2).toBeWithin(1, 3);
  expect(3).not.toBeWithin(1, 3);
});
```

--------------------------------

### Use .toSatisfy with a custom predicate function

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/toSatisfy.mdx

Use `.toSatisfy` when you want to use a custom matcher by supplying a predicate function that returns a `Boolean`. This example demonstrates passing a predicate that checks if a number is greater than one but not equal to three.

```javascript
test('passes when value passes given predicate', () => {
  const greaterThanOneButNotThree = n => n > 1 && n !== 3;
  expect(100).toSatisfy(greaterThanOneButNotThree);
  expect(0).not.toSatisfy(greaterThanOneButNotThree);
  expect(3).not.toSatisfy(greaterThanOneButNotThree);
});
```

--------------------------------

### Deploy Website via SSH

Source: https://github.com/jest-community/jest-extended/blob/main/website/README.md

Build and deploy the website using SSH. Assumes SSH is configured for deployment.

```bash
$ USE_SSH=true yarn deploy
```

--------------------------------

### Build Static Website

Source: https://github.com/jest-community/jest-extended/blob/main/website/README.md

Generate static website content into the build directory for hosting.

```bash
$ yarn build
```

--------------------------------

### Configure Jest with setupFilesAfterEnv

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/getting-started/setup.md

Add this line to your `jest.config.mjs` to include all jest-extended matchers.

```javascript
/** @type {import('jest').Config} */
const config = {
  ///...
  setupFilesAfterEnv: ['jest-extended/all'],
  ///...
}
```

--------------------------------

### Add Files for Committing

Source: https://github.com/jest-community/jest-extended/blob/main/CONTRIBUTING.md

Use this command to stage specific files for your next commit.

```bash
git add <files to be comitted>
```

--------------------------------

### Configure Jest to use all matchers via package.json

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/getting-started/setup.md

To automatically extend `expect` with all matchers, configure `setupFilesAfterEnv` in `package.json` to point to `jest-extended/all`.

```json
"jest": {
  "setupFilesAfterEnv": ["jest-extended/all"]
}
```

--------------------------------

### Check if a value is a Symbol

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/symbol.mdx

Use `.toBeSymbol()` to assert that the received value is a Symbol. This matcher does not require any specific setup or imports beyond Jest Extended itself.

```javascript
test('passes when value is a symbol', () => {
  expect(Symbol()).toBeSymbol();
  expect(true).not.toBeSymbol();
});
```

--------------------------------

### Deploy Website without SSH

Source: https://github.com/jest-community/jest-extended/blob/main/website/README.md

Build and deploy the website without SSH. Requires specifying the GitHub username.

```bash
$ GIT_USER=<Your GitHub username> yarn deploy
```

--------------------------------

### Check if date is within a date range

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/date.mdx

Use `.toBeBetween` to assert that a date falls within a specified range, inclusive of the start and end dates. Non-Date inputs will not pass.

```javascript
test('passes when input is in given date range', () => {
 expect(new Date('05/01/2019')).toBeBetween(new Date('01/01/2019'), new Date('10/01/2019'));
 expect(new Date('05/01/2019')).toBeBetween(new Date('05/01/2019'), new Date('10/01/2019'));
 expect(new Date('01/01/2019')).not.toBeBetween(new Date('05/01/2019'), new Date('10/01/2019'));
});
```

--------------------------------

### Configure ESLint Plugins

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/getting-started/eslint.md

Add 'jest-extended' to the plugins array in your .eslintrc configuration file. The 'eslint-plugin-' prefix can be omitted.

```json
{
  "plugins": ["jest-extended"]
}
```

--------------------------------

### Matcher API - .toBeNil()

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/toBeNil.mdx

The `.toBeNil()` matcher checks if a value is strictly `null` or `undefined`.

```APIDOC
## .toBeNil()

### Description
Use `.toBeNil` when checking a value is `null` or `undefined`.

### Method
`expect(value).toBeNil()`

### Parameters
None

### Request Example
```javascript
test('passes when value is null or undefined', () => {
  expect(null).toBeNil();
  expect(undefined).toBeNil();
  expect(true).not.toBeNil();
});
```

### Response
#### Success Response (200)
- `true` if the value is `null` or `undefined`.

#### Response Example
```json
{
  "pass": true
}
```
```

--------------------------------

### String Matchers

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/index.md

A collection of custom matchers for asserting properties of strings.

```APIDOC
## .toBeString()

### Description
Asserts that the received value is a string.

### Method
`expect(value).toBeString()`

### Endpoint
N/A (Jest Matcher)

### Parameters
None

### Request Example
```javascript
expect('hello').toBeString();
```

### Response
#### Success Response (200)
Passes if the value is a string.

#### Response Example
N/A (Assertion Result)
```

```APIDOC
## .toBeHexadecimal(string)

### Description
Asserts that the received value is a hexadecimal string.

### Method
`expect(value).toBeHexadecimal()`

### Endpoint
N/A (Jest Matcher)

### Parameters
None

### Request Example
```javascript
expect('0xabc123').toBeHexadecimal();
```

### Response
#### Success Response (200)
Passes if the value is a hexadecimal string.

#### Response Example
N/A (Assertion Result)
```

```APIDOC
## .toBeDateString(string)

### Description
Asserts that the received value is a valid date string.

### Method
`expect(value).toBeDateString()`

### Endpoint
N/A (Jest Matcher)

### Parameters
None

### Request Example
```javascript
expect('2023-10-27').toBeDateString();
```

### Response
#### Success Response (200)
Passes if the value is a valid date string.

#### Response Example
N/A (Assertion Result)
```

```APIDOC
## .toEqualCaseInsensitive(string)

### Description
Asserts that the received value is equal to the expected string, ignoring case.

### Method
`expect(value).toEqualCaseInsensitive(expected)`

### Endpoint
N/A (Jest Matcher)

### Parameters
- **expected** (string) - Required - The string to compare against.

### Request Example
```javascript
expect('Hello').toEqualCaseInsensitive('hello');
```

### Response
#### Success Response (200)
Passes if the values are equal ignoring case.

#### Response Example
N/A (Assertion Result)
```

```APIDOC
## .toStartWith(prefix)

### Description
Asserts that the received string starts with the given prefix.

### Method
`expect(value).toStartWith(prefix)`

### Endpoint
N/A (Jest Matcher)

### Parameters
- **prefix** (string) - Required - The prefix to check for.

### Request Example
```javascript
expect('hello world').toStartWith('hello');
```

### Response
#### Success Response (200)
Passes if the string starts with the prefix.

#### Response Example
N/A (Assertion Result)
```

```APIDOC
## .toEndWith(suffix)

### Description
Asserts that the received string ends with the given suffix.

### Method
`expect(value).toEndWith(suffix)`

### Endpoint
N/A (Jest Matcher)

### Parameters
- **suffix** (string) - Required - The suffix to check for.

### Request Example
```javascript
expect('hello world').toEndWith('world');
```

### Response
#### Success Response (200)
Passes if the string ends with the suffix.

#### Response Example
N/A (Assertion Result)
```

```APIDOC
## .toInclude(substring)

### Description
Asserts that the received string includes the given substring.

### Method
`expect(value).toInclude(substring)`

### Endpoint
N/A (Jest Matcher)

### Parameters
- **substring** (string) - Required - The substring to check for.

### Request Example
```javascript
expect('hello world').toInclude('world');
```

### Response
#### Success Response (200)
Passes if the string includes the substring.

#### Response Example
N/A (Assertion Result)
```

```APIDOC
## .toIncludeRepeated(substring, times)

### Description
Asserts that the received string includes the given substring repeated a specific number of times.

### Method
`expect(value).toIncludeRepeated(substring, times)`

### Endpoint
N/A (Jest Matcher)

### Parameters
- **substring** (string) - Required - The substring to check for.
- **times** (number) - Required - The number of times the substring should be repeated.

### Request Example
```javascript
expect('ababab').toIncludeRepeated('ab', 3);
```

### Response
#### Success Response (200)
Passes if the string includes the substring repeated the specified number of times.

#### Response Example
N/A (Assertion Result)
```

```APIDOC
## .toIncludeMultiple([substring])

### Description
Asserts that the received string includes all of the given substrings.

### Method
`expect(value).toIncludeMultiple(substrings)`

### Endpoint
N/A (Jest Matcher)

### Parameters
- **substrings** (array of strings) - Required - The substrings to check for.

### Request Example
```javascript
expect('hello world').toIncludeMultiple(['hello', 'world']);
```

### Response
#### Success Response (200)
Passes if the string includes all the specified substrings.

#### Response Example
N/A (Assertion Result)
```

```APIDOC
## .toEqualIgnoringWhitespace(string)

### Description
Asserts that the received string is equal to the expected string, ignoring whitespace.

### Method
`expect(value).toEqualIgnoringWhitespace(expected)`

### Endpoint
N/A (Jest Matcher)

### Parameters
- **expected** (string) - Required - The string to compare against.

### Request Example
```javascript
expect('hello world').toEqualIgnoringWhitespace('  hello   world  ');
```

### Response
#### Success Response (200)
Passes if the values are equal ignoring whitespace.

#### Response Example
N/A (Assertion Result)
```

--------------------------------

### toBeTrue()

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/boolean.mdx

Use `.toBeTrue` when checking a value is equal (`===`) to `true`.

```APIDOC
## .toBeTrue()

### Description
Use `.toBeTrue` when checking a value is equal (`===`) to `true`.

### Method
`expect(value).toBeTrue()`

### Parameters
None

### Request Example
```json
{
  "example": "const isJestCool = () => true;\nexpect(isJestCool()).toBeTrue();"
}
```

### Response
#### Success Response (200)
Boolean: `true` if the value is strictly equal to `true`, `false` otherwise.

#### Response Example
```json
{
  "example": "true"
}
```
```

--------------------------------

### Use .toBeFinite() for finite numbers and BigInts

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/number.mdx

Use `.toBeFinite` to check if a value is a finite `Number` or a `BigInt`. It excludes `NaN` and `Infinity`.

```javascript
test('passes when value is a finite number or bigint', () => {
  expect(1).toBeFinite();
  expect(BigInt(123456789)).toBeFinite();
  expect(Infinity).not.toBeFinite();
  expect(NaN).not.toBeFinite();
});
```

--------------------------------

### Check for Empty String, Array, and Object

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/toBeEmpty.mdx

Use .toBeEmpty() to assert that a string, array, or object is empty. Use .not.toBeEmpty() to assert that it is not empty. This matcher works with various data types including strings, arrays, and objects.

```javascript
test('passes when given an empty string', () => {
  expect('').toBeEmpty();
  expect('hello').not.toBeEmpty();
});

test('passes when given an empty array', () => {
  expect([]).toBeEmpty();
  expect(['hello']).not.toBeEmpty();
});

test('passes when given an empty object', () => {
  expect({}).toBeEmpty();
  expect({ hello: 'world' }).not.toBeEmpty();
});
```

--------------------------------

### Check Promise Rejection with .toReject()

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/promise.mdx

Use `.toReject` to assert that a promise is rejected. Ensure the promise is awaited before the assertion.

```javascript
test('passes when a promise rejects', async () => {
  await expect(Promise.reject()).toReject();
});
```

--------------------------------

### toBeBetween(startDate, endDate)

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/date.mdx

Checks if a date equals or occurs after startDate and equals or occurs before endDate.

```APIDOC
## .toBeBetween(startDate, endDate)

### Description
Use `.toBeBetween` when checking if a date equals or occurs after `startDate` and equals or occurs before `endDate`.

### Method
`expect(date).toBeBetween(startDate, endDate)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
expect(new Date('05/01/2019')).toBeBetween(new Date('01/01/2019'), new Date('10/01/2019'));
expect(new Date('05/01/2019')).toBeBetween(new Date('05/01/2019'), new Date('10/01/2019'));
expect(new Date('01/01/2019')).not.toBeBetween(new Date('05/01/2019'), new Date('10/01/2019'));
```

### Response
#### Success Response (200)
None (assertion result)

#### Response Example
None
```

--------------------------------

### Check state mutation by a specific amount with .toChangeBy()

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/function.mdx

Use `.toChangeBy` to assert that a callback function mutates a state by a precise amount. The `by` argument specifies the expected difference.

```javascript
test('passes when given a value that the mutator decrements', () => {
  let value = 1;
  expect(() => value--).toChangeBy(() => value, -1);
});
```

--------------------------------

### Use .toBeNil() to check for null or undefined

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/toBeNil.mdx

Use this matcher when you need to assert that a value is strictly null or undefined. It simplifies tests by covering both cases with a single matcher.

```javascript
test('passes when value is null or undefined', () => {
  expect(null).toBeNil();
  expect(undefined).toBeNil();
  expect(true).not.toBeNil();
});
```

--------------------------------

### Check state mutation to a specific value with .toChangeTo()

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/function.mdx

Use `.toChangeTo` to confirm that a callback function mutates a state to a specific target value. The `to` argument is the expected final value.

```javascript
test('passes when the value being checked becomes the provided value', () => {
  let value = 1;
  expect(() => value = 10).toChangeTo(() => value, 10);
});
```

--------------------------------

### Use .fail() to Assert Failure

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/fail.mdx

Use the .fail() assertion when you expect a test to fail. This is useful for testing error conditions or expected failures.

```javascript
test('fail', () => {
  expect().fail('test should fail');
});
```

--------------------------------

### toBeExtensible

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/object.mdx

Checks if an object is extensible (i.e., new properties can be added to it).

```APIDOC
## .toBeExtensible()

### Description
Use `.toBeExtensible` when checking if an object is extensible.

### Method
Custom Matcher

### Endpoint
N/A (Jest Matcher)

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **boolean** - true if the object is extensible.

#### Response Example
```json
{
  "result": true
}
```
```

--------------------------------

### toChangeBy(checker, by)

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/function.mdx

Checks if a callback function mutates a piece of state by a specific amount.

```APIDOC
## .toChangeBy(checker, by)

### Description
Use `.toChangeBy` when checking if the callback function mutates a piece of state by a specific amount.

### Method
`expect(callback).toChangeBy(checker, by)`

### Parameters
#### Query Parameters
- **checker** (Function) - A function that queries the state to be checked.
- **by** (Number) - The expected change in the state.

### Request Example
```json
{
  "example": "expect(() => value--).toChangeBy(() => value, -1)"
}
```

### Response
#### Success Response (200)
- **callback** (Function) - The function that is expected to mutate the state.
- **checker** (Function) - The function used to check the state before and after the mutation.
- **by** (Number) - The expected amount of change.

#### Response Example
```json
{
  "example": "expect(() => value--).toChangeBy(() => value, -1)"
}
```
```

--------------------------------

### Check state mutation with .toChange()

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/function.mdx

Use `.toChange` to verify that a callback function modifies a state, which is then checked by a provided checker function. Ensure the checker accurately reflects the state change.

```javascript
test('passes when given a value that the mutator increments', () => {
  let value = 0;
  expect(() => value++).toChange(() => value);
});
```

--------------------------------

### Use .toBePositive() for positive numbers and BigInts

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/number.mdx

Use `.toBePositive` to verify if a value is a positive `Number` or `BigInt`. It excludes negative values, zero, `NaN`, and `Infinity`.

```javascript
test('passes when value is a positive number or bigint', () => {
  expect(1).toBePositive();
  expect(BigInt(42)).toBePositive();
  expect(Infinity).not.toBePositive();
  expect(-1).not.toBePositive();
  expect(-BigInt(42)).not.toBePositive();
  expect(NaN).not.toBePositive();
});
```

--------------------------------

### toBeBefore(date)

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/date.mdx

Checks if a date occurs before a specified date.

```APIDOC
## .toBeBefore(date)

### Description
Use `.toBeBefore` when checking if a date occurs before `date`.

### Method
`expect(date).toBeBefore(expectedDate)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
expect(new Date('01/01/2018')).toBeBefore(new Date('01/01/2019'));
expect('01/01/2019').not.toBeBefore(new Date('01/01/2018'));
```

### Response
#### Success Response (200)
None (assertion result)

#### Response Example
None
```

--------------------------------

### Use .toBeEven() for even numbers and BigInts

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/number.mdx

Use `.toBeEven` to determine if a value is an even `Number` or `BigInt`. It excludes odd numbers, `NaN`, and non-integer values.

```javascript
test('passes when value is an even number or bigint', () => {
  expect(2).toBeEven();
  expect(BigInt(2)).toBeEven();
  expect(BigInt(-4)).toBeEven();
  expect(1).not.toBeEven();
  expect(BigInt(1)).not.toBeEven();
  expect(NaN).not.toBeEven();
});
```

--------------------------------

### Use .toSatisfyAll() with a predicate function

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/array.mdx

Use `.toSatisfyAll` when you want to use a custom matcher by supplying a predicate function that returns a `Boolean` for all values in an array. It asserts that every element in the array satisfies the condition.

```javascript
test('passes when all values in array pass given predicate', () => {
  const isOdd = el => el % 2 === 1;
  expect([1, 3, 5, 7]).toSatisfyAll(isOdd);
  expect([1, 3, 4, 5, 7]).not.toSatisfyAll(isOdd);
});
```

--------------------------------

### Check if an object is empty

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/object.mdx

Use `.toBeEmptyObject` to assert that a value is an empty object. Ensure the value is strictly an object.

```javascript
test('passes when value is an empty object', () => {
  expect({}).toBeEmptyObject();
  expect({ a: 'hello' }).not.toBeEmptyObject();
});
```

--------------------------------

### toBeAfter(date)

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/date.mdx

Checks if a date occurs after a specified date.

```APIDOC
## .toBeAfter(date)

### Description
Use `.toBeAfter` when checking if a date occurs after `date`.

### Method
`expect(date).toBeAfter(expectedDate)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
expect(new Date('01/01/2019')).toBeAfter(new Date('01/01/2018'));
expect('01/01/2018').not.toBeAfter(new Date('01/01/2019'));
```

### Response
#### Success Response (200)
None (assertion result)

#### Response Example
None
```

--------------------------------

### toChangeTo(checker, to)

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/function.mdx

Checks if a callback function mutates a piece of state to a target value.

```APIDOC
## .toChangeTo(checker, to)

### Description
Use `.toChangeTo` when checking if the callback function mutates a piece of state to a target value.

### Method
`expect(callback).toChangeTo(checker, to)`

### Parameters
#### Query Parameters
- **checker** (Function) - A function that queries the state to be checked.
- **to** (any) - The target value the state should change to.

### Request Example
```json
{
  "example": "expect(() => value = 10).toChangeTo(() => value, 10)"
}
```

### Response
#### Success Response (200)
- **callback** (Function) - The function that is expected to mutate the state.
- **checker** (Function) - The function used to check the state before and after the mutation.
- **to** (any) - The target value.

#### Response Example
```json
{
  "example": "expect(() => value = 10).toChangeTo(() => value, 10)"
}
```
```

--------------------------------

### toBeFalse()

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/boolean.mdx

Use `.toBeFalse` when checking a value is equal (`===`) to `false`.

```APIDOC
## .toBeFalse()

### Description
Use `.toBeFalse` when checking a value is equal (`===`) to `false`.

### Method
`expect(value).toBeFalse()`

### Parameters
None

### Request Example
```json
{
  "example": "const areWeThereYet = () => false;\nexpect(areWeThereYet()).toBeFalse();"
}
```

### Response
#### Success Response (200)
Boolean: `true` if the value is strictly equal to `false`, `false` otherwise.

#### Response Example
```json
{
  "example": "true"
}
```
```

--------------------------------

### Configure ESLint Rules for Jest Extended

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/getting-started/eslint.md

Specify the desired linting rules from 'jest-extended' and their severity levels within the 'rules' section of your .eslintrc configuration.

```json
{
  "rules": {
    "jest-extended/prefer-to-be-true": "warn",
    "jest-extended/prefer-to-be-false": "error"
  }
}
```

--------------------------------

### Alternative TypeScript Import Syntax

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/getting-started/typescript.md

If the standard import syntax does not work, use this alternative reference type declaration to include jest-extended types in your TypeScript project.

```typescript
/// <reference types="jest-extended" />
```

--------------------------------

### Use .toIncludeAllMembers() to check for all members

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/array.mdx

Use `.toIncludeAllMembers` when checking if an `Array` contains all of the same members of a given set. The order of members does not matter.

```javascript
test('passes when given array values match the members of the set', () => {
  expect([1, 2, 3]).toIncludeAllMembers([2, 1, 3]);
  expect([1, 2, 2]).toIncludeAllMembers([2, 1]);
});
```

--------------------------------

### Use .toIncludeSamePartialMembers() for exact partial member matches

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/array.mdx

Use `.toIncludeSamePartialMembers` when checking if an `Array` contains exactly the same partial members as a given set, in any order. It verifies that all specified partial properties exist and match.

```javascript
test('passes when given array values match the partial members of the set', () => {
  expect([{ foo: 'bar', baz: 'qux' }, { property: 'hello', another: 'world' }]).toIncludeSamePartialMembers([{ foo: 'bar' },  { property: 'hello' }]);
});
```

--------------------------------

### toBeEmpty() Matcher

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/toBeEmpty.mdx

Use .toBeEmpty() to assert that a value is an empty string, array, object, or iterable.

```APIDOC
## .toBeEmpty()

### Description
Use `.toBeEmpty` when checking if a `String` `''`, `Array` `[]`, `Object` `{}`, or [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#Built-in_iterables) is empty. Because `toBeEmpty` supports checking for emptiness of Iterables, you can use it to check whether a `Map`, or `Set` is empty, as well as checking that a generator yields no values.

### Method
`expect(value).toBeEmpty()`
`expect(value).not.toBeEmpty()`

### Parameters
None

### Request Example
```javascript
test('passes when given an empty string', () => {
  expect('').toBeEmpty();
  expect('hello').not.toBeEmpty();
});

test('passes when given an empty array', () => {
  expect([]).toBeEmpty();
  expect(['hello']).not.toBeEmpty();
});

test('passes when given an empty object', () => {
  expect({}).toBeEmpty();
  expect({ hello: 'world' }).not.toBeEmpty();
});
```

### Response
None (This is a matcher, not an API endpoint)

### Error Handling
None (This is a matcher, not an API endpoint)
```

--------------------------------

### toBeBeforeOrEqualTo(date)

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/date.mdx

Checks if a date equals to or occurs before a specified date.

```APIDOC
## .toBeBeforeOrEqualTo(date)

### Description
Use `.toBeBeforeOrEqualTo` when checking if a date equals to or occurs before `date`.

### Method
`expect(date).toBeBeforeOrEqualTo(expectedDate)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
expect(new Date('01/01/2018')).toBeBeforeOrEqualTo(new Date('01/01/2019'));
expect(new Date('01/01/2018')).toBeBeforeOrEqualTo(new Date('01/01/2018'));
expect('01/01/2019').not.toBeBeforeOrEqualTo(new Date('01/01/2018'));
```

### Response
#### Success Response (200)
None (assertion result)

#### Response Example
None
```

--------------------------------

### toHaveBeenCalledExactlyOnceWith

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/mock.mdx

Checks if a mock function was called exactly one time and with the expected arguments.

```APIDOC
## .toHaveBeenCalledExactlyOnceWith()

### Description
Use `.toHaveBeenCalledExactlyOnceWith` to check if a `Mock` was called exactly one time and with the expected values.

### Method
`expect(mock).toHaveBeenCalledExactlyOnceWith(arg1, arg2, ...)`

### Parameters
#### Arguments
- **arg1, arg2, ...** (any) - The arguments to check against.

### Request Example
```javascript
test('passes only if mock was called exactly once with the expected value', () => {
  const mock = jest.fn();

  expect(mock).not.toHaveBeenCalled();
  mock('hello');
  expect(mock).toHaveBeenCalledExactlyOnceWith('hello');
});
```

### Response
#### Success Response (200)
- **true** (boolean) - Returns true if the mock was called exactly once with the specified arguments.

#### Response Example
```json
{
  "toHaveBeenCalledExactlyOnceWith": true
}
```
```

--------------------------------

### Check Mock Called Exactly Once With Specific Arguments

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/mock.mdx

Use `.toHaveBeenCalledExactlyOnceWith` to confirm that a mock function was called exactly one time and with the specified arguments. This provides a precise check on both call count and parameters.

```javascript
test('passes only if mock was called exactly once with the expected value', () => {
  const mock = jest.fn();

  expect(mock).not.toHaveBeenCalled();
  mock('hello');
  expect(mock).toHaveBeenCalledExactlyOnceWith('hello');
});
```

--------------------------------

### Symbol Matchers

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/index.md

Custom matchers for asserting properties of symbols.

```APIDOC
## .toBeSymbol()

### Description
Asserts that the received value is a symbol.

### Method
`expect(value).toBeSymbol()`

### Endpoint
N/A (Jest Matcher)

### Parameters
None

### Request Example
```javascript
const sym = Symbol('test');
expect(sym).toBeSymbol();
```

### Response
#### Success Response (200)
Passes if the value is a symbol.

#### Response Example
N/A (Assertion Result)
```

--------------------------------

### toHaveBeenCalledOnce

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/mock.mdx

Checks if a mock function was called exactly one time.

```APIDOC
## .toHaveBeenCalledOnce()

### Description
Use `.toHaveBeenCalledOnce` to check if a `Mock` was called exactly one time.

### Method
`expect(mock).toHaveBeenCalledOnce()`

### Request Example
```javascript
test('passes only if mock was called exactly once', () => {
  const mock = jest.fn();

  expect(mock).not.toHaveBeenCalled();
  mock();
  expect(mock).toHaveBeenCalledOnce();
});
```

### Response
#### Success Response (200)
- **true** (boolean) - Returns true if the mock was called exactly once.

#### Response Example
```json
{
  "toHaveBeenCalledOnce": true
}
```
```

--------------------------------

### toBeAfterOrEqualTo(date)

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/date.mdx

Checks if a date equals to or occurs after a specified date.

```APIDOC
## .toBeAfterOrEqualTo(date)

### Description
Use `.toBeAfterOrEqualTo` when checking if a date equals to or occurs after `date`.

### Method
`expect(date).toBeAfterOrEqualTo(expectedDate)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
expect(new Date('01/01/2019')).toBeAfterOrEqualTo(new Date('01/01/2018'));
expect(new Date('01/01/2019')).toBeAfterOrEqualTo(new Date('01/01/2019'));
expect('01/01/2018').not.toBeAfterOrEqualTo(new Date('01/01/2019'));
```

### Response
#### Success Response (200)
None (assertion result)

#### Response Example
None
```

--------------------------------

### toChangeTo

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/number.mdx

Checks if a function call changes a value to a specified value.

```APIDOC
## .toChangeTo()

### Description
Use `.toChangeTo` when checking if a function call changes a value to a specified value.

### Method
`expect(callback).toChangeTo(getter, value)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "expect(() => { value = 2 }).toChangeTo(() => value, 2)"
}
```

### Response
#### Success Response (200)
- **callback** (Function) - The function that is expected to change the value.
- **getter** (Function) - A function that returns the value to be checked.
- **value** (any) - The expected final value.

#### Response Example
```json
{
  "example": "expect(() => { value = 2 }).toChangeTo(() => value, 2)"
}
```
```

--------------------------------

### toBeFinite

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/number.mdx

Checks if a value is a finite Number or BigInt, excluding NaN and Infinity.

```APIDOC
## .toBeFinite()

### Description
Use `.toBeFinite` when checking if a value is a `Number`, not `NaN` or `Infinity`, or a `BigInt`.

### Method
`expect(value).toBeFinite()`

### Parameters
None

### Request Example
```json
{
  "example": "expect(1).toBeFinite()"
}
```

### Response
#### Success Response (200)
- **value** (Number | BigInt) - The value being tested.

#### Response Example
```json
{
  "example": "expect(1).toBeFinite()"
}
```
```

--------------------------------

### Object is extensible

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/object.mdx

Use `.toBeExtensible` to assert that an object can have new properties added to it. Primitive values will not pass this check.

```javascript
test('passes when value is extensible', () => {
  expect({ a: 1 }).toBeExtensible();
  expect(1).not.toBeExtensible();
});
```

--------------------------------

### Check Promise Resolution with .toResolve()

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/promise.mdx

Use `.toResolve` to assert that a promise successfully resolves. Ensure the promise is awaited before the assertion.

```javascript
test('passes when a promise resolves', async () => {
  await expect(Promise.resolve()).toResolve();
});
```

--------------------------------

### Check Mock Called Exactly Once

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/mock.mdx

Use `.toHaveBeenCalledOnce` to verify that a mock function has been invoked precisely one time. This is useful for ensuring a function executes only a single occurrence.

```javascript
test('passes only if mock was called exactly once', () => {
  const mock = jest.fn();

  expect(mock).not.toHaveBeenCalled();
  mock();
  expect(mock).toHaveBeenCalledOnce();
});
```

--------------------------------

### toBeFrozen

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/object.mdx

Checks if an object is frozen (i.e., it cannot be modified, its properties cannot be changed, and its prototype cannot be changed).

```APIDOC
## .toBeFrozen()

### Description
Use `.toBeFrozen` when checking if an object is frozen.

### Method
Custom Matcher

### Endpoint
N/A (Jest Matcher)

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **boolean** - true if the object is frozen.

#### Response Example
```json
{
  "result": true
}
```
```

--------------------------------

### Use .toChangeTo() for specific value change assertions

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/number.mdx

Use `.toChangeTo` to assert that a function call changes a value to a specific target value. Supports `BigInt` values.

```javascript
test('passes when value changes to the specified value', () => {
  let value = 0;
  let bigValue = BigInt(0);
  expect(() => { value = 2 }).toChangeTo(() => value, 2);
  expect(() => { bigValue = 42n }).toChangeTo(() => bigValue, 42n);
  expect(() => { value = 3 }).not.toChangeTo(() => value, 2);
});
```

--------------------------------

### Check if an object contains all specified key-value pairs

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/object.mdx

Use `.toContainEntries` to assert that an object includes all the provided entries, where each entry is a [key, value] pair. The order of entries does not matter.

```javascript
test('passes when object contains all of the given entries', () => {
  const o = { a: 'foo', b: 'bar', c: 'baz' };
  expect(o).toContainEntries([['a', 'foo']]);
  expect(o).toContainEntries([
    ['c', 'baz'],
    ['a', 'foo'],
  ]);
  expect(o).not.toContainEntries([
    ['b', 'qux'],
    ['a', 'foo'],
  ]);
});
```

--------------------------------

### Use .toIncludeAllPartialMembers() for partial member checks

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/array.mdx

Use `.toIncludeAllPartialMembers` when checking if an `Array` contains all of the same partial members of a given set. This is useful for checking object properties.

```javascript
test('passes when given array values match the partial members of the set', () => {
  expect([{ foo: 'bar', baz: 'qux' }]).toIncludeAllPartialMembers([{ foo: 'bar' }]);
});
```

--------------------------------

### Configure tsconfig.json for Type Declarations

Source: https://github.com/jest-community/jest-extended/blob/main/examples/typescript/all/README.md

Include 'node_modules/jest-extended/types/index.d.ts' in the 'files' property of your tsconfig.json to ensure Typescript recognizes jest-extended types.

```json
{
  "compilerOptions": {
    // ... other options
  },
  "files": [
    "node_modules/jest-extended/types/index.d.ts"
  ]
}
```

--------------------------------

### Use .toBeNegative() for negative numbers and BigInts

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/number.mdx

Use `.toBeNegative` to check if a value is a negative `Number` or `BigInt`. It excludes positive values, zero, `NaN`, and `-Infinity`.

```javascript
test('passes when value is a negative number or bigint', () => {
  expect(-1).toBeNegative();
  expect(BigInt(-123)).toBeNegative();
  expect(-Infinity).not.toBeNegative();
  expect(1).not.toBeNegative();
  expect(BigInt(123)).not.toBeNegative();
  expect(NaN).not.toBeNegative();
});
```

--------------------------------

### toChange()

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/function.mdx

Checks if a callback function mutates a piece of state queried by a checker function.

```APIDOC
## .toChange(checker)

### Description
Use `.toChange` when checking if the callback function mutates a piece of state that is queried by the checker function.

### Method
`expect(callback).toChange(checker)`

### Parameters
#### Query Parameters
- **checker** (Function) - A function that queries the state to be checked.

### Request Example
```json
{
  "example": "expect(() => value++).toChange(() => value)"
}
```

### Response
#### Success Response (200)
- **callback** (Function) - The function that is expected to mutate the state.
- **checker** (Function) - The function used to check the state before and after the mutation.

#### Response Example
```json
{
  "example": "expect(() => value++).toChange(() => value)"
}
```
```

--------------------------------

### fail() - Failing Assertion

Source: https://github.com/jest-community/jest-extended/blob/main/website/docs/matchers/fail.mdx

The `.fail()` matcher is used to explicitly fail a test case. It accepts an optional message that will be displayed when the test fails.

```APIDOC
## .fail(message)

### Description
Failing assertion.

### Method
`expect().fail()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
test('fail', () => {
  expect().fail('test should fail');
});
```

### Response
#### Success Response (200)
This matcher does not have a success response as its purpose is to fail the test.

#### Response Example
None
```