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 have keys satisfying {any}

✏️ Aliases:

{object} to have keys satisfying {any}
{object} to have props satisfying {any}
{object} to have properties satisfying {any}
{object} to have fields satisfying {any}

Asserts that all own enumerable string keys of a non-collection object individually satisfy the expected shape. Uses partial/satisfy semantics. Empty objects pass vacuously.

⚠️ Accepts any non-Map/Set/WeakMap/WeakSet object — including plain objects, class instances, and functions. Only considers own enumerable string keys (equivalent to Object.keys()). Symbol keys and non-enumerable properties are not checked.

Success:

expect(
  { foo: 1, bar: 2 },
  'to have keys satisfying',
  expect.it('to be a string'),
);
expect({ foo: 1, bar: 2 }, 'to have keys satisfying', /^[a-z]+$/);
expect({}, 'to have keys satisfying', /impossible/); // vacuously true

Failure:

expect({ FOO: 1, bar: 2 }, 'to have keys satisfying', /^[a-z]+$/);
// AssertionError: Expected all object keys to satisfy …, but key 'FOO' did not match

Negation:

expect({ FOO: 1 }, 'not to have keys satisfying', /^[a-z]+$/);

{object} to have a key satisfying {any}

✏️ Aliases:

{object} to have a key satisfying {any}
{object} to have key satisfying {any}
{object} to have a prop satisfying {any}
{object} to have prop satisfying {any}
{object} to have a property satisfying {any}
{object} to have property satisfying {any}
{object} to have a field satisfying {any}
{object} to have field satisfying {any}

Asserts that at least one own enumerable string key of a non-collection object satisfies the expected shape. Fails on objects with no own enumerable string keys.

⚠️ Accepts any non-Map/Set/WeakMap/WeakSet object. Only considers own enumerable string keys (equivalent to Object.keys()).

Success:

expect({ foo: 1, BAR: 2 }, 'to have a key satisfying', /^[a-z]+$/);
expect({ foo: 1 }, 'to have key satisfying', expect.it('to be a string'));

Failure:

expect({ FOO: 1, BAR: 2 }, 'to have a key satisfying', /^[a-z]+$/);
// AssertionError: Expected object to have a key satisfying …, but none matched

Negation:

expect({ FOO: 1, BAR: 2 }, 'not to have a key satisfying', /^[a-z]+$/);

{object} to have keys matching {RegExp}

✏️ Aliases:

{object} to have keys matching {RegExp}
{object} to have props matching {RegExp}
{object} to have properties matching {RegExp}
{object} to have fields matching {RegExp}

Asserts that all own enumerable string keys of a non-collection object match a regular expression. Empty objects pass vacuously.

⚠️ Accepts any non-Map/Set/WeakMap/WeakSet object. Only considers own enumerable string keys. Symbol keys and non-enumerable properties are not checked.

Success:

expect({ foo: 1, bar: 2 }, 'to have keys matching', /^[a-z]+$/);
expect({}, 'to have keys matching', /impossible/); // vacuously true

Failure:

expect({ foo: 1, Bar: 2 }, 'to have keys matching', /^[a-z]+$/);
// AssertionError: Expected all object keys to match /^[a-z]+$/, but key 'Bar' did not match

Negation:

expect({ FOO: 1 }, 'not to have keys matching', /^[a-z]+$/);

{object} to have a key matching {RegExp}

✏️ Aliases:

{object} to have a key matching {RegExp}
{object} to have key matching {RegExp}
{object} to have a prop matching {RegExp}
{object} to have prop matching {RegExp}
{object} to have a property matching {RegExp}
{object} to have property matching {RegExp}
{object} to have a field matching {RegExp}
{object} to have field matching {RegExp}

Asserts that at least one own enumerable string key of a non-collection object matches a regular expression. Fails on objects with no own enumerable string keys.

⚠️ Accepts any non-Map/Set/WeakMap/WeakSet object. Only considers own enumerable string keys. Symbol keys and non-enumerable properties are not checked.

Success:

expect({ foo: 1, BAR: 2 }, 'to have a key matching', /^[a-z]+$/);
expect({ foo: 1 }, 'to have key matching', /foo/);

Failure:

expect({ FOO: 1, BAR: 2 }, 'to have a key matching', /^[a-z]+$/);
// AssertionError: Expected object to have a key matching /^[a-z]+$/, but none matched

Negation:

expect({ FOO: 1, BAR: 2 }, 'not to have a key matching', /^[a-z]+$/);

{object} to satisfy {any}

See {unknown} to satisfy {any} in Equality & Comparison Assertions.

{object} to deep equal {any}

See {unknown} to deep equal {any} in Equality & Comparison Assertions.