All Assertions

Primitive Assertions

These are the most basic expectations about the type of a subject.

{unknown} to be a string

Success:

expect('hello, world!', 'to be a string');

Failure:

expect(42, 'to be a string');
// AssertionError: Expected 42 to be a string

Negation:

expect(42, 'not to be a string');

{unknown} to be a boolean

✏️ Aliases:

{unknown} to be a boolean
{unknown} to be a bool
{unknown} to be boolean

Success:

expect(true, 'to be a boolean');
expect(false, 'to be a boolean');

Failure:

expect(0, 'to be a boolean');
// AssertionError: Expected 0 to be a boolean

Negation:

expect(0, 'not to be a boolean');

{unknown} to be a number

✏️ Aliases:

{unknown} to be a number
{unknown} to be finite

The definition of "number" is that of Zod v4's; only finite numbers are considered valid.

Success:

expect(3.14, 'to be a number');
expect(-42, 'to be a number');
expect(0, 'to be a number');

Failure:

expect(NaN, 'to be a number');
// AssertionError: Expected NaN to be a number
expect(Infinity, 'to be a number');

Negation:

expect(NaN, 'not to be a number');
expect(Infinity, 'not to be a number');

{unknown} to be a bigint

Success:

expect(9007199254741991n, 'to be a bigint');

Failure:

expect(42, 'to be a bigint');
// AssertionError: Expected 42 to be a bigint

Negation:

expect(42, 'not to be a bigint');

{unknown} to be a symbol

Success:

expect(Symbol('foo'), 'to be a symbol');

Failure:

expect('foo', 'to be a symbol');
// AssertionError: Expected 'foo' to be a symbol

Negation:

expect('foo', 'not to be a symbol');

{unknown} to be null

Success:

expect(null, 'to be null');

Failure:

expect(undefined, 'to be null');
// AssertionError: Expected undefined to be null

Negation:

expect(undefined, 'not to be null');

{unknown} to be undefined

Success:

expect(undefined, 'to be undefined');

Failure:

expect(null, 'to be undefined');
// AssertionError: Expected null to be undefined

Negation:

expect(null, 'not to be undefined');

{unknown} to be a primitive

Success:

expect('hello', 'to be a primitive');
expect(42, 'to be a primitive');
expect(true, 'to be a primitive');
expect(null, 'to be a primitive');
expect(undefined, 'to be a primitive');
expect(Symbol('test'), 'to be a primitive');
expect(123n, 'to be a primitive');

Failure:

expect({}, 'to be a primitive');
// AssertionError: Expected {} to be a primitive
expect([], 'to be a primitive');

Negation:

expect({}, 'not to be a primitive');
expect([], 'not to be a primitive');

Numeric Assertions

These assertions test numeric values, ranges, and mathematical relationships.

{unknown} to be a number

👉 See to be a number

{unknown} to be infinite

Success:

expect(Infinity, 'to be infinite');
expect(-Infinity, 'to be infinite');

Failure:

expect(42, 'to be infinite');
// AssertionError: Expected 42 to be infinite

Negation:

expect(42, 'not to be infinite');

{unknown} to be Infinity

Success:

expect(Infinity, 'to be Infinity');

Failure:

expect(-Infinity, 'to be Infinity');
// AssertionError: Expected -Infinity to be Infinity

Negation:

expect(-Infinity, 'not to be Infinity');

{unknown} to be -Infinity

Success:

expect(-Infinity, 'to be -Infinity');

Failure:

expect(Infinity, 'to be -Infinity');
// AssertionError: Expected Infinity to be -Infinity

Negation:

expect(Infinity, 'not to be -Infinity');

{unknown} to be positive

✏️ Aliases:

{unknown} to be positive
{unknown} to be a positive number

Success:

expect(42, 'to be positive');
expect(3.14, 'to be positive');

Failure:

expect(-5, 'to be positive');
// AssertionError: Expected -5 to be positive
expect(0, 'to be positive');

Negation:

expect(-5, 'not to be positive');
expect(0, 'not to be positive');

{unknown} to be a positive integer

✏️ Aliases:

{unknown} to be a positive integer
{unknown} to be a positive int

Success:

expect(42, 'to be a positive integer');
expect(1, 'to be a positive integer');

Failure:

expect(3.14, 'to be a positive integer');
// AssertionError: Expected 3.14 to be a positive integer
expect(-5, 'to be a positive integer');

Negation:

expect(3.14, 'not to be a positive integer');

{unknown} to be negative

✏️ Aliases:

{unknown} to be negative
{unknown} to be a negative number

Success:

expect(-42, 'to be negative');
expect(-3.14, 'to be negative');

Failure:

expect(5, 'to be negative');
// AssertionError: Expected 5 to be negative
expect(0, 'to be negative');

Negation:

expect(5, 'not to be negative');
expect(0, 'not to be negative');

{unknown} to be a negative integer

✏️ Aliases:

{unknown} to be a negative integer
{unknown} to be a negative int

Success:

expect(-42, 'to be a negative integer');
expect(-1, 'to be a negative integer');

Failure:

expect(-3.14, 'to be a negative integer');
// AssertionError: Expected -3.14 to be a negative integer
expect(5, 'to be a negative integer');

Negation:

expect(-3.14, 'not to be a negative integer');

{unknown} to be NaN

Success:

expect(NaN, 'to be NaN');
expect(Number.NaN, 'to be NaN');

Failure:

expect(42, 'to be NaN');
// AssertionError: Expected 42 to be NaN

Negation:

expect(42, 'not to be NaN');

{unknown} to be an integer

✏️ Aliases:

{unknown} to be an integer
{unknown} to be a safe integer
{unknown} to be an int
{unknown} to be a safe int

Success:

expect(42, 'to be an integer');
expect(-17, 'to be an integer');
expect(0, 'to be an integer');

