it-should — fluent assertions for TypeScript

@artstesh/it-should is a small fluent assertion toolkit for TypeScript tests. It fills the gaps left by the built-in expect matchers: array ordering, occurrence counting, object comparison with per-field rules, date accuracy, and more — expressed as readable chains.

import { should } from '@artstesh/it-should';

should().array(students).ordered({ by: (e) => e?.age });

If the service under test returns an unsorted collection, the test fails with Elements aren't ordered. — no hand-written sorting logic, no fixtures with exactly two records arranged to make a naive comparison work.

How it reads

A chain starts with should(), picks a verifier for the type under test, and applies checks. Every check either passes silently or throws a ShouldError with a readable message, so the assertions drop straight into any test runner — Jest, Jasmine, Mocha, Vitest, or plain code.

Verifier	Covers
`should().number(x)`	comparisons, ranges, approximate equality — Numbers
`should().string(x)`	content, case, length, occurrence counting — Strings
`should().array(x)`	membership, counts, uniqueness, ordering — Arrays
`should().date(x)`	before/after, ranges, accuracy-aware equality — Dates
`should().objects(x, y)`	deep comparison with per-field rules — Objects
`should().true(x)`/`.false(x)`	boolean-context checks — General Assertions

Every chain supports not to invert the following checks, and defined() to guard against null/undefined — see Concepts.

Where to start

Installation and Quick Start — up and running in a minute.
Concepts — the chain model, negation, and the null/undefined rules.
Cookbook — copy-paste recipes for common test scenarios.
API reference — every signature on one shelf.

Project

MIT-licensed; the documentation describes the current v2 line (TypeScript ^5) — see Versions for the supported lines and the changelog.

02 сентября 2026