Quick Start

Three minutes, five chains: numbers, strings, arrays with ordering, dates, and objects. 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.

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.

02 сентября 2026