Concepts

Four rules explain every chain in it-should. Learn them once and no check will surprise you.

Rule 1: a chain is a typed sentence

should() returns the VerifierFactory. Its methods — number, string, array, date, objects, true, false — create a verifier for that kind of value. Check methods return the verifier, so checks chain; each check either passes silently or throws a ShouldError with a readable message:

should().number(5).greater(3).less(10);   // passes
should().number(5).greater(10);           // throws ShouldError

There is no .and() glue and no assertion object to keep — the chain is the assertion.

Rule 2: `not` inverts everything that follows

not is a property on every verifier. Once used, every later check in the chain expects the negated outcome (the failure messages flip accordingly):

should().string('Any content').not.equals('any content'); // ok
should().array([1, 2, 3]).not.contain(5);                 // ok
should().number(5).not.positive();                        // throws '5 is positive, but should not.'

Rule 3: `null`/`undefined` always fail — even with `not`

Before any real check runs, the verifier asserts the entry is defined. null and undefined throw The entry is not defined. regardless of not, because "is 5 greater than null" has no sensible negative. The one deliberate exception:

should().string(null).defined();        // throws — the entry is not defined
should().string(null).not.defined();    // ok — the one legal negation of null

Check a nullable value with defined() first, or assert its negated definedness when absence is the expectation.

Rule 4: failure messages are part of the contract

Messages are short, stable sentences produced per check family — for example Elements aren't ordered. (arrays), Objects have different 'name': "a" & "b". (objects, with the property path), or The entry is not defined. (the definedness guard). Tests should assert behavior, not parse messages — but when a message changes, that is an observable change of the library (see Versions).

Where each kind of value lives

You are checking…	Chapter
numbers, ranges, precision	Numbers
strings, occurrences, case	Strings
dates and accuracy	Dates
arrays: membership, counts, uniqueness, ordering	Arrays, Array Ordering
two objects, field by field	Objects
truthiness and definedness	General Assertions

Sharp edges — negation quirks, whitespace definitions, reference equality traps — are collected in Caveats; recommended habits in Best Practices.

02 сентября 2026