bare-assert

stable

bare-assert — Assertion library for JavaScript. It is written in JavaScript, but it depends on bare-type, a native addon that requires Bare >=1.32.0, so an older Bare refuses to load it with an UNSUPPORTED_ENGINE error. bare-assert depends on bare-type directly since v1.3.0. Before that it reached bare-type through bare-inspect.

Mirrors the Node.js assert module.

npm i bare-assert

It provides the same functions as the Node.js 25 assert module, except deepEqual(), notDeepEqual(), the strict namespace, and the Assert class, and it adds notOk(). It also differs from Node.js in these ways:

A generated failure message has the form <actual> <operator> <expected>, not a diff.
An AssertionError has the code 'ASSERTION', not 'ERR_ASSERTION', and no generatedMessage property.
An error that matches a thrown value follows the rules in Matching a thrown error, which differ from Node.js 25 in several cases. An object matches only the own enumerable properties of the thrown value, plus name and message, so it cannot match stack, cause, or an inherited property. An Error is also compared by cause and errors, which Node.js 25 ignores.

Usage

const assert = require('bare-assert')

assert(1 + 1 === 2, 'sum should be correct')

assert.equal(1, 1)
assert.notEqual(1, 2)

assert.deepStrictEqual({ a: [1, 2] }, { a: [1, 2] })
assert.throws(() => JSON.parse('{'), SyntaxError)

API

AssertionError

`AssertionError`

new AssertionError(opts?: {
      message?: string
      actual?: any
      expected?: any
      operator?: string
    })

The error thrown when an assertion fails, which carries the actual, expected, and operator involved. It extends Error. Create one with an optional message, actual, expected, and operator.

Parameters

Parameter	Type	Default	Description
`opts?`	`{ message?: string; actual?: any; expected?: any; operator?: string }`	—	Fields to set on the new error: `message` (defaults to a generated `"<actual> <operator> <expected>"` string), `actual`, `expected`, and `operator`.

`actual: any`

The actual value that failed the assertion.

`expected: any`

The expected value the assertion was checked against.

`operator: string`

The comparison operator used by the assertion that failed, for example '==' or 'strictEqual'.

`name: 'AssertionError'`

The name of the error.

`code: string`

Always 'ASSERTION'. It is not part of the type declarations. Before v1.3.0 reading it returned undefined.

Functions

Every function except ifError() takes an optional message as its last argument. A string replaces the generated message of the AssertionError. An Error instance is thrown as it is, instead of an AssertionError. In throws(), doesNotThrow(), rejects(), and doesNotReject(), the message follows the optional error. A string in second position is the message, and any other value there is the error to match, so an Error instance passed as the message must be the third argument.

`assert(value: any, message?: string | Error): void`

Throw an AssertionError if value is falsy.

Parameters

Parameter	Type	Default	Description
`value`	`any`	—	The value to assert is truthy.
`message?`	`string` \| `Error`	—	Custom message for the thrown error; if an `Error` instance, it is thrown directly instead of an `AssertionError`.

Throws

AssertionError — thrown if value is falsy (unless message is an Error instance, which is thrown instead).

`assert.deepStrictEqual(actual: any, expected: any, message?: string | Error): void`

Throw an AssertionError unless actual and expected are the same value recursively. Added in v1.3.0.

A pair that is not two objects is compared with Object.is(), so NaN equals NaN, 0 differs from -0, and 1 differs from '1'. Functions are compared the same way, so two functions are equal only if they are the same function.
Two objects must have the same prototype. They are then compared by their own enumerable properties, whether keyed by string or symbol, in any order. Non-enumerable properties are ignored. The named properties of an array are compared too, and a hole in a sparse array differs from an undefined element.
Boxed primitives, dates, regular expressions, errors, buffers, ArrayBuffer and SharedArrayBuffer values, DataView values, typed arrays, maps, and sets are compared by what they hold. Typed arrays of different element types are unequal. An error is compared by its name, message, cause, and errors, and by its own enumerable properties.
Map entries and set members are matched in any order, and object keys and members are compared deeply.
Weak maps, weak sets, and promises are equal only to themselves.
Cycles are handled.

