assertion-error

library2.0.1jsnpmunverified

The `assertion-error` package provides standardized `AssertionError` and `AssertionResult` classes, primarily designed for JavaScript and TypeScript test and validation frameworks. As of its current stable version `2.0.1`, it offers a robust way to represent both assertion failures and successes within a consistent `Result` interface. The library maintains a steady, though not rapid, release cadence, with significant updates like the `v2.0.0` rewrite to modern TypeScript and ES6 classes. A key differentiator is the inclusion of `AssertionResult`, which allows functions to explicitly return successful assertion outcomes alongside `AssertionError` for failures, both implementing a common `Result` interface with an `.ok` boolean property. This design streamlines error handling and result checking in testing utilities, providing a more structured approach than relying solely on exceptions. It supports both Node.js and Deno environments.

testing serialization

npm install assertion-error

github ↗package ↗

INSTALL

IMPORT

SIG · ASSERTION-ERROR

assertion-error

testingjavascriptv2.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AssertionError

✓ import { AssertionError } from 'assertion-error'

✗ const AssertionError = require('assertion-error')

Since v2.0.0, the package uses ES6 modules. Direct `require()` access to the class constructor needs `require('assertion-error').AssertionError`.

AssertionResult

✓ import { AssertionResult } from 'assertion-error'

✗ const AssertionResult = require('assertion-error')

The `AssertionResult` class was introduced in v2.0.0 and follows the same ES6 module import pattern as `AssertionError`.

CommonJS access (pre-v2.0.0 or for specific setups)

✓ const AssertionError = require('assertion-error')

✗ import { AssertionError } from 'assertion-error'

Before v2.0.0, the package exported `AssertionError` as the default. For v2.0.0+, CommonJS users should access named exports via `require('assertion-error').AssertionError`.

Demonstrates importing `AssertionError` and `AssertionResult`, creating instances, throwing `AssertionError`, and checking the `.ok` property on results.

import { AssertionError, AssertionResult } from 'assertion-error'; function validateInput(value: unknown): AssertionResult | AssertionError { if (typeof value !== 'string' || value.length === 0) { return new AssertionError('Input must be a non-empty string.', { actual: value, expected: 'non-empty string' }); } return new AssertionResult('Input is valid.', { actual: value, expected: 'non-empty string', ok: true }); } // Example usage: const validResult = validateInput('hello'); console.log(`Valid input check: name='${validResult.name}', ok=${validResult.ok}, toJSON=${JSON.stringify(validResult.toJSON())}`); try { const invalidResult = validateInput(123); if (invalidResult instanceof AssertionError) { throw invalidResult; // Typically you'd throw an AssertionError } } catch (error) { if (error instanceof AssertionError) { console.error(`Caught an AssertionError: message='${error.message}', actual='${error.actual}', expected='${error.expected}', ok=${error.ok}`); } else { console.error('Caught a non-AssertionError:', error); } }

Debug

Known issues

breakingVersion 2.0.0 introduced a complete rewrite to TypeScript and ES6 classes, fundamentally changing the package's internal structure and module export style. This moved from a CJS-first default export to ESM-first named exports.

fix

Update import statements from `const AssertionError = require('assertion-error')` to `import { AssertionError } from 'assertion-error'` for ESM environments. For CommonJS, access the class via `require('assertion-error').AssertionError`.

affects: >=2.0.0

breakingThe `AssertionResult` class was introduced in v2.0.0, providing a companion to `AssertionError` for representing successful assertion outcomes. Both classes now implement a `Result` interface with an `.ok` boolean property.

fix

Adjust code to incorporate `AssertionResult` for explicit success handling where appropriate, and leverage the new `.ok` property for checking assertion outcomes regardless of success or failure.

affects: >=2.0.0

gotchaWhen migrating to v2.0.0+, direct `require('assertion-error')` in CommonJS will no longer return the `AssertionError` constructor directly, as it is now a named export.

fix

In CommonJS environments, ensure you access the constructor as `require('assertion-error').AssertionError` (and `require('assertion-error').AssertionResult`).

affects: >=2.0.0

gotchaThe package explicitly distinguishes between `AssertionError` (an instance of `Error` meant to be thrown) and `AssertionResult` (not an `Error` and meant to be returned). Misunderstanding this distinction can lead to incorrect error handling patterns.

fix

Always throw `AssertionError` instances and catch them in `try...catch` blocks. Return `AssertionResult` instances from functions where a successful (but explicit) assertion outcome is required. Check `instanceof Error` or the `.ok` property to differentiate.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: AssertionError is not a constructor

Attempting to instantiate `require('assertion-error')` directly after upgrading to v2.0.0 or later in a CommonJS environment, where `AssertionError` is now a named export.

fix

Change `new require('assertion-error')` to `new (require('assertion-error').AssertionError)`.

SyntaxError: Named export 'AssertionError' not found (module 'assertion-error')

Attempting to use `import { AssertionError } from 'assertion-error'` in a pure CommonJS environment (e.g., Node.js without `"type": "module"` in `package.json` or a transpiler).

fix

For CommonJS, use `const AssertionError = require('assertion-error').AssertionError;`. If you intend to use ESM, ensure your environment is configured for it (e.g., `"type": "module"` in `package.json`).

Property 'ok' does not exist on type 'AssertionError' (or 'AssertionResult').

Using an older version of `assertion-error` (<2.0.0) which did not include the `.ok` property on its classes, or a TypeScript configuration that isn't picking up the latest type definitions.

fix

Update `assertion-error` to version `2.0.0` or higher. Ensure your `tsconfig.json` is correctly set up to include `node_modules/@types` and that your IDE is picking up the latest type definitions.

Upgrade

Version history

2.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/chaijs/assertion-error ↗

packagehttps://www.npmjs.com/package/assertion-error ↗