Matchers & Assertions

Kotest's shouldBe does not simply call equals. It dispatches on runtime type first: arrays are compared by contents rather than by reference, iterables and maps element-wise with a positional diff, data classes with per-field failure reporting. Everything else falls back to equals.

failureMessage is shown when the matcher is used positively (should / a shouldX extension) and does not pass. negatedFailureMessage is shown when it is used negatively (shouldNot) and it does pass. Copying the positive text into the negated slot makes failures report the opposite of reality.

It returns the caught exception, already typed as T. Bind it and assert on message, cause or custom fields. Use shouldThrowUnit<T> when the block's last expression is Unit, because plain shouldThrow expects a block returning Any?.

Inside the block Kotest switches its error collector to soft mode, so matcher failures are recorded instead of thrown; at the end it throws one MultiAssertionError listing them all. Only failures routed through Kotest's collector are aggregated — non-assertion exceptions abort the block immediately.

shouldBe asserts the two values compare equal (equals, or Kotest's type-aware comparison). shouldBeSameInstanceAs asserts they are literally the same object in memory — a reference check like ===. Two equal data class instances pass the first and fail the second.

Kotest's shouldMatch requires the entire string to match the regex — it is a full match, not a search. To assert that a pattern occurs somewhere inside a string, pass a Regex to shouldContain, which looks for a match anywhere. shouldStartWith/shouldEndWith are literal, case-sensitive; shouldContainIgnoringCase is a case-insensitive substring check.

shouldBeInstanceOf<T>() passes when the value is a T or any subtype. shouldBeTypeOf<T>() requires the runtime class to be exactly T, so a subclass fails. Neither can check generic type arguments, because those are erased at runtime.

shouldNot negates at the call site: it fails when the matcher passes, printing negatedFailureMessage. invert() negates the matcher itself, returning a new Matcher whose passed flag is flipped and whose two messages are swapped — needed when you must hand a negated matcher to something that takes a Matcher value.

They attach context to any failure raised inside their block: the clue text is prepended to the matcher's own message. Nested clues stack — every active clue appears, outermost first — and asClue is the form that uses the receiver object itself as the clue.

Decide from the contract, not from the flake. If ordering is guaranteed (an explicit ORDER BY), the flake is a real bug — keep shouldContainExactly and fix the source. If ordering is genuinely undefined, switch to shouldContainExactlyInAnyOrder, which still pins size and duplicates. Never fall back to size-plus-contains.

shouldBe ultimately uses equals, which is the wrong test in those cases. Use plusOrMinus for floating point tolerance, shouldBeEqualComparingTo for BigDecimal (compareTo ignores scale), and the reflective matchers shouldBeEqualToIgnoringFields or shouldBeEqualToUsingFields for objects with noisy fields.

They return the value narrowed to the asserted type — T for shouldBeInstanceOf, the non-null T for shouldNotBeNull — and they carry Kotlin contracts so the original variable also smart-casts afterwards. That replaces as casts and !! with assertions that fail with real messages.

Both combinators short-circuit and return one sub-result verbatim. and returns the first failure, else the second result; or returns the first pass, else the last failure. So you see one side's message, never an assembled "A and B" sentence — and the value may be tested twice.

contramap adapts a matcher's input type: Matcher<String>.contramap { o: Order -> o.ref } yields a Matcher<Order> that applies the same rule to the projected field. neverNullMatcher wraps a non-null test into a Matcher<T?> that fails with a message on null instead of throwing NPE.

shouldThrow<T> accepts T or any subtype; shouldThrowExactly<T> requires the runtime class to be exactly T and fails on subtypes. If the block throws an AssertionError that isn't the expected type, Kotest rethrows it as-is so a nested assertion failure isn't masked as a wrong-exception report.

One function per rule returning a Matcher<T>, named as a predicate phrase (beShippable()). Expose paired shouldX / shouldNotX extensions that delegate to should / shouldNot and return the receiver. Never throw from inside a matcher, keep matchers pure, and review failure wording like production copy.

shouldBeSorted checks natural ascending order on Comparable elements and allows equal neighbours. shouldBeSortedWith takes a custom comparator. Monotonically increasing allows ties; strictly increasing forbids them. Traps: empty and single-element collections pass trivially, and sortedness alone does not pin the contents.

Aggregate independent observations of one state (fields of a response, elements of a collection) and fail fast on preconditions and dependent assertions. Add clues wherever a failure could come from more than one input. Judge by whether one defect produces one report line.