or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-expect--js

BDD style assertions for node and the browser.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/expect.js@0.3.x

To install, run

npx @tessl/cli install tessl/npm-expect--js@0.3.0

index.mddocs/

Expect.js

Expect.js is a minimalistic BDD (Behavior-Driven Development) assertion toolkit for JavaScript that works in both Node.js and browser environments. It provides a clean, chainable API for writing test assertions with expressive syntax similar to natural language.

Package Information

  • Package Name: expect.js
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install expect.js
  • Repository: https://github.com/LearnBoost/expect.js

Core Imports

Node.js:

const expect = require('expect.js');

Browser (via script tag):

<script src="expect.js"></script>
<!-- Global 'expect' function is now available -->

Basic Usage

const expect = require('expect.js');

// Basic equality assertions
expect(5).to.be(5);
expect('hello').to.be.a('string');
expect([1, 2, 3]).to.have.length(3);

// Negation
expect(false).to.not.be(true);
expect('foo').to.not.be.empty();

// Property and containment checks
expect({ name: 'Alice', age: 30 }).to.have.property('name');
expect([1, 2, 3]).to.contain(2);
expect('hello world').to.contain('world');

Architecture

Expect.js is built around a simple but powerful architecture:

  • Entry Point: The expect() function creates Assertion instances
  • Chainable Interface: Assertion methods return this for fluent API
  • Language Chains: Properties like .to, .be, .have for readable syntax
  • Negation Support: .not property inverts assertion logic
  • Cross-Environment: Works identically in Node.js and browsers

Capabilities

Core Factory Function

Creates assertion instances for chaining methods.

function expect(obj: any): Assertion;

Static Properties and Methods

Version information and utility functions.

expect.version: string;
expect.Assertion: constructor;
expect.stringify(obj: any): string;
expect.eql(actual: any, expected: any): boolean;

Basic Assertions

Core assertion methods for common testing scenarios.

// Truthiness assertion
Assertion.prototype.ok(): Assertion;

// Strict equality assertion (===)
Assertion.prototype.be(value: any): Assertion;
Assertion.prototype.equal(value: any): Assertion;

// Deep equality assertion
Assertion.prototype.eql(value: any): Assertion;

// Explicit failure
Assertion.prototype.fail(message?: string): Assertion;

Usage Examples:

expect(true).to.be.ok();
expect(5).to.be(5);
expect({ a: 1 }).to.eql({ a: 1 });
expect().to.fail('Custom failure message');

Type Assertions

Methods for checking data types and instances.

// Type checking (supports 'array', 'regexp', 'object', and standard typeof types)
Assertion.prototype.a(type: string | constructor): Assertion;
Assertion.prototype.an(type: string | constructor): Assertion;

Usage Examples:

expect(5).to.be.a('number');
expect([]).to.be.an('array');
expect(new Date()).to.be.a(Date);
expect(/test/).to.be.a('regexp');

Numeric Comparisons

Methods for comparing numeric values.

// Greater than comparison
Assertion.prototype.above(n: number): Assertion;
Assertion.prototype.greaterThan(n: number): Assertion;

// Less than comparison
Assertion.prototype.below(n: number): Assertion;
Assertion.prototype.lessThan(n: number): Assertion;

// Range comparison (inclusive)
Assertion.prototype.within(start: number, finish: number): Assertion;

Usage Examples:

expect(10).to.be.above(5);
expect(3).to.be.below(10);
expect(7).to.be.within(5, 10);

Collection and Property Assertions

Methods for working with arrays, objects, and strings.

// Empty check for arrays, objects, or strings
Assertion.prototype.empty(): Assertion;

// Length assertion
Assertion.prototype.length(n: number): Assertion;

// Property existence and value checking
Assertion.prototype.property(name: string, value?: any): Assertion;

// Key existence checking  
Assertion.prototype.key(...keys: string[]): Assertion;
Assertion.prototype.keys(...keys: string[]): Assertion;

// Containment checking
Assertion.prototype.contain(obj: any): Assertion;
Assertion.prototype.string(obj: any): Assertion;

Usage Examples:

