@nevware21/tripwire

JavaScript/TypeScript Test support utilities and assertion library

Modules

Tripwire Core

Documentation

• Why tripwire - what is automatic across node, browser and worker, what is fast, how it compares with Mocha, Karma, Jest and Vitest, and when not to use it
• Performance - the runner’s mechanisms, measured benchmark results against Mocha and Karma, and how to reproduce them; Performance History charts every recorded run over time
• Core Assertion Typedoc
• For AI agents: AGENTS.md and llms.txt

Feature Highlights

Feature	Functions
Type Checking	isObject, isArray, isString, isNumber, isBoolean, isFunction, isNull, isUndefined, isNaN, isFinite, typeOf, isInstanceOf, exists
Equality & Comparison	equal, strictEqual, deepEqual, deepStrictEqual, notDeepStrictEqual, closeTo, isAbove, isBelow, isWithin, isAtLeast, isAtMost
Property Assertions	hasProperty, hasOwnProperty, hasDeepProperty, nestedProperty, deepNestedProperty
Collection Operations	includes, sameMembers, includeMembers, lengthOf, sizeOf
Change Tracking	changes, increases, decreases - See Change/Increase/Decrease Assertions Guide
Error Testing	throws, doesNotThrow, rejects, doesNotReject
Chaining	and continues a chain after a called assertion (expect(5).is.number().and.is.above(1)); or passes when any of the given clause functions passes (expect(5).or(e => e.is.string(), e => e.is.number()))
Extensibility	createExprAdapter, addAssertFunc - See Expression Adapter Guide

Quick Start

Install the package:

npm install @nevware21/tripwire --save-dev

Recommended version range:

{
  "devDependencies": {
    "@nevware21/tripwire": ">= 0.1.8 < 2.x"
  }
}

Basic Usage

import { assert, expect } from '@nevware21/tripwire';

// Assert style - quick and direct
assert.equal(1 + 1, 2);
assert.isString("hello");
assert.deepEqual({ a: 1 }, { a: 1 });

// Expect style - fluent and readable
expect(1 + 1).to.equal(2);
expect("hello").to.be.a.string;
expect({ a: 1 }).to.deep.equal({ a: 1 });

Migration Guides

One guide per framework you are leaving. The Mocha, Karma and Jest guides end with a machine-readable JSON block for automated migrations.

• Migrating from Mocha / ts-mocha - the test runner: flags, .mocharc to .tripwirerc, globals, what has no equivalent
• Migrating from Karma - karma.conf.js field mapping, browser and worker targets, coverage, launch modes
• Migrating from Jest or Vitest - matcher and config mapping, what has no equivalent (mocking, snapshots, parallel workers)
• Migrating from Chai - assertion mapping, and the @nevware21/tripwire-chai shim as a staged option
• Migrating from Node.js Native Assert - assertion mapping, including the deepStrictEqual difference

Migrating from Node.js Native Assert

Migrating from Node.js Assert to Tripwire - Complete guide for migrating from Node.js native assert module

Key differences to be aware of: deepStrictEqual and notDeepStrictEqual match Node’s structural, type-strict behaviour (since v0.1.7 and v0.2.0 respectively), so they carry over unchanged. Two methods differ:

- assert.doesNotMatch(text, /pattern/);
+ assert.notMatch(text, /pattern/);

  await assert.rejects(fn, /error pattern/);  // unchanged

See the full migration guide for complete details and examples.

Test Runner, CLI & Configuration

Test Runner, CLI & Configuration Guide - Running the tripwire CLI against node/browser/worker targets, every CLI flag and .tripwirerc config field, file discovery, coverage, and hook failures (--fail-on-hook).

npx tripwire --target browser --reporter spec,xunit "test/**/*.test.ts"

Related:

• Test Reporters - all 14 built-in reporters with sample output for each (spec, list, min, dot, progress, landing, nyan, tap, xunit, json, json-stream, doc, markdown, cargo), how to select and combine them, the per-reporter options, and writing a custom one
• Migrating from Karma - moving a Karma suite to the tripwire runner: karma.conf.js field mapping, browser and worker targets with no plugins to assemble, coverage, launch modes for other browsers and devices, and a machine-readable summary
• Migrating from Mocha - moving a Mocha (or ts-mocha) suite to the tripwire runner: flag and config mapping, what has no equivalent, a step-by-step checklist, and a machine-readable summary for automated migrations
• Runner Troubleshooting - known issues and their fixes, including opting in to the global describe/it names and the duplicate-global TypeScript errors that opting in alongside @types/mocha, @types/jest or @types/jasmine produces
• Test Suite API - the describe/it/hook definition API the runner executes (Mocha, Jasmine and TDD styles, .only/.skip, filters, deterministic test IDs)
• Test Execution Flow - how suites, tests and hooks are executed, when promises are created, timeout and hook failure handling, and the opt-in runner metrics

Shim Chai

Documentation

Chai Shim Typedoc

Quick Start

Install the package:

npm install @nevware21/tripwire-chai --save-dev

Recommended version range:

{
  "devDependencies": {
    "@nevware21/tripwire-chai": ">= 0.1.8 < 2.x"
  }
}

Migration from Chai

Migrating from Chai to Tripwire - Guide for upgrading from Chai.js

Step 1: Update your imports

- import { assert } from 'chai';
+ import { assert } from '@nevware21/tripwire-chai';

Step 2: Run your tests

Most assert.* functions should work immediately.

Step 3: Update error message tests (if needed)

Error messages differ from Chai - use regex for flexibility:

- assert.throws(() => fn(), "exact chai message");
+ assert.throws(() => fn(), /error message/);

What’s Supported

The shim implements the Chai v5.x assert API including:

• Basic assertions: equal, strictEqual, deepEqual, isOk, isTrue, etc.
• Type checking: isObject, isArray, isString, isNumber, isBoolean, isFunction, etc.
• Comparisons: isAbove, isAtLeast, isBelow, isAtMost, closeTo
• Properties: property, deepProperty, nestedProperty, ownProperty with value checks
• Collections: include, deepInclude, members, sameMembers, keys
• Changes: changes, increases, decreases with delta tracking
• Errors: throws, doesNotThrow, rejects, doesNotReject
• Object state: isExtensible, isSealed, isFrozen, isEmpty

What’s NOT Supported

• expect API - Use core tripwire instead
• should API - No plans to implement
• Plugins - use() function not available

When to Use Core Tripwire

Consider migrating to @nevware21/tripwire for:

• Better error messages
• Fluent expect syntax
• New features and improvements
• Long-term maintenance