or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-interface.mdconfiguration.mdexception-execution.mdindex.mdtest-assertions.mdtest-control.mdtest-creation.md
tile.json

tessl/npm-brittle

A TAP test runner built for modern times with comprehensive assertion methods and async support

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/brittle@3.18.x

To install, run

npx @tessl/cli install tessl/npm-brittle@3.18.0

index.mddocs/

Brittle

Brittle is a modern TAP (Test Anything Protocol) test runner designed for JavaScript/Node.js applications with support for multiple runtime environments including Node.js, Bare, and Pear. It offers both classic callback-style and inverted promise-based test patterns, comprehensive assertion methods for value comparison, object comparison, truthiness checking, and exception handling, advanced features like test planning, timeouts, teardown handlers, subtests, stealth mode, and coverage reporting, and flexible execution options including solo mode for focused testing, skip/todo functionality, and configurable timeouts and bail options.

Package Information

  • Package Name: brittle
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install brittle

Core Imports

import test from "brittle";

For named imports:

import { test, solo, skip, hook, todo, configure, pause, resume, stealth, createTypedArray } from "brittle";

CommonJS:

const test = require("brittle");
const { solo, skip, hook, todo, configure, pause, resume, stealth, createTypedArray } = require("brittle");

Basic Usage

import test from "brittle";

// Basic test with callback
test("addition works", (t) => {
  t.is(2 + 2, 4, "2 + 2 equals 4");
  t.pass("test passed");
});

// Inverted test (promise-based)
const t = test("async test");
t.is(await someAsyncFunction(), "expected result");
t.end();

// Test with plan
test("planned test", (t) => {
  t.plan(2);
  t.ok(true, "first assertion");
  t.is(1, 1, "second assertion");
});

Architecture

Brittle is built around several key components:

  • Test Creation Functions: Multiple ways to create tests (test, solo, skip, hook, todo, stealth)
  • Test Instance API: Rich assertion methods and utilities available on test objects
  • Runner System: Internal TAP-compliant test execution engine
  • Configuration System: Global and per-test configuration options
  • Promise Interface: Full thenable support for all tests
  • CLI Tools: Runtime-specific binary executables

Capabilities

Test Creation

Core test creation functionality providing various test types and execution modes for comprehensive testing workflows.

function test(name?: string, options?: TestOptions, callback?: (t: Test) => void): Test | Promise<boolean>;
function solo(name?: string, options?: TestOptions, callback?: (t: Test) => void): Test | Promise<boolean>;
function skip(name?: string, options?: TestOptions, callback?: (t: Test) => void): Test | Promise<boolean>;
function hook(name?: string, options?: TestOptions, callback?: (t: Test) => void): Test | Promise<boolean>;
function todo(name?: string, options?: TestOptions, callback?: (t: Test) => void): Test | Promise<boolean>;
function stealth(name?: string, options?: TestOptions, callback?: (t: Test) => void): Test | Promise<boolean>;

Test Creation

Test Assertions

Comprehensive assertion methods for all types of value testing, comparison, and validation.

interface Test {
  // Basic assertions
  pass(message?: string): void;
  fail(message?: string): void;
  ok(value: any, message?: string): void;
  absent(value: any, message?: string): void;
  
  // Equality assertions
  is(actual: any, expected: any, message?: string): void;
  not(actual: any, expected: any, message?: string): void;
  
  // Deep comparison
  alike(actual: any, expected: any, message?: string): void;
  unlike(actual: any, expected: any, message?: string): void;
}

Test Assertions

Exception and Execution Testing

Testing for exceptions, promise rejections, and execution outcomes with detailed error matching.

interface Test {
  exception(fn: Function | Promise, expectedError?: any, message?: string): void;
  execution(fn: Function | Promise, message?: string): Promise<number>;
}

Exception and Execution Testing

Test Control and Utilities

Test lifecycle management, subtests, planning, timeouts, and utility functions.

interface Test {
  test(name?: string, options?: TestOptions, callback?: (t: Test) => void): Test | Promise<boolean>;
  plan(n: number): void;
  end(): void;
  timeout(ms: number): void;
  teardown(fn: Function, options?: TeardownOptions): void;
  comment(...message: any[]): void;
  tmp(): Promise<string>;
}

Test Control and Utilities

Configuration and Global Control

Global test configuration, execution control, and runtime settings.

function configure(options: ConfigurationOptions): void;
function pause(): void;
function resume(): void;

interface ConfigurationOptions {
  timeout?: number;
  bail?: boolean;
  solo?: boolean;
  source?: boolean;
  unstealth?: boolean;
  coverage?: boolean | string;
}

Configuration and Global Control

CLI Interface

Command-line interface tools for running tests across different runtime environments.

// Available binary executables:
// brittle / brittle-node - Node.js runtime
// brittle-bare - Bare runtime  
// brittle-pear - Pear runtime

// CLI Flags:
// --solo, -s - Engage solo mode
// --bail, -b - Bail out on first assert failure
// --coverage, -c - Turn on coverage
// --timeout, -t <timeout> - Set test timeout in milliseconds

CLI Interface

Types

interface TestOptions {
  timeout?: number;
  solo?: boolean;
  hook?: boolean;
  skip?: boolean;
  todo?: boolean;
  stealth?: boolean;
}

interface TeardownOptions {
  order?: number;
  force?: boolean;
}

class Test {
  name: string;
  passes: number;
  fails: number;
  assertions: number;
  
  // Promise interface
  then(onFulfilled?: Function, onRejected?: Function): Promise<boolean>;
  catch(onRejected?: Function): Promise<boolean>;
  finally(onFinally?: Function): Promise<boolean>;
}

/**
 * Create typed array for snapshot testing (used internally by snapshots)
 * @param buffer - Buffer or typed array data
 * @returns Uint8Array for snapshot comparison
 */
function createTypedArray(buffer: Buffer | TypedArray): Uint8Array;