Quick Start

Three minutes, six chains: numbers, strings, arrays with ordering, dates, objects, and a function call. Every snippet assumes import { should } from '@artstesh/it-should';.

1. A number check

const percent = service.getProgress(); // 0..100

should().number(percent).inRange(0, 100).positive();

Bounds in inRange are exclusive; chainable checks let one line assert several properties.

2. A string check with occurrence counting

should().string('any any content').contains('any');           // at least once
should().string('any any content').contains('any', Times.twice()); // exactly twice

Times helpers (once, twice, exactly(n), moreThan(n), lessThan(n)) turn "contains" into "contains exactly N times". See Strings.

3. The flagship: array ordering

interface Student { name: string; age: number; }

const students: Student[] = studentService.getAll();

should().array(students).ordered({ by: (e) => e?.age });            // ascending by age
should().array(students).ordered({ by: (e) => e?.age, dir: 'desc' }); // descending

On failure the test throws Elements aren't ordered. — the check that motivated the library. Full settings in Array Ordering.

4. A date check with accuracy

should().date('2024-05-06T10:00:00.000Z').equals('2024-05-06T22:15:30.000Z', 'day'); // ok

Dates accept Date instances or ISO strings everywhere; the optional accuracy ('year'… 'millisecond') truncates both sides before comparing. See Dates.

5. Object comparison with a rule

should()
  .objects({ id: 1, name: 'a' }, { id: 1, name: 'A' })
  .rule('name', (a, b) => a.toLowerCase() === b.toLowerCase())
  .equal(); // ok

rule/map/ignoring/compareOnly shape the comparison; equal() runs it. See Objects.

6. A function call that must fail

should().method(() => parser.parse('not json')).throws();

method(fn) invokes the function with the arguments you pass; returns(...) asserts the call completes and hands the produced value back for further chains. See Methods.

Negation and definedness

Any chain can flip meaning with not and guard the entry with defined():

should().string('Any content').not.equals('any content'); // ok (case-sensitive)
should().string(maybeNull).defined();                      // throws if null/undefined

The exact null/undefined rules matter — read Concepts before relying on not with nullable entries.

Next steps

Concepts — the model behind the chains.
Cookbook — recipes for real test scenarios.
API reference — every signature.

16 September 2026