Caveats
The sharp edges — each with the reason and the workaround. The general null/undefined rules live in Concepts; here are the non-obvious cases.
not does not rescue null/undefined (except for defined)
Every check runs the definedness guard first, and the guard ignores not: should().string(null).not.equals('x') throws The entry is not defined. — it does not pass. The only legal negation on a nullable entry is not.defined().
equalsIgnoreCase skips the definedness guard
Unlike its case-sensitive sibling, equalsIgnoreCase compares undefined?.toUpperCase() === undefined?.toUpperCase()-style expressions: two null/undefined sides pass instead of throwing. Check defined() first when the entry may be absent.
whitespace() means spaces only
The check removes space characters and tests for emptiness — '' and ' ' pass; strings with tabs ('\t'), newlines, or non-breaking spaces do not. Roll your own with match(/^\s*$/) if you need full Unicode whitespace (see Strings).
match() is a partial match
It delegates to String.match: /order/ matches 'invoice-order-42'. Anchor with ^ and $ when the entire string must match.
Unparseable date strings are not null
new Date('garbage') is an Invalid Date, not null — the definedness guard passes and the comparison fails cryptically. Pass ISO strings or Date instances; treat everything else as a test bug.
Reference equality for objects without an identifier
All array checks (and objects().equal() for nested objects without rules) fall back to ===. Identical-looking object literals in two places are still different references. Pass the identifier function, or a rule for nested fields (Arrays, Objects).
Spaces-only strings and case checks under not
upperCased()/lowerCased() treat a spaces-only string as "nothing to compare" for the negation path — edge cases around ' ' may behave unexpectedly in not chains. If a nullable/spacey input is possible, assert defined() and content first.
containExactly counts occurrences, not positions
containExactly(2, x) means "x occurs exactly 2 times" — position in the array is irrelevant. Combine with equal (order-sensitive) when placement matters.
ShouldError is not exported
The error type ships in the package but is not re-exported from the root — catch it as Error or match on message if a test must intercept an assertion failure itself.
Property count must match in objects()
objects(x, y) fails with The objects has different number of properties. when the sides differ in field count — even if all compared fields match. Align with map (renames), ignoring, or compareOnly (Objects).