API Reference

Validators

`.toBeA<C extends NewableOrPrimitive>(type: C): void`

Asserts that the value is an instance of a provided class or a primitive type. It is compatible with built-in types like strings, numbers, and dates.

If you want to match a nested value, use the matcher expect.a(type) instead.

Parameters:

type - The class or primitive constructor to match against.

Examples:

// Primitives
expect(123).toBeA(Number)
expect('foo').not.toBeA(Boolean)

// Classes
expect(new Person('John', 'Doe')).toBeA(Person)

Matchers

`expect.a<T extends NewableOrPrimitive>(type: T): never`

Matches an instance of a provided class or a primitive type. It is compatible with built-in types like strings, numbers, and dates.

Using this matcher is recommended when you don't care about the exact value as long as it matches a given type.

If you want to match a top level value, use expect(...).toBeA(type) instead.

Parameters:

type - The class or primitive constructor to match against.

Examples:

// Primitives
expect({ foo: Math.random() }).toEqual({ foo: expect.a(Number) })

// Classes
expect({
  employee: new Employee('John Doe', 42),
  birthday: new Date('1990-01-01'),
}).toEqual({
  employee: expect.a(Employee),
  birthday: expect.a(Date),
})

`expect.anything(): never`

Matches any value.

Using this matcher is recommended when you want to ensure that a key is present on an object, but you don't care about its value.

Examples:

const person = findPerson('John Doe')
expect(person).toEqual({
  name: 'John Doe',
  favoriteThing: expect.anything(),
})

`expect.between(min: number | bigint, max: number | bigint): never`

Matches numbers that are between the two numbers. The range is [min, max], inclusive on both sides.

Works for both numbers and bigints.

If you want to match a top level value, use expect(...).toBeBetween(min, max) instead.

Parameters:

min - The minimum value, inclusive.
max - The maximum value, inclusive.

Examples:

const location = getLatLon()
expect(location).toEqual({
  lat: expect.between(-90, 90),
  lon: expect.between(-180, 180),
})

`expect.closeTo(target: number, delta: number): never`

Matches numbers that are close to the target value. The range is [target - delta, target + delta], inclusive on both sides.

Works only for numbers and not for bigints.

If you want to match a top level value, use expect(...).toBeCloseTo(target, delta) instead.

Parameters:

target - The number to aim for.
delta - The maximum difference between the values.

Examples:

const vector = getApproximateStrikeTarget()
expect(vector).toEqual({
  x: expect.closeTo(420, 0.001),
  y: expect.closeTo(69, 0.001),
})

`expect.defined(): never`

Matches values that are not undefined.

If you want to match a top level value, use expect(...).not.toEqual(undefined) instead.

Examples:

const result = await fetchStockPrices('BANANA', 'KIWI')
expect(result).toEqual({
  BANANA: expect.defined(),
  KIWI: expect.defined(),
})

`expect.empty(): never`

Matches empty strings, arrays, sets and maps.

If you want to match a top level value, use expect(...).toBeEmpty() instead.

Examples:

const sadGuy = await people.findWhere({ friendCount: 0 })
expect(sadGuy).toEqual({
  name: 'John Doe',
  friends: expect.empty(),
})

`expect.falsy(): never`

Matches falsy values, as defined by: https://developer.mozilla.org/en-US/docs/Glossary/Falsy

You can also use its sister matcher, truthy, to match the opposite.

If you want to match a top level value, use expect(...).toBeFalsy() instead.

Examples:

const doggy = dogApi.getDog('Waffles')
expect(doggy).toEqual({
  name: 'Waffles',
  // Waffles is a stray, we don't know the date :(
  birthday: expect.falsy(),
})

`expect.greaterThan(target: number | bigint): never`

Matches numbers that are greater than the given target.

Works for both numbers and bigints.

If you want to match a top level value, use expect(...).toBeGreaterThan(target) instead.

Parameters:

target - The target value to compare to.

Examples:

expect({
  salary: 100_000,
  bonus: 10_000,
}).toEqual({
  salary: expect.greaterThan(50_000),
  bonus: expect.greaterThan(5_000),
})

`expect.greaterThanOrEqual(target: number | bigint): never`

Matches numbers that are greater than or equal to the given target.

Works for both numbers and bigints.

If you want to match a top level value, use expect(...).toBeGreaterThanOrEqual(target) instead.

Parameters:

target - The target value to compare to.

Examples:

expect({
  salary: 100_000,
  bonus: 5_000,
}).toEqual({
  salary: expect.greaterThanOrEqual(50_000),
  bonus: expect.greaterThanOrEqual(5_000),
})

`expect.includes(...items: any[]): never`

Matches an array, Set or iterable that includes the given item or items. Also matches a string that includes the given substring or substrings.

