MockK's `match { }` lets you supply an arbitrary predicate as an argument matcher. What are the mechanics and the downsides, and how do you keep predicate-based matching debuggable?

## Mechanics Inside a recording block, `match<T> { predicate }` stores a function-backed matcher in that argument slot. Matching then works like this: - **During stubbing**, when the production code calls the mocked method, MockK evaluates the stored matchers against the incoming arguments to select an answer. Your lambda runs there. - **During verification**, MockK evaluates the matchers against *every recorded call* to that method to count matches. Your lambda runs once per candidate call. So the predicate is not evaluated once, and it is not evaluated at the point where you wrote it. It is a callback into your test's logic executed inside MockK's matching loop. That leads to a set of practical requirements: 1. **Pure.** A predicate that mutates test state, increments a counter or logs will run an unpredictable number of times. 2. **Cheap.** It may run for every recorded call on that method. 3. **Total.** It should return false rather than throw on unexpected shapes. Throwing from a matcher aborts matching in a way that reads like a MockK internal failure rather than a test assertion. 4. **Null-aware where needed.** `match { }` provides a non-null value to the lambda; nullable parameters use `matchNullable { }`, whose lambda receives the nullable value. Suspending predicates use `coMatch { }`. ## The diagnostics problem Built-in matchers describe themselves. When `eq(7)` fails, the report shows what was expected and what arrived, and a reader instantly sees the difference. When `range(1, 10)` fails, the bound is visible. A lambda has no such description — MockK can print that a matcher rejected the argument, but not the condition inside your closure. So a failing predicate-matched stub produces the least actionable failure in the whole catalog: > no answer found for: Service(#1).send(Order(id=42, total=0)) and you are left reading the test source to work out which of the three clauses inside the lambda failed. This is the core argument against making `match { }` a habit. It is the universal fallback, and universal fallbacks erode the quality of failure output across a suite. ## Techniques that keep it debuggable **Prefer a specific matcher.** `more(0)`, `range(1, 10)`, `ofType<Retryable>()`, `isNull(inverse = true)` each say something a reader and a failure message can use. A lambda that merely re-implements one of these is a strict downgrade. **Name the predicate.** Extract it as an extension on MockK's matcher scope so call sites read like a domain assertion: ```kotlin fun MockKMatcherScope.orderFor(customerId: Long) = match<Order> { it.customerId == customerId } every { repo.save(orderFor(42)) } returns Unit ``` The failure message still shows an opaque matcher, but the *test source* now names the intent, which is where the reader ends up anyway. **Keep it to what the test claims.** A predicate checking six fields will fail for a change in any of them, including fields irrelevant to this test. One or two fields keeps it both readable and robust. **Compose instead of conjoining in a lambda.** `and(more(0), less(100))`, `or(isNull(), ofType<Draft>())` and `not(m)` build compound matchers out of self-describing parts, so the description survives. **Capture when the assertion is real.** If what you want is a rich assertion on the argument — several fields, a nested structure, an assertion library's diff — capturing the argument and asserting after the fact gives a proper failure message. Matching answers "which call", asserting answers "was it right"; a predicate that is really an assertion in disguise belongs on the assertion side. ## When `match { }` is genuinely the right choice - Selecting which stub applies among several calls that differ by a computed condition — the matcher *is* dispatch logic, not an assertion. - Types with no usable `equals` where only one field identifies the call. - Cross-field conditions no built-in matcher expresses ("start before end", "currency matches the account"). In all of those the predicate is doing something the catalog cannot, and the readability cost is paid for. ## A checklist for review - Could a built-in matcher express this? Then use it. - Does the lambda mutate anything or do IO? Then fix it. - Does it check more fields than the test claims? Then narrow it. - Is it really an assertion? Then capture and assert instead. - Does it appear more than twice? Then give it a name.