Failure:

expect(3.14, 'to be an integer');
// AssertionError: Expected 3.14 to be an integer

Negation:

expect(3.14, 'not to be an integer');

{unknown} to be greater than {number}

Success:

expect(10, 'to be greater than', 5);
expect(3.14, 'to be greater than', 3);

Failure:

expect(5, 'to be greater than', 10);
// AssertionError: Expected 5 to be greater than 10

Negation:

expect(5, 'not to be greater than', 10);

{unknown} to be less than {number}

✏️ Aliases:

{unknown} to be less than {number}
{unknown} to be lt {number}

Success:

expect(5, 'to be less than', 10);
expect(3, 'to be less than', 3.14);

Failure:

expect(10, 'to be less than', 5);
// AssertionError: Expected 10 to be less than 5

Negation:

expect(10, 'not to be less than', 5);

{unknown} to be greater than or equal to {number}

✏️ Aliases:

{unknown} to be greater than or equal to {number}
{unknown} to be at least {number}
{unknown} to be gte {number}

Success:

expect(10, 'to be greater than or equal to', 10);
expect(15, 'to be at least', 10);

Failure:

expect(5, 'to be greater than or equal to', 10);
// AssertionError: Expected 5 to be greater than or equal to 10

Negation:

expect(5, 'not to be greater than or equal to', 10);

{unknown} to be less than or equal to {number}

✏️ Aliases:

{unknown} to be less than or equal to {number}
{unknown} to be at most {number}
{unknown} to be lte {number}

Success:

expect(10, 'to be less than or equal to', 10);
expect(5, 'to be at most', 10);

Failure:

expect(15, 'to be less than or equal to', 10);
// AssertionError: Expected 15 to be less than or equal to 10

Negation:

expect(15, 'not to be less than or equal to', 10);

{number} to be within {number} and {number}

✏️ Aliases:

{number} to be within {number} and {number}
{number} to be between {number} and {number}

ℹ️ This assertion is inclusive of the boundary values.

Success:

expect(5, 'to be within', 1, 10);
expect(7.5, 'to be between', 7, 8);

Failure:

expect(15, 'to be within', 1, 10);
// AssertionError: Expected 15 to be within 1 and 10

Negation:

expect(15, 'not to be within', 1, 10);

{number} to be close to {number} within {number}

ℹ️ The first number is the subject, the second number is the target, and the third number is the tolerance.

Success:

expect(1.0, 'to be close to', 1.1, 0.2);
expect(3.14159, 'to be close to', 3.14, 0.01);

Failure:

expect(1.0, 'to be close to', 2.0, 0.5);
// AssertionError: Expected 1.0 to be close to 2.0 within 0.5

Negation:

expect(1.0, 'not to be close to', 2.0, 0.5);

Other Assertions

These assertions are the odd ducks. We don't have the mental stamina to categorize them properly.

{unknown} to be truthy

✏️ Aliases:

{unknown} to be truthy
{unknown} to exist
{unknown} to be ok

Success:

expect(1, 'to be truthy');
expect('hello', 'to be truthy');
expect(true, 'to exist');
expect({}, 'to be ok');
expect([], 'to exist');

Failure:

expect(0, 'to be truthy');
// AssertionError: Expected 0 to be truthy
expect('', 'to exist');
expect(false, 'to be ok');
expect(null, 'to exist');
expect(undefined, 'to be truthy');

Negation:

expect(0, 'not to be truthy');
expect('', 'not to exist');
expect(false, 'not to be ok');

{unknown} to be falsy

Success:

expect(0, 'to be falsy');
expect('', 'to be falsy');
expect(false, 'to be falsy');
expect(null, 'to be falsy');
expect(undefined, 'to be falsy');
expect(NaN, 'to be falsy');

Failure:

expect(1, 'to be falsy');
// AssertionError: Expected 1 to be falsy
expect('hello', 'to be falsy');
expect(true, 'to be falsy');

Negation:

expect(1, 'not to be falsy');
expect('hello', 'not to be falsy');
expect(true, 'not to be falsy');

{unknown} to be defined

Success:

expect(0, 'to be defined');
expect('', 'to be defined');
expect(false, 'to be defined');
expect(null, 'to be defined');

Failure:

expect(undefined, 'to be defined');
// AssertionError: Expected undefined to be defined

Negation:

expect(undefined, 'not to be defined');

String & Pattern Assertions

These assertions test strings, regular expressions, and pattern matching.

{unknown} to be a string

👉 See to be a string

{unknown} to be a RegExp

✏️ Aliases:

{unknown} to be a RegExp
{unknown} to be a regex
{unknown} to be a regexp

Success:

expect(/hello/, 'to be a RegExp');
expect(new RegExp('world'), 'to be a regex');
expect(/[a-z]+/i, 'to be a regexp');

Failure:

expect('hello', 'to be a RegExp');
// AssertionError: Expected 'hello' to be a RegExp

Negation:

expect('hello', 'not to be a RegExp');

{string} to begin with {string}

✏️ Aliases:

{string} to begin with {string}
{string} to start with {string}

Success:

expect('hello world', 'to begin with', 'hello');
expect('JavaScript', 'to start with', 'Java');

Failure:

expect('hello world', 'to begin with', 'world');
// AssertionError: Expected 'hello world' to begin with 'world'

Negation:

expect('hello world', 'not to begin with', 'world');

{string} to end with {string}

Success:

expect('hello world', 'to end with', 'world');
expect('test.js', 'to end with', '.js');

Failure:

expect('hello world', 'to end with', 'hello');
// AssertionError: Expected 'hello world' to end with 'hello'

Negation:

expect('hello world', 'not to end with', 'hello');

{string} to match {RegExp}

Success:

expect('hello123', 'to match', /\d+/);
expect('JavaScript', 'to match', /^Java/);
expect('test@example.com', 'to match', /@/);

