or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

assert-interface.mdconfiguration.mdcore-assertions.mdexpect-interface.mdindex.mdplugin-system.mdshould-interface.mdutilities.md
tile.json

tessl/npm-chai

BDD/TDD assertion library for Node.js and browser testing frameworks.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/chai@6.0.x

To install, run

npx @tessl/cli install tessl/npm-chai@6.0.0

index.mddocs/

Chai

Chai is a comprehensive BDD/TDD assertion library for Node.js and browsers that enables expressive and readable tests. It provides three distinct assertion styles (assert, expect, and should) with a rich API for validating values, objects, arrays, functions, and promises. Chai supports both synchronous and asynchronous testing patterns with extensive error messages and a robust plugin architecture.

Package Information

  • Package Name: chai
  • Package Type: npm
  • Language: JavaScript (ES modules)
  • Installation: npm install chai

Core Imports

import { expect, assert, should } from "chai";

For CommonJS:

const { expect, assert, should } = require("chai");

Individual style imports:

import { expect } from "chai";  // BDD expect style
import { assert } from "chai";  // TDD assert style
import { should } from "chai";  // BDD should style (requires activation)

Global registration (for browser/testing frameworks):

import "chai/register-expect.js";  // Sets global.expect
import "chai/register-assert.js";  // Sets global.assert
import "chai/register-should.js";  // Sets global.should

Basic Usage

import { expect, assert, should } from "chai";

// Expect style (most popular)
expect(4).to.equal(4);
expect({ name: 'Alice' }).to.have.property('name', 'Alice');
expect([1, 2, 3]).to.include(2);

// Assert style (similar to Node.js assert)
assert.equal(4, 4);
assert.property({ name: 'Alice' }, 'name');
assert.include([1, 2, 3], 2);

// Should style (extends Object.prototype)
should(); // Activates should
(4).should.equal(4);
({ name: 'Alice' }).should.have.property('name', 'Alice');
([1, 2, 3]).should.include(2);

Architecture

Chai is built around several key components:

  • Assertion Styles: Three different APIs (expect, assert, should) providing the same functionality
  • Chainable Interface: Fluent assertion syntax with language chains for readability
  • Plugin System: Extensible architecture allowing custom assertion methods and properties
  • Error Handling: Detailed assertion failures with configurable stack traces and diffs
  • Utility System: Internal utilities for type checking, property access, and deep equality
  • Configuration: Global settings for behavior customization

Capabilities

Expect Interface

BDD-style assertions using the expect() function with chainable syntax for expressive test statements.

function expect(value: any, message?: string): Assertion;
expect.fail(actual?: any, expected?: any, message?: string, operator?: string): never;

Expect Interface

Assert Interface

TDD-style assertions providing standalone functions similar to Node.js assert module for direct validation.

function assert(expression: any, message?: string): void;
assert.fail(actual?: any, expected?: any, message?: string, operator?: string): never;
assert.equal(actual: any, expected: any, message?: string): void;
assert.strictEqual(actual: any, expected: any, message?: string): void;
assert.deepEqual(actual: any, expected: any, message?: string): void;

Assert Interface

Should Interface

BDD-style assertions that extend Object.prototype with should property for natural language assertions.

function should(): void;
should.fail(actual?: any, expected?: any, message?: string, operator?: string): never;
should.equal(actual: any, expected: any, message?: string): void;
should.exist(value: any, message?: string): void;

Should Interface

Core Assertion Methods

Chainable assertion methods for property testing, type validation, comparison operations, and collection analysis.

interface Assertion {
  // Language chains
  to: Assertion;
  be: Assertion;
  been: Assertion;
  is: Assertion;
  that: Assertion;
  which: Assertion;
  and: Assertion;
  has: Assertion;
  have: Assertion;
  with: Assertion;
  at: Assertion;
  of: Assertion;
  same: Assertion;
  but: Assertion;
  does: Assertion;
  still: Assertion;
  also: Assertion;

  // Modifiers
  not: Assertion;
  deep: Assertion;
  nested: Assertion;
  own: Assertion;
  ordered: Assertion;
  any: Assertion;
  all: Assertion;

  // Comparison methods
  equal(value: any): Assertion;
  eql(value: any): Assertion;
  above(value: number): Assertion;
  least(value: number): Assertion;
  below(value: number): Assertion;
  most(value: number): Assertion;
  within(start: number, finish: number): Assertion;
  closeTo(expected: number, delta: number): Assertion;
}

Core Assertions

Configuration System

Global configuration options for customizing assertion behavior, error reporting, proxy usage, and deep equality comparison.

interface Config {
  includeStack: boolean;
  showDiff: boolean;
  truncateThreshold: number;
  useProxy: boolean;
  proxyExcludedKeys: string[];
  deepEqual: ((expected: any, actual: any) => boolean) | null;
}

Configuration

Plugin System

Extensible architecture for adding custom assertion methods, properties, and functionality to all assertion styles.

function use(plugin: (chai: ChaiStatic, utils: ChaiUtils) => void): ChaiStatic;

Plugin System

Utility Functions

Internal utility functions for type detection, property manipulation, flag management, and deep equality comparison.

interface ChaiUtils {
  flag(assertion: Assertion, key: string, value?: any): any;
  test(assertion: Assertion, expression: boolean): void;
  type(obj: any): string;
  getMessage(assertion: Assertion, args: any[]): string;
  getActual(assertion: Assertion, args: any[]): any;
  inspect(obj: any, showHidden?: boolean, depth?: number, colors?: boolean): string;
  eql(a: any, b: any): boolean;
}

Utilities

Types

class Assertion {
  constructor(obj: any, msg?: string, ssfi?: Function, lockSsfi?: boolean);
  
  static addProperty(name: string, fn: (this: Assertion) => void): void;
  static addMethod(name: string, fn: (this: Assertion, ...args: any[]) => void): void;
  static addChainableMethod(
    name: string, 
    method: (this: Assertion, ...args: any[]) => void,
    chainingBehavior?: (this: Assertion) => void
  ): void;
  static overwriteProperty(name: string, fn: (this: Assertion, _super: () => void) => void): void;
  static overwriteMethod(name: string, fn: (this: Assertion, _super: (...args: any[]) => void, ...args: any[]) => void): void;
  static overwriteChainableMethod(
    name: string,
    method: (this: Assertion, _super: (...args: any[]) => void, ...args: any[]) => void,
    chainingBehavior?: (this: Assertion, _super: () => void) => void
  ): void;
}

class AssertionError extends Error {
  constructor(message?: string, props?: object, ssf?: Function);
  actual: any;
  expected: any;
  operator: string;
  showDiff: boolean;
}

interface ChaiStatic {
  expect: ExpectStatic;
  assert: AssertStatic;
  should(): Should;
  Should: ShouldStatic;
  use(fn: (chai: ChaiStatic, utils: ChaiUtils) => void): ChaiStatic;
  util: ChaiUtils;
  config: Config;
  AssertionError: typeof AssertionError;
  Assertion: typeof Assertion;
}