Parameters

Parameter	Type	Default	Description
`actual`	`any`	—	The value produced.
`expected`	`any`	—	The value to compare `actual` against.
`message?`	`string` \| `Error`	—	Custom message for the thrown error; if an `Error` instance, it is thrown directly instead of an `AssertionError`.

Throws

AssertionError — thrown if the values are not recursively equal (unless message is an Error instance, which is thrown instead).

`assert.doesNotMatch(actual: string, expected: RegExp, message?: string | Error): void`

Throw an AssertionError unless actual is a string that does not match the expected regular expression. A value that is not a string also throws. Added in v1.3.0.

Parameters

Parameter	Type	Default	Description
`actual`	`string`	—	The string to test.
`expected`	`RegExp`	—	The regular expression that `actual` must not match.
`message?`	`string` \| `Error`	—	Custom message for the thrown error; if an `Error` instance, it is thrown directly instead of an `AssertionError`.

Throws

AssertionError — thrown if actual is not a string or matches expected (unless message is an Error instance, which is thrown instead).

`assert.doesNotReject(fn: (() => Promise<unknown>) | Promise<unknown>, message?: string | Error): Promise<void>`

Overloads:

assert.doesNotReject(fn: (() => Promise<unknown>) | Promise<unknown>, message?: string | Error): Promise<void>
assert.doesNotReject(fn: (() => Promise<unknown>) | Promise<unknown>, error: ((err: unknown) => boolean) | RegExp | Error | object, message?: string | Error): Promise<void>

Reject with an AssertionError if fn rejects. With error, only a reason that matches error is turned into an AssertionError, and any other reason is passed on unchanged, with one exception that Matching a thrown error describes. The returned promise settles once the assertion has been made, so it must be awaited. Added in v1.3.0.

Parameters

Parameter	Type	Default	Description
`fn`	`() => Promise<unknown>` \| `Promise<unknown>`	—	The promise to await, or a function returning one. A function that throws synchronously does not count as a rejection: the returned promise rejects with the error it threw.
`error?`	`(err: unknown) => boolean` \| `RegExp` \| `Error` \| `object`	—	What the rejection reason is checked against. See Matching a thrown error.
`message?`	`string` \| `Error`	—	Custom message for the error; if an `Error` instance, it is used directly instead of an `AssertionError`.

Returns

A promise that resolves once the assertion has passed, and rejects with an AssertionError if fn rejects. With error, it rejects with an AssertionError only if the reason matches error.

`assert.doesNotThrow(fn: () => unknown, message?: string | Error): void`

Overloads:

assert.doesNotThrow(fn: () => unknown, message?: string | Error): void
assert.doesNotThrow(fn: () => unknown, error: ((err: unknown) => boolean) | RegExp | Error | object, message?: string | Error): void

Throw an AssertionError if fn throws. With error, a thrown value that does not match error is re-thrown as it is, with one exception that Matching a thrown error describes. If a message is also given, any thrown value throws an AssertionError with that message, whether it matches error or not. Added in v1.3.0.

Parameters

Parameter	Type	Default	Description
`fn`	`() => unknown`	—	The function to call.
`error?`	`(err: unknown) => boolean` \| `RegExp` \| `Error` \| `object`	—	What the thrown value is checked against. See Matching a thrown error.
`message?`	`string` \| `Error`	—	Custom message for the thrown error; if an `Error` instance, it is thrown directly instead of an `AssertionError`.

Throws

AssertionError — thrown if fn throws, except in the case below (unless message is an Error instance, which is thrown instead).
The thrown value itself — re-thrown if error is given, the thrown value does not match it, and no message is given.

`assert.equal(actual: any, expected: any, message?: string | Error): void`

Throw an AssertionError unless actual and expected are loosely equal (==), with NaN treated as equal to NaN.

Parameters

Parameter	Type	Default	Description
`actual`	`any`	—	The value produced.
`expected`	`any`	—	The value to compare `actual` against.
`message?`	`string` \| `Error`	—	Custom message for the thrown error; if an `Error` instance, it is thrown directly instead of an `AssertionError`.

Throws

AssertionError — thrown if the values are not loosely equal (unless message is an Error instance, which is thrown instead).

