@txmo-dev/midas-assertions

Zero-dependency fluent assertion library for TypeScript/JavaScript. Mirrors the .NET Midas.Assertions API.
Built by Midas Path Software Solutions — MIT-licensed forever.

Why?

FluentAssertions for .NET went commercial. We built our own — then ported it to TypeScript so our full-stack teams use the same assertion API on both sides.

Installation

npm install @txmo-dev/midas-assertions

Quick Start

import { should, shouldStr, shouldNum, shouldArr, shouldFn, shouldAsync } from '@txmo-dev/midas-assertions';

// Object assertions
should(result).notBeNull();
should(result).be(expected);
should(result).beInstanceOf(PatientDto);

// String assertions
shouldStr(name).notBeNullOrWhiteSpace();
shouldStr(name).startWith("Dr.");
shouldStr(name).contain("Smith");
shouldStr(name).matchWildcard("Dr.*Smith*");

// Number assertions
shouldNum(age).beGreaterThan(0);
shouldNum(balance).beCloseTo(100, 0.01);
shouldNum(count).bePositive();

// Boolean assertions
should(isActive).beTrue();
should(isDeleted).beFalse();

// Date assertions
should(createdAt).beBefore(new Date());
should(expiresAt).beAfter(new Date());

// Array assertions
shouldArr(patients).notBeEmpty();
shouldArr(patients).haveCount(5);
shouldArr(patients).contain("Kwame");
shouldArr(callOrder).containInOrder("save", "notify", "log");
shouldArr(tags).onlyHaveUniqueItems();

// Sync exception assertions
shouldFn(() => dangerousCall()).throw("*not allowed*");

// Async exception assertions
await shouldAsync(async () => await riskyCall()).throwAsync("*expired*");

API

Entry Points

| Function | Returns | Use When | |---|---|---| | should(value) | Auto-detected assertion type | General use — infers type at runtime | | shouldBool(value) | BooleanAssertions | Boolean values | | shouldNum(value) | NumberAssertions | Numbers | | shouldStr(value) | StringAssertions | Strings | | shouldDate(value) | DateAssertions | Dates | | shouldArr(value) | ArrayAssertions | Arrays | | shouldFn(fn) | FunctionAssertions | Sync functions (for throw testing) | | shouldAsync(fn) | AsyncFunctionAssertions | Async functions (for throwAsync testing) | | shouldObj(value) | ObjectAssertions | Force object assertions |

Assertion Classes

| Class | Key Methods | |---|---| | ObjectAssertions | be, notBe, beNull, beUndefined, beNullish, beTruthy, beFalsy, beInstanceOf, beTypeOf, deepEqual | | BooleanAssertions | beTrue, beFalse, be | | NumberAssertions | be, beGreaterThan, beLessThan, beGreaterThanOrEqual, beLessThanOrEqual, bePositive, beNegative, beCloseTo, beNaN, beFinite | | StringAssertions | be, beEmpty, contain, startWith, endWith, matchRegex, matchWildcard, haveLength, notBeNullOrWhiteSpace | | DateAssertions | be, beAfter, beBefore, beOnOrAfter, beOnOrBefore, beCloseTo | | ArrayAssertions | beEmpty, haveCount, contain, containWhere, containSingle, containInOrder, onlyHaveUniqueItems, allSatisfy, satisfyRespectively, beEquivalentTo, equal | | FunctionAssertions | throw, notThrow | | AsyncFunctionAssertions | throwAsync, notThrowAsync | | ExceptionAssertions | withMessage + .and / .which chaining |

Chaining

All assertions return AndConstraint for fluent chaining:

shouldStr(name).notBeNullOrWhiteSpace().and.startWith("Dr.").and.haveLength(10);

Exception assertions return ExceptionAssertions for message matching:

shouldFn(() => badCall()).throw().withMessage("*invalid*");

Wildcard Matching

matchWildcard and throw("*pattern*") use * as a wildcard (matches any characters):

shouldStr(msg).matchWildcard("*error*occurred*");
shouldFn(() => fail()).throw("*not found*");

Test Coverage

• 216 tests passing
• 99.71% statement coverage
• 100% function coverage

Target

• ES2020+
• Node.js >= 18
• Zero dependencies

License

MIT © Midas Path Software Solutions