Failure:

expect('hello', 'to match', /\d+/);
// AssertionError: Expected 'hello' to match /\d+/

Negation:

expect('hello', 'not to match', /\d+/);

{string} to be empty

Success:

expect('', 'to be empty');

Failure:

expect('hello', 'to be empty');
// AssertionError: Expected 'hello' to be empty

Negation:

expect('hello', 'not to be empty');

{string} to be non-empty

Functionally identical to "not to be empty".

Success:

expect('hello', 'to be non-empty');
expect(' ', 'to be non-empty'); // Whitespace counts as non-empty

Failure:

expect('', 'to be non-empty');
// AssertionError: Expected '' to be non-empty

Negation:

PRO TIP: Use "to be empty" instead.

expect('', 'not to be non-empty');

{string} includes {string}

✏️ Aliases:

{string} includes {string}
{string} contains {string}

Success:

expect('hello world', 'includes', 'world');
expect('JavaScript', 'contains', 'Script');
expect([1, 2, 3], 'to include', 2);
expect('test string', 'to contain', 'string');

Failure:

expect('hello', 'includes', 'world');
// AssertionError: Expected 'hello' to include 'world'

Negation:

expect('hello', 'not to include', 'world');

Collection Assertions

These assertions test collections like arrays, Maps, Sets, and their properties.

{unknown} to be an array

✏️ Aliases:

{unknown} to be an array
{unknown} to be array

Success:

expect([], 'to be an array');
expect([1, 2, 3], 'to be an array');
expect(new Array(5), 'to be an array');

Failure:

expect('hello', 'to be an array');
// AssertionError: Expected 'hello' to be an array

Negation:

expect('hello', 'not to be an array');

{arraylike} to be empty

Success:

expect([], 'to be empty');

Failure:

expect([1, 2, 3], 'to be empty');
// AssertionError: Expected [1, 2, 3] to be empty

Negation:

expect([1, 2, 3], 'not to be empty');

{array} to have length {nonnegative-integer}

✏️ Aliases:

{array} to have length {nonnegative-integer}
{array} to have size {nonnegative-integer}

Success:

expect([1, 2, 3], 'to have length', 3);
expect('hello', 'to have length', 5);

Failure:

expect([1, 2], 'to have length', 3);
// AssertionError: Expected [1, 2] to have length 3

Negation:

expect([1, 2], 'not to have length', 3);

{arraylike} to be non-empty

Functionally equivalent to not to be empty.

Success:

expect([1, 2, 3], 'to be non-empty');
expect('hello', 'to be non-empty');

Failure:

expect([], 'to be non-empty');
// AssertionError: Expected [] to be non-empty

Negation:

expect([], 'not to be non-empty');

{array} to contain {any}

✏️ Aliases:

{array} to contain {any}
{array} to include {any}

Success:

expect([1, 2, 3], 'to contain', 2);
expect(['a', 'b', 'c'], 'to include', 'b');

Failure:

expect([1, 2, 3], 'to contain', 5);
// AssertionError: Expected [1, 2, 3] to contain 5

Negation:

expect([1, 2, 3], 'not to contain', 5);

{Map} to contain {any}

✏️ Aliases:

{Map} to contain {any}
{Map} to include {any}

Success:

const map = new Map([
  ['key1', 'value1'],
  ['key2', 'value2'],
]);
expect(map, 'to contain', 'key1');
expect(map, 'to include', 'key2');

Failure:

const map = new Map([['key1', 'value1']]);
expect(map, 'to contain', 'key3');
// AssertionError: Expected Map to contain 'key3'

Negation:

expect(map, 'not to contain', 'key3');

{Map} to have size {nonnegative-integer}

Success:

const map = new Map([
  ['a', 1],
  ['b', 2],
]);
expect(map, 'to have size', 2);

Failure:

const map = new Map([['a', 1]]);
expect(map, 'to have size', 2);
// AssertionError: Expected Map to have size 2

Negation:

expect(map, 'not to have size', 2);

{Map} to be empty

Success:

expect(new Map(), 'to be empty');

Failure:

const map = new Map([['a', 1]]);
expect(map, 'to be empty');
// AssertionError: Expected Map to be empty

Negation:

expect(map, 'not to be empty');

{Set} to contain {any}

✏️ Aliases:

{Set} to contain {any}
{Set} to include {any}

Success:

const set = new Set([1, 2, 3]);
expect(set, 'to contain', 2);
expect(set, 'to include', 3);

Failure:

const set = new Set([1, 2, 3]);
expect(set, 'to contain', 5);
// AssertionError: Expected Set to contain 5

Negation:

expect(set, 'not to contain', 5);

{Set} to have size {nonnegative-integer}

Success:

const set = new Set([1, 2, 3]);
expect(set, 'to have size', 3);

Failure:

const set = new Set([1, 2]);
expect(set, 'to have size', 3);
// AssertionError: Expected Set to have size 3

Negation:

expect(set, 'not to have size', 3);

{Set} to be empty

Success:

expect(new Set(), 'to be empty');

Failure:

const set = new Set([1, 2, 3]);
expect(set, 'to be empty');
// AssertionError: Expected Set to be empty

Negation:

expect(set, 'not to be empty');

{unknown} to be a Set

Success:

expect(new Set(), 'to be a Set');
expect(new Set([1, 2, 3]), 'to be a Set');

Failure:

expect([1, 2, 3], 'to be a Set');
// AssertionError: Expected [1, 2, 3] to be a Set

Negation:

expect([1, 2, 3], 'not to be a Set');

{WeakMap} to contain {object | symbol}

✏️ Aliases:

{WeakMap} to contain {object | symbol}
{WeakMap} to include {object | symbol}

Success:

const obj = {};
const wm = new WeakMap([[obj, 'value']]);
expect(wm, 'to contain', obj);