`assert.fail(message?: string | Error): never`

Throw an AssertionError unconditionally, with the operator 'fail'. Added in v1.1.0.

Parameters

Parameter	Type	Default	Description
`message?`	`string` \| `Error`	`'Failed'`	Custom message for the thrown error; if an `Error` instance, it is thrown directly instead of an `AssertionError`.

Throws

AssertionError — always thrown (unless message is an Error instance, which is thrown instead).

`assert.ifError(actual: any): void`

Throw an AssertionError unless actual is null or undefined. Any other value throws, including 0 and ''. Added in v1.3.0.

Parameters

Parameter	Type	Default	Description
`actual`	`any`	—	The value to assert is `null` or `undefined`.

Throws

AssertionError — thrown if actual is neither null nor undefined, with the message ifError got <actual> and actual set on the error.

`assert.match(actual: string, expected: RegExp, message?: string | Error): void`

Throw an AssertionError unless actual is a string that matches the expected regular expression. A value that is not a string also throws. Added in v1.3.0.

Parameters

Parameter	Type	Default	Description
`actual`	`string`	—	The string to test.
`expected`	`RegExp`	—	The regular expression that `actual` must match.
`message?`	`string` \| `Error`	—	Custom message for the thrown error; if an `Error` instance, it is thrown directly instead of an `AssertionError`.

Throws

AssertionError — thrown if actual is not a string or does not match expected (unless message is an Error instance, which is thrown instead).

`assert.notDeepStrictEqual(actual: any, expected: any, message?: string | Error): void`

Throw an AssertionError unless actual and expected are different values recursively, as determined by the same comparison deepStrictEqual() uses. Added in v1.3.0.

Parameters

Parameter	Type	Default	Description
`actual`	`any`	—	The value produced.
`expected`	`any`	—	The value to compare `actual` against.
`message?`	`string` \| `Error`	—	Custom message for the thrown error; if an `Error` instance, it is thrown directly instead of an `AssertionError`.

Throws

AssertionError — thrown if the values are recursively equal (unless message is an Error instance, which is thrown instead).

`assert.notEqual(actual: any, expected: any, message?: string | Error): void`

Throw an AssertionError unless actual and expected are loosely unequal (!=), with NaN treated as equal to NaN.

Parameters

Parameter	Type	Default	Description
`actual`	`any`	—	The value produced.
`expected`	`any`	—	The value to compare `actual` against.
`message?`	`string` \| `Error`	—	Custom message for the thrown error; if an `Error` instance, it is thrown directly instead of an `AssertionError`.

Throws

AssertionError — thrown if the values are loosely equal (unless message is an Error instance, which is thrown instead).

`assert.notOk(value: any, message?: string | Error): void`

Throw an AssertionError if value is truthy. Added in v1.2.0.

Parameters

Parameter	Type	Default	Description
`value`	`any`	—	The value to assert is falsy.
`message?`	`string` \| `Error`	—	Custom message for the thrown error; if an `Error` instance, it is thrown directly instead of an `AssertionError`.

Throws

AssertionError — thrown if value is truthy (unless message is an Error instance, which is thrown instead).

`assert.notStrictEqual(actual: any, expected: any, message?: string | Error): void`

Throw an AssertionError unless actual and expected are different values according to Object.is(), which treats NaN as equal to NaN and 0 as distinct from -0.

Parameters

Parameter	Type	Default	Description
`actual`	`any`	—	The value produced.
`expected`	`any`	—	The value to compare `actual` against.
`message?`	`string` \| `Error`	—	Custom message for the thrown error; if an `Error` instance, it is thrown directly instead of an `AssertionError`.

Throws

AssertionError — thrown if the values are the same value (unless message is an Error instance, which is thrown instead).

`assert.ok(value: any, message?: string | Error): void`

Throw an AssertionError if value is falsy.

Parameters

Parameter	Type	Default	Description
`value`	`any`	—	The value to assert is truthy.
`message?`	`string` \| `Error`	—	Custom message for the thrown error; if an `Error` instance, it is thrown directly instead of an `AssertionError`.

Throws