expect([]).to.be.empty();
expect('hello').to.have.length(5);
expect({ name: 'Alice' }).to.have.property('name');
expect({ name: 'Alice', age: 30 }).to.have.keys(['name', 'age']);
expect({ name: 'Alice', age: 30 }).to.have.keys('name', 'age');
expect([1, 2, 3]).to.contain(2);
expect('hello world').to.contain('hello');

Pattern Matching

Method for regular expression matching.

// Regular expression matching
Assertion.prototype.match(regexp: RegExp): Assertion;

Usage Examples:

expect('hello123').to.match(/\d+/);
expect('test@email.com').to.match(/\w+@\w+\.\w+/);

Function Testing

Methods for testing function behavior and exceptions.

// Create function wrapper with bound arguments
Assertion.prototype.withArgs(...args: any[]): Assertion;

// Exception throwing assertions
Assertion.prototype.throwError(fn?: function | RegExp): Assertion;
Assertion.prototype.throwException(fn?: function | RegExp): Assertion;

Usage Examples:

function divide(a, b) {
  if (b === 0) throw new Error('Division by zero');
  return a / b;
}

expect(divide).withArgs(10, 2).to.not.throwException();
expect(divide).withArgs(10, 0).to.throwException(/Division by zero/);

expect(() => { throw new Error('test'); }).to.throwError();

Language Chains and Modifiers

Properties that enable fluent, readable assertion syntax.

// Language chains (no-op properties for readability)
Assertion.prototype.to: Assertion;
Assertion.prototype.be: Assertion;
Assertion.prototype.have: Assertion;
Assertion.prototype.include: Assertion;

// Negation modifier
Assertion.prototype.not: Assertion;

// Property ownership modifier (for hasOwnProperty checks)
Assertion.prototype.own: Assertion;

// Strict matching modifier (for exact key matching)
Assertion.prototype.only: Assertion;

// Continuation chain (available after assertion completion)
Assertion.prototype.and: Assertion;

Usage Examples:

expect(obj).to.not.be.empty();
expect(obj).to.have.own.property('key');
expect(obj).to.only.have.keys(['a', 'b']);
expect(obj).to.have.property('name').and.be.a('string');

Error Handling

When assertions fail, expect.js throws Error objects with descriptive messages. Error objects may include:

  • message: Descriptive error message
  • actual: The actual value being tested
  • expected: The expected value (when applicable)
  • showDiff: Boolean flag indicating if diff should be displayed
// Example error messages:
// "expected 'test' to equal true"
// "expected { a: 1 } to have property 'b'"
// "expected 5 to be above 10"

Cross-Environment Compatibility

Expect.js works identically across environments:

  • Node.js: require('expect.js')
  • Browser: Global expect when script is loaded
  • Cross-browser: IE6+, Firefox, Safari, Chrome, Opera
  • No dependencies: Self-contained with polyfills for older environments

Types

interface Assertion {
  // Core assertions
  ok(): Assertion;
  be(value: any): Assertion;
  equal(value: any): Assertion;
  eql(value: any): Assertion;
  
  // Type assertions
  a(type: string | constructor): Assertion;
  an(type: string | constructor): Assertion;
  
  // Numeric comparisons
  above(n: number): Assertion;
  greaterThan(n: number): Assertion;
  below(n: number): Assertion;
  lessThan(n: number): Assertion;
  within(start: number, finish: number): Assertion;
  
  // Collections and properties
  empty(): Assertion;
  length(n: number): Assertion;
  property(name: string, value?: any): Assertion;
  key(...keys: string[]): Assertion;
  keys(...keys: string[]): Assertion;
  contain(obj: any): Assertion;
  string(obj: any): Assertion;
  
  // Pattern matching
  match(regexp: RegExp): Assertion;
  
  // Function testing
  withArgs(...args: any[]): Assertion;
  throwError(fn?: function | RegExp): Assertion;
  throwException(fn?: function | RegExp): Assertion;
  
  // Explicit failure
  fail(message?: string): Assertion;
  
  // Language chains and modifiers
  to: Assertion;
  be: Assertion;
  have: Assertion;
  include: Assertion;
  not: Assertion;
  own: Assertion;
  only: Assertion;
  and: Assertion;
}