expect.js

expect.js is a lightweight BDD-style assertion toolkit originally built by Guillermo Rauch (LearnBoost) as a should.js-inspired alternative that works identically in Node.js and in the browser. It exposes a single global expect() function that wraps a value in a chainable Assertion object, letting tests read as plain English sentences such as expect(result).to.be.an('array') or expect(fn).to.throwException().

Unlike heavier assertion libraries, expect.js has zero runtime dependencies, ships as a single ~1,300-line file, and avoids extending built-in prototypes, making it safe to drop into any test runner (Mocha, Jasmine, or a custom harness) or load directly via a <script> tag for browser-based test suites.

What You Get

• A chainable expect(value).to.be... assertion API covering equality, type checks, truthiness, ranges, and exceptions
• Cross-browser support (IE6+, Firefox, Safari, Chrome, Opera) alongside first-class Node.js usage
• A single, dependency-free source file with no prototype extensions or global shims
• Descriptive failure messages with actual/expected/showDiff metadata for diff-aware test reporters
• Framework-agnostic design that works with Mocha, Jasmine, or any runner that just calls functions and catches thrown errors

Common Use Cases

• Writing BDD-style unit test assertions in a Mocha or Jasmine Node.js test suite
• Asserting DOM state and browser-only behavior in in-browser test pages served over support/
• Replacing heavier assertion libraries in small utility packages that want zero added dependencies
• Testing thrown-exception behavior with regex or callback-based exception matching via throwException()

Under The Hood

Architecture expect.js is a single self-contained IIFE module exposing one entry point, expect(), which wraps a value in a new Assertion instance. The flags object (not, to, be, have, include, only) defines a small grammar, and the Assertion constructor recursively clones prototype methods onto each instance under every applicable flag name, which is how chains like .to.not.have are built at runtime rather than declared statically. Every check funnels through a central assert() helper that throws an Error carrying actual/expected/showDiff metadata on failure. This recursive flag-cloning mechanism is the single load-bearing abstraction in the codebase — the entire fluent chain grammar depends on it.

Tech Stack Written in vanilla ES5 JavaScript with zero runtime dependencies. The only devDependencies are mocha (test runner) and serve (static file server for browser test pages), wired together through a small Makefile (make test, make test-browser). The library ships as a single index.js, consumed via CommonJS module.exports in Node.js or attached to window.expect when loaded directly in a browser via <script>.

Code Quality Tests live in test/expect.js (roughly 570 lines) using Mocha’s describe/it structure, with a local err() helper that invokes a function and asserts the exact thrown error message — giving genuine behavioral coverage of the assertion API itself. There is no TypeScript, no JSDoc type annotations, and no linter or CI configuration present in the repository. Error handling is explicit throughout: assert() throws descriptive Error objects with diff metadata rather than failing silently.

What Makes It Unique expect.js does not introduce novel assertion mechanics — its own README positions it as a smaller, should.js-inspired alternative with incremental API simplifications for browser compatibility. Its distinguishing value is minimalism: no prototype extensions, no shims, a single dependency-free file that behaves identically across old and modern browsers and Node.js alike.