Kotest's MatcherResult carries a passed flag plus two messages — failureMessage and negatedFailureMessage. Under what circumstances does each message reach the developer, and what breaks if you write them carelessly?

## What a Kotest matcher actually returns Kotest's assertion core is deliberately tiny. `Matcher<in T>` has one method: `test(value: T): MatcherResult`. A matcher **never throws** — it *reports*. That single design choice is what lets matchers be composed, inverted, adapted and collected, because a value can be examined without control flow leaving the function. `MatcherResult` carries three things: - `passed()` — did the rule hold for this value? - `failureMessage()` — the text to show when the rule was **expected to hold** and did not. - `negatedFailureMessage()` — the text to show when the rule was **expected not to hold** and it did. ## Two call paths select the message The infix entry points are what turn a result into a failure: - `value should matcher` — if `passed()` is `false`, raise an assertion failure carrying `failureMessage()`. - `value shouldNot matcher` — if `passed()` is `true`, raise an assertion failure carrying `negatedFailureMessage()`. Every `shouldXxx` / `shouldNotXxx` extension you write on top of a matcher ultimately delegates to one of those two. That is why a single matcher powers both directions of an assertion and why the negated message is mandatory work, not an optional nicety: it is the *only* output a `shouldNot` failure ever produces. A useful mental check while writing a matcher: read each message aloud prefixed with "the test failed because …". `failureMessage` completes that sentence when the property is absent; `negatedFailureMessage` completes it when the property is unexpectedly present. ## Lazy messages in Kotest 5 In Kotest 5 the companion factory is `MatcherResult(passed: Boolean, failureMessageFn: () -> String, negatedFailureMessageFn: () -> String)` — the messages are **lambdas**, evaluated only if the corresponding failure is raised. Kotest 4 took eager `String` arguments, meaning every passing assertion still paid to build two strings. Consequences in 5.x: - Expensive rendering (formatting a big list, computing a diff, serialising a domain object) costs nothing on the happy path, so you can afford *rich* messages. - The lambdas capture the value by reference. If the matcher is applied to mutable state that changes before the failure is rendered, the message can describe the state at throw time rather than at test time. Capture an immutable snapshot when that matters. ## What a good message contains A failure message must be readable by someone who did not write the matcher and cannot see the source. Include: 1. the **actual** value (rendered, not just its class), 2. the **expected** property in plain words, 3. enough discriminator to find the offending element in a collection. So `"\"$value\" should be a valid ISO-8601 date"` rather than `"invalid"`. The negated form is normally the same sentence with the polarity flipped: `"\"$value\" should not be a valid ISO-8601 date"`. ## The failure modes interviewers probe - **Copy-paste polarity bug** — the negated slot repeats the positive text. Every `shouldNot` failure then claims the opposite of what happened, and it is invisible until someone actually writes a negative assertion, often months later. Always test both directions of a custom matcher. - **Message omits the actual value** — the report says a rule was violated but not by what, forcing a debugger session for what should have been a glance at CI output. - **Throwing inside the matcher** — raising `AssertionError` directly from `test()` bypasses the `should` / `shouldNot` plumbing. That plumbing is where Kotest attaches contextual clues and where failures are collected instead of thrown in soft-assertion blocks, so a self-throwing matcher silently opts out of both and can never be negated or composed. - **Side effects in `test()`** — composition and inversion may call `test` more than once on the same value; a matcher that mutates or consumes (e.g. reads a stream) misbehaves under `and` / `or`. ## Richer results Beyond the plain result, Kotest offers `ComparableMatcherResult`, which carries the same passed flag and message lambdas **plus** the actual and expected values as strings. Tooling that understands comparison failures can then render a side-by-side diff instead of a single line — worth reaching for when your matcher compares large structures where "these two blobs differ" is useless without a diff. ## Bottom line The contract is: report, don't throw; fill in both polarities honestly; put the value in the text; and in Kotest 5 lean on the lazy lambdas to make messages generous rather than terse.