AssertionError — thrown if value is falsy (unless message is an Error instance, which is thrown instead).

`assert.partialDeepStrictEqual(actual: any, expected: any, message?: string | Error): void`

Throw an AssertionError unless expected is contained in actual: every part of expected must be found in actual with a partially equal value, and actual may hold more. Added in v1.3.0.

Objects are compared by kind, not prototype, so a class instance and a plain object that have the same properties can be equal. Every own enumerable property of expected must be in actual, and that includes the named properties of an array. An array and an object are never equal, and neither are a Map and a Set.
The items of an array in expected must appear in actual in the same order, though not next to each other, and each item of actual can match at most one item of expected. [1, 2, 3, 4] contains [1, 3] but not [3, 1], and [1, 2, 3] does not contain [1, 1].
Each map entry and set member in expected must be matched by a different entry or member of actual, in any order. The values and members are compared partially too.
The bytes of a typed array, buffer, ArrayBuffer, SharedArrayBuffer, or DataView in expected must appear in actual in the same order, though not next to each other. Typed arrays of different element types are unequal.
Primitives are compared with Object.is(), so 0 and -0 are unequal. Dates and regular expressions must be equal, and weak maps, weak sets, and promises are equal only to themselves.
An error is compared by name, message, cause, and errors, and by its own enumerable properties. Of the four, a property that is missing or undefined on the expected error, and an empty message, are not compared. A cause that the expected error has must be on the actual error as well, even if it is undefined.
Cycles are handled.

Parameters

Parameter	Type	Default	Description
`actual`	`any`	—	The value produced.
`expected`	`any`	—	The value to compare `actual` against.
`message?`	`string` \| `Error`	—	Custom message for the thrown error; if an `Error` instance, it is thrown directly instead of an `AssertionError`.

Throws

AssertionError — thrown if the values are not partially equal (unless message is an Error instance, which is thrown instead).

`assert.rejects(fn: (() => Promise<unknown>) | Promise<unknown>, message?: string | Error): Promise<void>`

Overloads:

assert.rejects(fn: (() => Promise<unknown>) | Promise<unknown>, message?: string | Error): Promise<void>
assert.rejects(fn: (() => Promise<unknown>) | Promise<unknown>, error: ((err: unknown) => boolean) | RegExp | Error | object, message?: string | Error): Promise<void>

Reject with an AssertionError unless fn rejects, and, with error, unless the reason matches error. The returned promise settles once the assertion has been made, so it must be awaited. Added in v1.3.0.

Parameters

Parameter	Type	Default	Description
`fn`	`() => Promise<unknown>` \| `Promise<unknown>`	—	The promise to await, or a function returning one. A function that throws synchronously does not count as a rejection: the returned promise rejects with the error it threw.
`error?`	`(err: unknown) => boolean` \| `RegExp` \| `Error` \| `object`	—	What the rejection reason must match. See Matching a thrown error.
`message?`	`string` \| `Error`	`'Executed'`	Custom message for the error; if an `Error` instance, it is used directly instead of an `AssertionError`. The default applies when nothing was rejected.

Returns

A promise that resolves once the assertion has passed, and rejects with an AssertionError if fn does not reject, or rejects with a reason that does not match error.

`assert.strictEqual(actual: any, expected: any, message?: string | Error): void`

Throw an AssertionError unless actual and expected are the same value according to Object.is(), which treats NaN as equal to NaN and 0 as distinct from -0.

Parameters

Parameter	Type	Default	Description
`actual`	`any`	—	The value produced.
`expected`	`any`	—	The value to compare `actual` against.
`message?`	`string` \| `Error`	—	Custom message for the thrown error; if an `Error` instance, it is thrown directly instead of an `AssertionError`.

Throws

AssertionError — thrown if the values are not the same value (unless message is an Error instance, which is thrown instead).

`assert.throws(fn: () => unknown, message?: string | Error): void`

Overloads:

assert.throws(fn: () => unknown, message?: string | Error): void
assert.throws(fn: () => unknown, error: ((err: unknown) => boolean) | RegExp | Error | object, message?: string | Error): void

Throw an AssertionError unless fn throws, and, with error, unless the thrown value matches error. Added in v1.3.0.

