{"id":12837,"library":"assertion-error","title":"AssertionError for Test Frameworks","description":"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.","status":"active","version":"2.0.1","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/chaijs/assertion-error","tags":["javascript","test","assertion","assertion-error","typescript"],"install":[{"cmd":"npm install assertion-error","lang":"bash","label":"npm"},{"cmd":"yarn add assertion-error","lang":"bash","label":"yarn"},{"cmd":"pnpm add assertion-error","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v2.0.0, the package uses ES6 modules. Direct `require()` access to the class constructor needs `require('assertion-error').AssertionError`.","wrong":"const AssertionError = require('assertion-error')","symbol":"AssertionError","correct":"import { AssertionError } from 'assertion-error'"},{"note":"The `AssertionResult` class was introduced in v2.0.0 and follows the same ES6 module import pattern as `AssertionError`.","wrong":"const AssertionResult = require('assertion-error')","symbol":"AssertionResult","correct":"import { AssertionResult } from 'assertion-error'"},{"note":"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`.","wrong":"import { AssertionError } from 'assertion-error'","symbol":"CommonJS access (pre-v2.0.0 or for specific setups)","correct":"const AssertionError = require('assertion-error')"}],"quickstart":{"code":"import { AssertionError, AssertionResult } from 'assertion-error';\n\nfunction validateInput(value: unknown): AssertionResult | AssertionError {\n  if (typeof value !== 'string' || value.length === 0) {\n    return new AssertionError('Input must be a non-empty string.', { actual: value, expected: 'non-empty string' });\n  }\n  return new AssertionResult('Input is valid.', { actual: value, expected: 'non-empty string', ok: true });\n}\n\n// Example usage:\nconst validResult = validateInput('hello');\nconsole.log(`Valid input check: name='${validResult.name}', ok=${validResult.ok}, toJSON=${JSON.stringify(validResult.toJSON())}`);\n\ntry {\n  const invalidResult = validateInput(123);\n  if (invalidResult instanceof AssertionError) {\n    throw invalidResult; // Typically you'd throw an AssertionError\n  }\n} catch (error) {\n  if (error instanceof AssertionError) {\n    console.error(`Caught an AssertionError: message='${error.message}', actual='${error.actual}', expected='${error.expected}', ok=${error.ok}`);\n  } else {\n    console.error('Caught a non-AssertionError:', error);\n  }\n}\n","lang":"typescript","description":"Demonstrates importing `AssertionError` and `AssertionResult`, creating instances, throwing `AssertionError`, and checking the `.ok` property on results."},"warnings":[{"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`.","message":"Version 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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"The `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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"In CommonJS environments, ensure you access the constructor as `require('assertion-error').AssertionError` (and `require('assertion-error').AssertionResult`).","message":"When 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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `new require('assertion-error')` to `new (require('assertion-error').AssertionError)`.","cause":"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.","error":"TypeError: AssertionError is not a constructor"},{"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`).","cause":"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).","error":"SyntaxError: Named export 'AssertionError' not found (module 'assertion-error')"},{"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.","cause":"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.","error":"Property 'ok' does not exist on type 'AssertionError' (or 'AssertionResult')."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null}