Failure:

const obj1 = {},
  obj2 = {};
const wm = new WeakMap([[obj1, 'value']]);
expect(wm, 'to contain', obj2);
// AssertionError: Expected WeakMap to contain object

Negation:

expect(wm, 'not to contain', obj2);

{unknown} to be a WeakMap

Success:

expect(new WeakMap(), 'to be a WeakMap');

Failure:

expect(new Map(), 'to be a WeakMap');
// AssertionError: Expected Map to be a WeakMap

Negation:

expect(new Map(), 'not to be a WeakMap');

{WeakSet} to contain {object | symbol}

✏️ Aliases:

{WeakSet} to contain {object | symbol}
{WeakSet} to include {object | symbol}

Success:

const obj = {};
const ws = new WeakSet([obj]);
expect(ws, 'to contain', obj);

Failure:

const obj1 = {},
  obj2 = {};
const ws = new WeakSet([obj1]);
expect(ws, 'to contain', obj2);
// AssertionError: Expected WeakSet to contain object

Negation:

expect(ws, 'not to contain', obj2);

{unknown} to be a WeakSet

Success:

expect(new WeakSet(), 'to be a WeakSet');

Failure:

expect(new Set(), 'to be a WeakSet');
// AssertionError: Expected Set to be a WeakSet

Negation:

expect(new Set(), 'not to be a WeakSet');

Object Assertions

These assertions test objects, their properties, and object-specific behaviors.

{unknown} to be an object

Success:

expect({}, 'to be an object');
expect({ a: 1 }, 'to be an object');
expect([], 'to be an object'); // Arrays are objects
expect(new Date(), 'to be an object');

Failure:

expect('hello', 'to be an object');
// AssertionError: Expected 'hello' to be an object
expect(null, 'to be an object');

Negation:

expect('hello', 'not to be an object');
expect(null, 'not to be an object');

{unknown} to be a record

✏️ Aliases:

{unknown} to be a record
{unknown} to be a plain object

Success:

expect({}, 'to be a record');
expect({ a: 1, b: 2 }, 'to be a plain object');

Failure:

expect([], 'to be a record');
// AssertionError: Expected [] to be a record
expect(new Date(), 'to be a record');

Negation:

expect([], 'not to be a record');

{object} to be empty

Success:

expect({}, 'to be empty');

Failure:

expect({ a: 1 }, 'to be empty');
// AssertionError: Expected { a: 1 } to be empty

Negation:

expect({ a: 1 }, 'not to be empty');

{object} to have keys {array}

✏️ Aliases:

{object} to have keys {array}
{object} to have properties {array}
{object} to have props {array}
{object} to include keys {array}
{object} to include properties {array}
{object} to include props {array}
{object} to contain keys {array}
{object} to contain properties {array}
{object} to contain props {array}

Success:

expect({ a: 1, b: 2 }, 'to have keys', ['a', 'b']);
expect({ name: 'John', age: 30 }, 'to have properties', ['name', 'age']);

Failure:

expect({ a: 1 }, 'to have keys', ['a', 'b']);
// AssertionError: Expected { a: 1 } to have keys ['a', 'b']

Negation:

expect({ a: 1 }, 'not to have keys', ['a', 'b']);

{object} to have key {keypath}

✏️ Aliases:

{object} to have key {keypath}
{object} to have property {keypath}
{object} to have prop {keypath}
{object} to include key {keypath}
{object} to include property {keypath}
{object} to include prop {keypath}
{object} to contain key {keypath}
{object} to contain property {keypath}
{object} to contain prop {keypath}

Tests whether an object has a property at the specified keypath using dot or bracket notation. This assertion supports complex keypath traversal including nested properties, array indices, and quoted keys.

Supported keypath formats:

Dot notation: 'prop.nested'
Bracket notation with numbers: 'arr[0]'
Bracket notation with quoted strings: 'obj["key"]' or "obj['key']"
Mixed notation: 'data.items[1].name'

Success:

const obj = {
  foo: { bar: [{ baz: 'value' }] },
  'kebab-case': 'works',
  items: [
    { id: 1, name: 'first' },
    { id: 2, name: 'second' },
  ],
};

expect(obj, 'to have key', 'foo.bar');
expect(obj, 'to have property', 'foo.bar[0].baz');
expect(obj, 'to have prop', 'kebab-case');
expect(obj, 'to have key', 'items[1].name');
expect(obj, 'to have property', 'foo["bar"][0]["baz"]');

Failure:

expect(obj, 'to have key', 'nonexistent.path');
// AssertionError: Expected object to contain keypath nonexistent.path

expect(obj, 'to have property', 'foo.bar[5].missing');
// AssertionError: Expected object to contain keypath foo.bar[5].missing

Negation:

expect(obj, 'not to have key', 'nonexistent.path');
expect(obj, 'not to have property', 'foo.bar[5].missing');

{object} to have exact key {string | number | symbol}

✏️ Aliases:

{object} to have exact key {string | number | symbol}
{object} to have exact property {string | number | symbol}
{object} to have exact prop {string | number | symbol}

Tests whether an object has an exact property key without keypath traversal. This assertion checks for direct properties on the object and supports symbols and keys that would conflict with bracket/dot notation.

Unlike to have key, this assertion:

Does not support keypath traversal (no dots or brackets are interpreted)
Can check for symbol keys
Can check for keys containing dots, brackets, or other special characters as literal property names
Only checks direct properties (no nested access)

Success:

const sym = Symbol('test');
const obj = {
  simple: 'value',
  'key.with.dots': 'direct property',
  'key[with]brackets': 'another direct property',
  [sym]: 'symbol value',
};

expect(obj, 'to have exact key', 'simple');
expect(obj, 'to have exact property', 'key.with.dots'); // literal key, not traversal
expect(obj, 'to have exact prop', 'key[with]brackets'); // literal key, not array access
expect(obj, 'to have exact key', sym); // symbol key

