Arrays
should().array(x) verifies arrays: emptiness, length, membership, occurrence counts, uniqueness, and whole-collection equality. Ordering has its own deep-dive: Array Ordering.
Size
should().array([]).empty(); // ok
should().array([1, 2]).length(2); // ok
Membership and counts
should().array([1, 2]).contain(2); // ok
should().array([1, 2]).contain(5); // throws — "The collection doesn't contain the expected element."
should().array([1, 2, 2]).containExactly(2, 2); // ok — exactly two occurrences
should().array([1, 2, 2]).containExactly(1, 2); // throws — found 2, expected 1
Predicate-based variants select the elements by condition instead of value:
should().array([1, 2, 3]).containBy((e) => e! > 2); // ok — at least one matches
should().array([1, 2, 3]).containByExactly(2, (e) => e! > 1); // ok — exactly two match
should().array([1, 2, 3]).containOnly((e) => e! < 10); // ok — every element matches
should().array([1, 2, 3]).containOnly((e) => e! > 1); // throws — 1 does not match
The identifier function
When elements are objects, value comparison is reference comparison and fails even for identical-looking data. Every membership/equality check accepts an optional identifier — a function extracting the comparison key from an element:
interface Student { id: number; name: string; }
const students: Student[] = [{ id: 3, name: 'C' }, { id: 5, name: 'E' }];
should().array(students).contain({ id: 3, name: 'C' }, (e) => e?.id); // ok — matched by id
should().array(students).contain({ id: 3, name: 'C' }); // throws — compared by reference
The same parameter appears on containExactly, equal, equalUnordered, and uniq. For primitives, omit it.
Uniqueness
should().array([1, 5, 7]).uniq(); // ok
should().array([{ id: 3 }, { id: 3 }]).uniq((e) => e?.id); // throws — duplicate id
Whole-collection equality
should().array([1, 2]).equal([1, 2]); // ok — same elements, same order
should().array([1, 2]).equal([2, 1]); // throws — order matters
should().array([1, 2]).equalUnordered([2, 1]); // ok — order ignored
should().array(students).equalUnordered(expected, (e) => e?.id); // objects: give an identifier
Negation
should().array([1, 2, 3]).not.contain(5); // ok
should().array([1, 2, 3]).not.contain(2); // throws — the collection does contain 2
should().array([1, 2]).not.uniq(); // throws — [1, 2] is unique
The null/undefined rules from Concepts apply to every check; a null/undefined array throws The entry is not defined. even under not.
Signatures and messages
02 сентября 2026