If you want to match a top level value, use expect(...).toInclude(...items) instead.

Parameters:

items - Items or matchers to look for. When the value is a string, all items must be strings too.

Examples:

expect({
  numbers: [1, 2, 3],
  mixed: [1, 'foo', false],
  string: 'I like pancakes',
}).toEqual({
  numbers: expect.includes(1, 2),
  mixed: expect.includes(1, expect.a(String)),
  string: expect.includes('pancakes'),
})

`expect.integer(): never`

Matches numbers that are integers.

Works for both numbers and bigints.

If you want to match a top level value, use expect(...).toBeAnInteger() instead.

Examples:

const counts = getParticleCounts()
expect(counts).toEqual({
  min: 0,
  max: expect.integer(),
  median: expect.integer(),
})

`expect.length(length: number): never`

Matches an array, string or any object with a length property that has the given length.

If you want to match a top level value, use expect(...).toHaveLength(length) instead.

Parameters:

length - The expected length. Can be a matcher.

Examples:

expect({
  numbers: [1, 2, 3],
  letters: 'abcdef',
}).toEqual({
  numbers: expect.length(3),
  letters: expect.length(expect.greaterThan(3)),
})

`expect.lessThan(target: number | bigint): never`

Matches numbers that are less than the given target.

Works for both numbers and bigints.

If you want to match a top level value, use expect(...).toBeLessThan(target) instead.

Parameters:

target - The target value to compare to.

Examples:

expect({
  salary: 100_000,
  bonus: 10_000,
}).toEqual({
  salary: expect.lessThan(200_000),
  bonus: expect.lessThan(20_000),
})

`expect.lessThanOrEqual(target: number | bigint): never`

Matches numbers that are less than or equal to the given target.

Works for both numbers and bigints.

If you want to match a top level value, use expect(...).toBeLessThanOrEqual(target) instead.

Parameters:

target - The target value to compare to.

Examples:

expect({
  salary: 100_000,
  bonus: 20_000,
}).toEqual({
  salary: expect.lessThanOrEqual(200_000),
  bonus: expect.lessThanOrEqual(20_000),
})

`expect.notEmpty(): never`

Matches strings, arrays, sets and maps that aren't empty.

If you want to match a top level value, use expect(...).not.toBeEmpty() instead.

Examples:

const happyGuy = await people.findWhere({ friendCount: 42 })
expect(happyGuy).toEqual({
  name: 'John Doe',
  friends: expect.notEmpty(),
})

`expect.notNullish(): never`

Matches values that are not nullish, i.e. values that are not null or undefined.

If you want to match a top level value, use expect(...).not.toBeNullish() instead.

Examples:

const result = await fetchStockPrices('BANANA', 'KIWI')
expect(result).toEqual({
  BANANA: expect.notNullish(),
  KIWI: expect.notNullish(),
})

`expect.nullish(): never`

Matches null and undefined.

If you want to match a top level value, use expect(...).toBeNullish() instead.

Examples:

const result = await flight.getPassenger('17A')
expect(result).toEqual({
  name: 'John Doe',
  seat: '17A',
  insurancePolicy: expect.nullish(),
})

`expect.property(key: string, value?: unknown): never`

Matches objects for which a given key exists. Optionally checks the property value.

Parameters:

key - The expected property key.
value - (optional) The expected property value.

Examples:

const events = await getLatestEvents({ limit: 3 })
expect(events).toEqual([
  expect.property('pending', true),
  expect.property('finalizedAt'),
  expect.property('finalizedAt'),
])

`expect.regex(regex: RegExp): never`

Matches strings that match the given regular expression.

If you want to match a top level value, use expect(...).toMatchRegex(regex) instead.

Parameters:

regex - The regular expression to test the matched values.

Examples:

const contact = await customer.getUSContactInfo()
expect(contact).toEqual({
  state: expect.regex(/^[A-Z]{2}$/),
  zipCode: expect.regex(/^\d{5}$/),
  phoneNumber: expect.regex(/^\d{3}-\d{3}-\d{4}$/),
})

`expect.safeInteger(): never`

Matches numbers that are integers between Number.MIN_SAFE_INTEGER nad Number.MAX_SAFE_INTEGER.

Works for both numbers and bigints.

If you want to match a top level value, use expect(...).toBeASafeInteger() instead.

Examples:

const counts = getExperimentStats()
expect(counts).toEqual({
  min: 0,
  max: expect.safeInteger(),
  median: expect.safeInteger(),
})

`expect.satisfies(predicate: (value: unknown) => boolean): never`

Matches values for which the predicate returns a truthy value.

Usually other matchers are more appropriate, but this can be useful if you are testing something custom.

If you want to match a top level value, use expect(...).toSatisfy(predicate) instead.