Failure:

const obj = { nested: { prop: 'value' } };

expect(obj, 'to have exact key', 'nested.prop');
// AssertionError: Expected object to have exact key nested.prop
// (This fails because 'nested.prop' is not a direct property)

expect(obj, 'to have exact property', 'missing');
// AssertionError: Expected object to have exact key missing

Negation:

expect(obj, 'not to have exact key', 'missing');
expect(obj, 'not to have exact property', 'nested.prop'); // no traversal

{object} to have a null prototype

✏️ Aliases:

{object} to have a null prototype
{object} to be a dictionary

Success:

const obj = Object.create(null);
expect(obj, 'to have a null prototype');

Failure:

expect({}, 'to have a null prototype');
// AssertionError: Expected {} to have a null prototype

Negation:

expect({}, 'not to have a null prototype');

{string | number | symbol} to be an enumerable property of {non-null}

✏️ Aliases:

{string | number | symbol} to be an enumerable property of {non-null}
{non-null} to have enumerable property {string | number | symbol}

This accepts any non-null, non-undefined value as the second parameter.

Success:

const obj = { a: 1, b: 2 };
expect('a', 'to be an enumerable property of', obj);

Failure:

const obj = { a: 1 };
Object.defineProperty(obj, 'b', { value: 2, enumerable: false });
expect('b', 'to be an enumerable property of', obj);
// AssertionError: Expected 'b' to be an enumerable property of object

Negation:

expect('b', 'not to be an enumerable property of', obj);

{unknown} to be sealed

Success:

const obj = { a: 1 };
Object.seal(obj);
expect(obj, 'to be sealed');

Failure:

expect({}, 'to be sealed');
// AssertionError: Expected {} to be sealed

Negation:

expect({}, 'not to be sealed');

{unknown} to be frozen

Success:

const obj = { a: 1 };
Object.freeze(obj);
expect(obj, 'to be frozen');

Failure:

expect({}, 'to be frozen');
// AssertionError: Expected {} to be frozen

Negation:

expect({}, 'not to be frozen');

{unknown} to be extensible

Success:

expect({}, 'to be extensible');

Failure:

const obj = {};
Object.preventExtensions(obj);
expect(obj, 'to be extensible');
// AssertionError: Expected {} to be extensible

Negation:

expect(obj, 'not to be extensible');

{object} to satisfy {any}

✏️ Aliases:

{object} to satisfy {any}
{object} to be like {any}

"To satisfy" is a ~~wonky~~ special loose "deep equal" assertion. It is similar to AVA's t.like() or Jest's expect.objectContaining(). It checks that the actual object contains at least the properties and values specified in the expected object. It ignores any additional properties.

In addition, any regular expression in a property value position will be used to match the corresponding actual value (which will be coerced into a string). This makes it easy to assert that a string property contains a substring, starts with a prefix, or matches some other pattern.

Note: The parameter in this assertion and others supporting the "to satisfy" semantics are not strongly typed, even though regular expressions and expect.it() have special meaning. This is because the parameter can accept literally any value.

Success:

expect({ a: 1, b: 2, c: 3 }, 'to satisfy', { a: 1, b: 2 });
expect({ name: 'John', age: 30 }, 'to be like', { name: 'John' });

// Using regular expressions in property values
expect(
  {
    email: 'user@example.com',
    phone: '+1-555-0123',
    id: 12345,
  },
  'to satisfy',
  {
    email: /^user@/,
    phone: /^\+1-555/,
    id: /123/,
  },
);

Failure:

expect({ a: 1 }, 'to satisfy', { a: 1, b: 2 });
// AssertionError: Expected { a: 1 } to satisfy { a: 1, b: 2 }

Negation:

expect({ a: 1 }, 'not to satisfy', { a: 1, b: 2 });

Function Assertions

These assertions test functions, their behavior, and properties.

{unknown} to be a function

Success:

expect(function () {}, 'to be a function');
expect(() => {}, 'to be a function');
expect(Math.max, 'to be a function');

Failure:

expect('hello', 'to be a function');
// AssertionError: Expected 'hello' to be a function

Negation:

expect('hello', 'not to be a function');

to be an async function

Success:

expect(async function () {}, 'to be an async function');
expect(async () => {}, 'to be an async function');

Failure:

expect(function () {}, 'to be an async function');
// AssertionError: Expected function to be an async function

Negation:

expect(function () {}, 'not to be an async function');

{unknown} to be a constructor

✏️ Aliases:

{unknown} to be a constructor
{unknown} to be constructible
{unknown} to be a class

⚠️ Warning!

It is currently (as of September 2025) not possible to reliably distinguish between classes and regular functions in JavaScript. We can only tell if a function is constructable (i.e., can be called with new); we cannot determine if it is specifically a class constructor.

Use with caution.

Success:

class MyClass {}
expect(MyClass, 'to be a class');
expect(Date, 'to be a constructor');

Failure:

const fn = function () {};
expect(fn, 'to be a class');
// AssertionError: Expected function to be a class

Negation:

expect(fn, 'not to be a class');

{function} to have arity {nonnegative-integer}

Success:

function add(a, b) {
  return a + b;
}
expect(add, 'to have arity', 2);

const multiply = (x, y, z) => x * y * z;
expect(multiply, 'to have arity', 3);

Failure:

function greet(name) {
  return `Hello, ${name}!`;
}
expect(greet, 'to have arity', 2);
// AssertionError: Expected function to have arity 2

Negation:

expect(greet, 'not to have arity', 2);

{function} to throw [{any}]

✏️ Aliases:
{function} to throw [{any}]
{function} to throw an error satisfying {any}
ℹ️ The to throw form of this assertion optionally accepts a parameter using the "to satisfy" semantics. The to throw an error satisfying form requires this parameter.

