Chai — BDD/TDD Assertion Library for Node.js

Introduction

Chai is an assertion library for JavaScript that pairs with any test runner. It offers three distinct assertion styles: BDD-flavored expect and should chains, and a classic TDD assert interface. Chai's plugin architecture extends its vocabulary with domain-specific matchers for HTTP, promises, dates, and more.

What Chai Does

• Provides expect(value).to.equal(...) chains for BDD-style assertions
• Offers assert.strictEqual() for TDD-style assertions in the same library
• Ships with deep equality, type checking, property inspection, and exception assertions
• Supports chainable language helpers: .to, .be, .have, .that, .which
• Extensible via plugins for sinon matchers, HTTP responses, promises, and dates

Architecture Overview

Chai builds assertion chains using a proxy-based object that records property accesses as flags (negation, deep equality, inclusion). When a terminal assertion method like .equal() is called, it reads the accumulated flags and evaluates the check. Failed assertions throw an AssertionError with a diff-friendly message. The plugin API lets third parties register new chainable properties and methods on the assertion prototype.

Self-Hosting & Configuration

• Install via npm and import the style you prefer: expect, should, or assert
• Use chai-as-promised for promise assertions: expect(promise).to.eventually.equal(...)
• Pair with sinon-chai for mock verification assertions: expect(spy).to.have.been.calledOnce
• Configure truncateThreshold to control how much of large objects appears in error messages
• Works in Node.js and browsers via bundlers or the UMD build

Key Features

• Three assertion styles in one library let teams pick the syntax they prefer
• Chainable natural-language API produces readable test code
• Deep equality comparison handles nested objects, arrays, and special types
• Plugin ecosystem adds matchers for HTTP, dates, DOM elements, and more
• Detailed error messages show expected vs. actual with diffs

Comparison with Similar Tools

• Node.js assert — built-in but minimal; Chai adds richer matchers and better messages
• Jest expect — bundled with Jest; Chai is runner-agnostic and works with Mocha, Vitest, or any framework
• Unexpected — extensible assertion library; Chai has broader community adoption and more plugins
• should.js — BDD-only; Chai offers three styles and is more actively maintained
• power-assert — zero-API assertions with detailed diffs; Chai provides a richer vocabulary

FAQ

Q: Which assertion style should I use? A: expect is the most popular choice. It does not modify Object.prototype unlike should, and reads more naturally than assert.

Q: Does Chai work with TypeScript? A: Yes. Install @types/chai for type definitions, or use Chai 5+ which ships built-in TypeScript support.

Q: Can I use Chai with Jest? A: Technically yes, but Jest ships its own expect and mixing both can cause confusion. Chai is more commonly used with Mocha or Vitest.

Q: How do I add custom assertions? A: Use chai.use(plugin) where the plugin function receives chai and utils to register new methods on the assertion chain.

Sources

• https://github.com/chaijs/chai
• https://www.chaijs.com/