assert.throws(() => JSON.parse('{'), SyntaxError)
assert.throws(() => JSON.parse('{'), /^SyntaxError/)
assert.throws(() => JSON.parse('{'), { name: 'SyntaxError' })

Parameters

Parameter	Type	Default	Description
`fn`	`() => unknown`	—	The function to call.
`error?`	`(err: unknown) => boolean` \| `RegExp` \| `Error` \| `object`	—	What the thrown value must match. See Matching a thrown error.
`message?`	`string` \| `Error`	`'Executed'`	Custom message for the thrown error; if an `Error` instance, it is thrown directly instead of an `AssertionError`. The default applies when nothing was thrown.

Throws

AssertionError — thrown if fn does not throw, or throws something that does not match error (unless message is an Error instance, which is thrown instead). When the thrown value does not match, actual is that value and expected is error. When nothing was thrown, both are undefined.

Matching a thrown error

throws(), doesNotThrow(), rejects(), and doesNotReject() take an optional error that says which thrown value or rejection reason they apply to. It is one of the following.

`error`	A thrown value matches when
A function	It is an instance of the function, which is checked only if the function has a `prototype`. Failing that, calling the function with the thrown value returns exactly `true`, so a truthy value such as `1` does not match.
A `RegExp`	The pattern matches the string form of the thrown value, such as `TypeError: boom`.
An `Error`	It has the same `name`, `message`, `cause`, and `errors`, and has a `cause` if and only if the `Error` has one. It also has each own enumerable property of the `Error`, with an equal value. The prototype is not compared, and the thrown value may have more properties.
An object, other than a function, a `RegExp`, or an `Error`	Each property named on the object is an own enumerable property of the thrown value, or is `name` or `message`, and has an equal value. A string property can be matched by a `RegExp`. Other values are compared as `deepStrictEqual()` compares them. The `stack` of an error, and a `cause` set through the `Error` constructor, are not enumerable, so an object cannot match them.

A function that the thrown value is not an instance of is called as a predicate. Calling a class without new throws, so a class that the thrown value is not an instance of fails the assertion with the message of that error. If the function that is called throws and no message was given, the assertion fails with an AssertionError that has the message of the error it threw. This holds in doesNotThrow() and doesNotReject() too, where it replaces the re-throwing of a value that does not match.

An Error or an object needs the thrown value to be an object. If the thrown value is a primitive, such as a string or a number, the comparison throws a TypeError of its own instead of failing with an AssertionError. Use a function or a RegExp to match a primitive.

bare-assert

Usage

API

AssertionError

`AssertionError`

`actual: any`

`expected: any`

`operator: string`

`name: 'AssertionError'`

`code: string`

Functions

`assert(value: any, message?: string | Error): void`

`assert.deepStrictEqual(actual: any, expected: any, message?: string | Error): void`

`assert.doesNotMatch(actual: string, expected: RegExp, message?: string | Error): void`

`assert.doesNotReject(fn: (() => Promise<unknown>) | Promise<unknown>, message?: string | Error): Promise<void>`

`assert.doesNotThrow(fn: () => unknown, message?: string | Error): void`

`assert.equal(actual: any, expected: any, message?: string | Error): void`

`assert.fail(message?: string | Error): never`

`assert.ifError(actual: any): void`

`assert.match(actual: string, expected: RegExp, message?: string | Error): void`

`assert.notDeepStrictEqual(actual: any, expected: any, message?: string | Error): void`

`assert.notEqual(actual: any, expected: any, message?: string | Error): void`

`assert.notOk(value: any, message?: string | Error): void`

`assert.notStrictEqual(actual: any, expected: any, message?: string | Error): void`

`assert.ok(value: any, message?: string | Error): void`

`assert.partialDeepStrictEqual(actual: any, expected: any, message?: string | Error): void`

`assert.rejects(fn: (() => Promise<unknown>) | Promise<unknown>, message?: string | Error): Promise<void>`

`assert.strictEqual(actual: any, expected: any, message?: string | Error): void`

`assert.throws(fn: () => unknown, message?: string | Error): void`

Matching a thrown error

See also

On this page