Parameters:

predicate - The function for checking values.

Examples:

function isShark(value: unknown) {
  return value instanceof Fish && value.species === 'shark'
}
expect(crazyZoologist).toEqual({
  name: 'John Doe',
  pet: expect.satisfies(isShark),
})

`expect.schema(schema: ZodSchema): never`

Matches values conforming to the provided zod schema.

If you want to match a top level value, use expect(...).toMatchSchema(schema) instead.

Parameters:

schema - The zod schema to use.

Examples:

import * as z from 'zod'
const product = await getLatestProduct()
expect(product).toEqual({
  name: 'Turbocharger 9000',
  uuid: expect.schema(z.string().uuid()),
  pricing: expect.schema(
    z.object({
      price: z.number().positive(),
      currency: z.string().length(3),
    }),
  ),
})

`expect.subset(subset: object): never`

Matches an object containing the given key value pairs.

Parameters:

subset - The key value paris to match against.

Examples:

const response = await api.get('/users/me')
expect(response).toEqual({
  success: true,
  data: expect.subset({
    name: 'John Doe',
    age: 42,
  }),
})

`expect.truthy(): never`

Matches truthy values, as defined by: https://developer.mozilla.org/en-US/docs/Glossary/Truthy

You can also use its sister matcher, falsy, to match the opposite.

If you want to match a top level value, use expect(...).toBeTruthy() instead.

Examples:

const kitty = catApi.getCat('Peanut')
expect(kitty).toEqual({
  name: 'Peanut',
  // they are a happy family, but we don't care about the details
  mom: expect.truthy(),
  dad: expect.truthy(),
})

Mocks

`function mockFn<F extends (...args: any) => any>(defaultImplementation?: F): MockFunctionOf<F>`

Creates a mock function conforming to a given signature. You can call methods on the mock function to further customize its behavior.

Without a default implementation and without any further configuration the mock will throw an error when called.

Parameters:

defaultImplementation - (optional) A default implementation to use when the mock is called.

Examples:

const mock1 = mockFn((a: number, b: string) => a + b.length)

const mock2 = mockFn<(a: number, b: string) => number>()
const mock3 = mockFn<[number, string], number>()

const mock4 = mockFn().returnsOnce(420).returns(69)

API Reference #

Validators #

.toBeA<C extends NewableOrPrimitive>(type: C): void #

Matchers #

expect.a<T extends NewableOrPrimitive>(type: T): never #

expect.anything(): never #

expect.between(min: number | bigint, max: number | bigint): never #

expect.closeTo(target: number, delta: number): never #

expect.defined(): never #

expect.empty(): never #

expect.falsy(): never #

expect.greaterThan(target: number | bigint): never #

expect.greaterThanOrEqual(target: number | bigint): never #

expect.includes(...items: any[]): never #

expect.integer(): never #

expect.length(length: number): never #

expect.lessThan(target: number | bigint): never #

expect.lessThanOrEqual(target: number | bigint): never #

expect.notEmpty(): never #

expect.notNullish(): never #

expect.nullish(): never #

expect.property(key: string, value?: unknown): never #

expect.regex(regex: RegExp): never #

expect.safeInteger(): never #

expect.satisfies(predicate: (value: unknown) => boolean): never #

expect.schema(schema: ZodSchema): never #

expect.subset(subset: object): never #

expect.truthy(): never #

Mocks #

function mockFn<F extends (...args: any) => any>(defaultImplementation?: F): MockFunctionOf<F> #

API Reference

Validators

`.toBeA<C extends NewableOrPrimitive>(type: C): void`

Matchers

`expect.a<T extends NewableOrPrimitive>(type: T): never`

`expect.anything(): never`

`expect.between(min: number | bigint, max: number | bigint): never`

`expect.closeTo(target: number, delta: number): never`

`expect.defined(): never`

`expect.empty(): never`

`expect.falsy(): never`

`expect.greaterThan(target: number | bigint): never`

`expect.greaterThanOrEqual(target: number | bigint): never`

`expect.includes(...items: any[]): never`

`expect.integer(): never`

`expect.length(length: number): never`

`expect.lessThan(target: number | bigint): never`

`expect.lessThanOrEqual(target: number | bigint): never`

`expect.notEmpty(): never`

`expect.notNullish(): never`

`expect.nullish(): never`

`expect.property(key: string, value?: unknown): never`

`expect.regex(regex: RegExp): never`

`expect.safeInteger(): never`

`expect.satisfies(predicate: (value: unknown) => boolean): never`

`expect.schema(schema: ZodSchema): never`

`expect.subset(subset: object): never`

`expect.truthy(): never`

Mocks

`function mockFn<F extends (...args: any) => any>(defaultImplementation?: F): MockFunctionOf<F>`