👉 See to satisfy <any>

Success:

expect(() => {
  throw new Error('Something went wrong');
}, 'to throw');

expect(() => {
  JSON.parse('invalid json');
}, 'to throw');

// String matching
expect(
  () => {
    throw new Error('Specific error message');
  },
  'to throw',
  'Specific error message',
);

// RegExp matching
expect(
  () => {
    throw new Error('Error: Something failed');
  },
  'to throw',
  /Something failed/,
);

// Object matching
expect(
  () => {
    throw new Error('Custom error');
  },
  'to throw',
  { message: 'Custom error' },
);

Failure:

expect(() => {
  return 'all good';
}, 'to throw');
// AssertionError: Expected function to throw

expect(
  () => {
    throw new Error('Different message');
  },
  'to throw',
  'Specific error message',
);
// AssertionError: Expected function to throw 'Specific error message'

Negation:

expect(() => {
  return 'all good';
}, 'not to throw');

expect(
  () => {
    throw new Error('Different message');
  },
  'not to throw',
  'Specific error message',
);

{function} to throw a {constructor}

✏️ Aliases:

{function} to throw a {constructor}
{function} to throw an {constructor}

Success:

expect(
  () => {
    throw new TypeError('Type error');
  },
  'to throw a',
  TypeError,
);

expect(
  () => {
    throw new RangeError('Range error');
  },
  'to throw an',
  Error,
); // RangeError extends Error

Failure:

expect(
  () => {
    throw new TypeError('Type error');
  },
  'to throw a',
  RangeError,
);
// AssertionError: Expected function to throw a RangeError

Negation:

expect(
  () => {
    throw new TypeError('Type error');
  },
  'not to throw a',
  RangeError,
);

{function} to throw a {constructor} satisfying {any}

✏️ Aliases:

{function} to throw a {constructor} satisfying {any}
{function} to throw an {constructor} satisfying {any}

👉 See {object} to satisfy {any}

This assertion is a combination of "to throw a" and "to throw".

Success:

expect(
  () => {
    const err = new Error('Custom error');
    err.code = 'CUSTOM_CODE';
    throw err;
  },
  'to throw a',
  Error,
  'satisfying',
  { code: 'CUSTOM_CODE' },
);

Failure:

expect(
  () => {
    throw new Error('Simple error');
  },
  'to throw a',
  Error,
  'satisfying',
  { code: 'MISSING_CODE' },
);
// AssertionError: Expected thrown error to satisfy { code: 'MISSING_CODE' }

Negation:

expect(
  () => {
    throw new Error('Simple error');
  },
  'not to throw a',
  Error,
  'satisfying',
  { code: 'MISSING_CODE' },
);

Equality & Comparison Assertions

These assertions test equality, identity, and value comparisons.

{unknown} to equal {any}

✏️ Aliases:

{unknown} to equal {any}
{unknown} to be {any}
{unknown} equals {any}
{unknown} is {any}
{unknown} is equal to {any}
{unknown} to strictly equal {any}
{unknown} is strictly equal to {any}

Success:

expect(42, 'to be', 42);
expect('hello', 'to equal', 'hello');
expect(true, 'is', true);
expect(null, 'is equal to', null);

Failure:

expect(42, 'to be', '42');
// AssertionError: Expected 42 to be '42'
expect({}, 'to equal', {});
// AssertionError: Expected {} to equal {}

Negation:

expect(42, 'not to be', '42');
expect({}, 'not to equal', {});

{unknown} to deep equal {any}

✏️ Aliases:

{unknown} to deep equal {any}
{unknown} to deep equal {any}

Success:

expect({ a: 1, b: 2 }, 'to deep equal', { a: 1, b: 2 });
expect([1, 2, 3], 'to deeply equal', [1, 2, 3]);
expect({ nested: { value: 42 } }, 'to deep equal', { nested: { value: 42 } });

Failure:

expect({ a: 1 }, 'to deep equal', { a: 1, b: 2 });
// AssertionError: Expected { a: 1 } to deep equal { a: 1, b: 2 }

Negation:

expect({ a: 1 }, 'not to deep equal', { a: 1, b: 2 });

{unknown} to be one of {array}

Success:

expect(2, 'to be one of', [1, 2, 3]);
expect('blue', 'to be one of', ['red', 'green', 'blue']);

Failure:

expect(5, 'to be one of', [1, 2, 3]);
// AssertionError: Expected 5 to be one of [1, 2, 3]

Negation:

expect(5, 'not to be one of', [1, 2, 3]);

{unknown} to be an instance of {constructor}

✏️ Aliases:

{unknown} to be an instance of {constructor}
{unknown} to be a {constructor}
{unknown} to be an {constructor}

Success:

expect(new Date(), 'to be an instance of', Date);
expect([], 'to be a', Array);
expect('hello', 'to be an instance of', String); // Note: primitive strings work too

Failure:

expect('hello', 'to be an instance of', Number);
// AssertionError: Expected 'hello' to be an instance of Number

Negation:

expect('hello', 'not to be an instance of', Number);

{unknown} to be a {intrinsic-type}

✏️ Aliases:

{unknown} to be a {intrinsic-type}
{unknown} to be an {intrinsic-type}
{unknown} to have type {intrinsic-type}

An intrinsic type is a case-insensitive string matching: string, number, boolean, bigint, symbol, undefined, object, function, null, Map, Set, WeakMap, WeakSet, WeakRef, Date, Error, Array, RegExp, Promise. This is a mashup of the result of typeof and constructor names for built-in types.

Success:

expect(new Date(), 'to be a', 'Date');
expect(new Error(), 'to be an', 'Error');
expect([], 'to be an', 'Array');
expect(1, 'to be a', 'number');

Failure:

expect('hello', 'to be a', Number);
// AssertionError: Expected 'hello' to be a Number

