# Chai — BDD/TDD Assertion Library for Node.js

> Chai is a flexible assertion library for Node.js and browsers that supports expect, should, and assert styles.

## Install

Save as a script file and run:

# Chai — BDD/TDD Assertion Library for Node.js

## Quick Use
```bash
npm install --save-dev chai
```
```javascript
import { expect } from 'chai';

expect([1, 2, 3]).to.have.lengthOf(3);
expect({ name: 'foo' }).to.have.property('name').that.equals('foo');
expect(() => badFn()).to.throw(Error);
```

## 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/

---
Source: https://tokrepo.com/en/workflows/2774d7ec-4278-11f1-9bc6-00163e2b0d79
Author: Script Depot