Negation:

expect('hello', 'not to be a', Number);

Error Assertions

These assertions test Error objects and their properties. If the subject looks like an Error but is not an instance of Error, these assertions will be unavailable.

{unknown} to be an Error

✏️ Aliases:

{unknown} to be an Error
{unknown} to be a Error

Success:

expect(new Error(), 'to be an Error');
expect(new TypeError(), 'to be an Error');
expect(new RangeError('Invalid range'), 'to be an Error');

Failure:

expect('error message', 'to be an Error');
// AssertionError: Expected 'error message' to be an Error

Negation:

expect('error message', 'not to be an Error');

{Error} to have message {string}

Success:

const error = new Error('Something went wrong');
expect(error, 'to have message', 'Something went wrong');

const typeError = new TypeError('Invalid type');
expect(typeError, 'to have message', 'Invalid type');

Failure:

const error = new Error('Actual message');
expect(error, 'to have message', 'Expected message');
// AssertionError: Expected Error to have message 'Expected message'

Negation:

expect(error, 'not to have message', 'Expected message');

{Error} to have message matching {RegExp}

Success:

const error = new Error('File not found: /path/to/file.txt');
expect(error, 'to have message matching', /File not found/);
expect(error, 'to have message matching', /\.txt$/);

Failure:

const error = new Error('Something went wrong');
expect(error, 'to have message matching', /File not found/);
// AssertionError: Expected Error message to match /File not found/

Negation:

expect(error, 'not to have message matching', /File not found/);

Date & Time Assertions

These assertions test Date objects, time-related values, durations, and temporal relationships.

{unknown} to be a Date

✏️ Aliases:

{unknown} to be a Date
{unknown} to be a date

Success:

expect(new Date(), 'to be a date');
expect(new Date('2024-01-01'), 'to be a Date');
expect(new Date(Date.now()), 'to be a date');

Failure:

expect('2024-01-01', 'to be a date');
// AssertionError: Expected '2024-01-01' to be a date
expect(1704067200000, 'to be a Date'); // Unix timestamp

Negation:

expect('2024-01-01', 'not to be a date');
expect(1704067200000, 'not to be a Date');

{unknown} to be a valid date

✏️ Aliases:

{unknown} to be a valid date
{unknown} to be date-like

Success:

expect(new Date(), 'to be a valid date');
expect('2024-01-01', 'to be date-like');
expect(1704067200000, 'to be a valid date'); // Unix timestamp

Failure:

expect('invalid-date', 'to be a valid date');
// AssertionError: Expected 'invalid-date' to be a valid date
expect(NaN, 'to be date-like');

Negation:

expect('invalid-date', 'not to be a valid date');
expect(NaN, 'not to be date-like');

{date-like} to be before {date-like}

Success:

expect(new Date('2022-01-01'), 'to be before', new Date('2023-01-01'));
expect('2022-01-01', 'to be before', '2023-01-01');
expect(1640995200000, 'to be before', new Date('2023-01-01'));

Failure:

expect(new Date('2023-01-01'), 'to be before', new Date('2022-01-01'));
// AssertionError: Expected 2023-01-01T00:00:00.000Z to be before 2022-01-01T00:00:00.000Z

Negation:

expect(new Date('2023-01-01'), 'not to be before', new Date('2022-01-01'));

{date-like} to be after {date-like}

Success:

expect(new Date('2023-01-01'), 'to be after', new Date('2022-01-01'));
expect('2023-01-01', 'to be after', '2022-01-01');
expect(Date.now(), 'to be after', new Date('2020-01-01'));

Failure:

expect(new Date('2022-01-01'), 'to be after', new Date('2023-01-01'));
// AssertionError: Expected 2022-01-01T00:00:00.000Z to be after 2023-01-01T00:00:00.000Z

Negation:

expect(new Date('2022-01-01'), 'not to be after', new Date('2023-01-01'));

{date-like} to be between {date-like} and {date-like}

Success:

expect(
  new Date('2022-06-01'),
  'to be between',
  new Date('2022-01-01'),
  new Date('2022-12-31'),
);
expect('2022-06-01', 'to be between', '2022-01-01', 'and', '2022-12-31');

Failure:

expect(
  new Date('2023-01-01'),
  'to be between',
  new Date('2022-01-01'),
  'and',
  new Date('2022-12-31'),
);
// AssertionError: Expected 2023-01-01T00:00:00.000Z to be between 2022-01-01T00:00:00.000Z and 2022-12-31T00:00:00.000Z

Negation:

expect(
  new Date('2023-01-01'),
  'not to be between',
  new Date('2022-01-01'),
  new Date('2022-12-31'),
);

{date-like} to be the same date as {date-like}

Success:

expect(
  new Date('2023-01-01T10:00:00'),
  'to be the same date as',
  new Date('2023-01-01T15:30:00'),
); // same date, different times
expect('2023-01-01', 'to be the same date as', new Date('2023-01-01T23:59:59'));

Failure:

expect(
  new Date('2023-01-01'),
  'to be the same date as',
  new Date('2023-01-02'),
);
// AssertionError: Expected 2023-01-01T00:00:00.000Z to be the same date as 2023-01-02T00:00:00.000Z

Negation:

expect(
  new Date('2023-01-01'),
  'not to be the same date as',
  new Date('2023-01-02'),
);

{date-like} to equal {date-like} within {duration}

Success:

const date1 = new Date('2023-01-01T10:00:00.000Z');
const date2 = new Date('2023-01-01T10:00:00.500Z');
expect(date1, 'to equal', date2, 'within', '1 second'); // 500ms difference
expect(date1, 'to equal', date2, 'within', '1 minute');

Failure:

const date1 = new Date('2023-01-01T10:00:00.000Z');
const date2 = new Date('2023-01-01T10:00:00.500Z');
expect(date1, 'to equal', date2, 'within', '100 milliseconds');
// AssertionError: Expected dates to be equal within 100 milliseconds

Negation:

expect(date1, 'not to equal', date2, 'within', '100 milliseconds');

{unknown} to be a weekend

Tests whether the date represents a weekend day (Saturday or Sunday) in UTC.

Success:

expect(new Date('2023-01-07'), 'to be a weekend'); // Saturday in UTC
expect(new Date('2023-01-08'), 'to be a weekend'); // Sunday in UTC
expect('2023-12-30', 'to be a weekend'); // Saturday in UTC

Failure:

expect(new Date('2023-01-09'), 'to be a weekend'); // Monday in UTC
// AssertionError: Expected 2023-01-09T00:00:00.000Z to be a weekend

Negation:

expect(new Date('2023-01-09'), 'not to be a weekend'); // Monday in UTC

{unknown} to be a weekday

Tests whether the date represents a weekday (Monday through Friday) in UTC.

Success:

expect(new Date('2023-01-09'), 'to be a weekday'); // Monday in UTC
expect(new Date('2023-01-13'), 'to be a weekday'); // Friday in UTC
expect('2023-01-10', 'to be a weekday'); // Tuesday in UTC

Failure:

expect(new Date('2023-01-07'), 'to be a weekday'); // Saturday in UTC
// AssertionError: Expected 2023-01-07T00:00:00.000Z to be a weekday

Negation:

expect(new Date('2023-01-07'), 'not to be a weekday'); // Saturday in UTC

Duration Formats

The date/time assertions support human-readable duration strings in the following formats:

Milliseconds: "100 milliseconds", "500 ms"
Seconds: "30 seconds", "1 second", "45 sec"
Minutes: "5 minutes", "1 minute", "30 min"
Hours: "2 hours", "1 hour", "12 hr"
Days: "7 days", "1 day"
Weeks: "2 weeks", "1 week"
Months: "3 months", "1 month"
Years: "2 years", "1 year"

Examples:

expect(someDate, 'to be within', '30 minutes', 'ago');
expect(futureDate, 'to be at least', '2 hours', 'from now');
expect(date1, 'to equal', date2, 'within', '1 second');

Promise Assertions

These assertions all expect a Promise subject. Use expectAsync() for these assertions.

{Promise} to resolve

✏️ Aliases:

{Promise} to resolve
{Promise} to fulfill

Success:

await expectAsync(Promise.resolve(42), 'to resolve');
await expectAsync(Promise.resolve('success'), 'to fulfill');

// With async functions
await expectAsync(async () => 'result', 'to resolve');

Failure:

await expectAsync(Promise.reject('error'), 'to resolve');
// AssertionError: Expected Promise to resolve

Negation:

await expectAsync(Promise.reject('error'), 'not to resolve');

{Promise} to reject

Success:

await expectAsync(Promise.reject('error'), 'to reject');
await expectAsync(Promise.reject(new Error('failed')), 'to reject');

// With async functions
await expectAsync(async () => {
  throw new Error('async error');
}, 'to reject');

Failure:

await expectAsync(Promise.resolve(42), 'to reject');
// AssertionError: Expected Promise to reject

Negation:

await expectAsync(Promise.resolve(42), 'not to reject');

{Promise} to reject with a {constructor}

✏️ Aliases:

{Promise} to reject with a {constructor}
{Promise} to reject with an {constructor}

Success:

await expectAsync(
  Promise.reject(new TypeError('Type error')),
  'to reject with a',
  TypeError,
);

await expectAsync(
  Promise.reject(new Error('Generic error')),
  'to reject with an',
  Error,
);

Failure:

await expectAsync(
  Promise.reject(new TypeError('Type error')),
  'to reject with a',
  RangeError,
);
// AssertionError: Expected Promise to reject with a RangeError

Negation:

await expectAsync(
  Promise.reject(new TypeError('Type error')),
  'not to reject with a',
  RangeError,
);

{Promise} to reject with error satisfying {any}

👉 See {object} to satisfy {any}

Success:

// String matching
await expectAsync(
  Promise.reject(new Error('Specific error')),
  'to reject with',
  'Specific error',
);

// RegExp matching
await expectAsync(
  Promise.reject(new Error('Error: Something failed')),
  'to reject with',
  /Something failed/,
);

// Object matching
await expectAsync(
  Promise.reject({ message: 'Custom error', code: 500 }),
  'to reject with',
  { message: 'Custom error' },
);

Failure:

await expectAsync(
  Promise.reject(new Error('Different error')),
  'to reject with',
  'Specific error',
);
// AssertionError: Expected Promise to reject with 'Specific error'

Negation:

await expectAsync(
  Promise.reject(new Error('Different error')),
  'not to reject with',
  'Specific error',
);

{Promise} to resolve with value satisfying {any}

✏️ Aliases:

{Promise} to resolve with value satisfying {any}
{Promise} to fulfill with value satisfying {any}

👉 See {object} to satisfy {any}}

Success:

// String matching
await expectAsync(
  Promise.resolve('Hello World'),
  'to fulfill with value satisfying',
  'Hello World',
);

// RegExp matching
await expectAsync(
  Promise.resolve('Success: Operation completed'),
  'to resolve to value satisfying',
  /Success/,
);

// Object matching
await expectAsync(
  Promise.resolve({ status: 'ok', data: [1, 2, 3] }),
  'to fulfill with value satisfying',
  { status: 'ok' },
);

Failure:

await expectAsync(
  Promise.resolve('Different value'),
  'to fulfill with value satisfying',
  'Expected value',
);
// AssertionError: Expected Promise to resolve to value satisfying 'Expected value'

Negation:

await expectAsync(
  Promise.resolve('Different value'),
  'not to fulfill with value satisfying',
  'Expected value',
);