When does heavy use of any() argument matchers weaken a test suite, and how do you decide between permissive matchers, eq()/argThat specificity, and ArgumentCaptor at scale?

## The core tension Every argument matcher sits on a slider between two failure modes: - **Over-matching** (too permissive, e.g. `any()` everywhere): the test stays green even when the production code does the wrong thing. The assertion becomes **vacuous** — it can't fail for the reason the test exists. The suite gives false confidence. - **Over-specifying** (too strict, e.g. `eq()` on every incidental field including timestamps and framework objects): the test breaks on harmless refactors, generating churn and training the team to ignore or weaken tests. Good matcher choice is choosing the right point on that slider **per argument**, driven by what the test is actually asserting. ## Why over-matching is the more dangerous side A brittle test is annoying but **visible** — it fails loudly and someone fixes it. A vacuous test is **invisible**: it passes forever, including when a bug is introduced. `verify(orderRepo).save(any())` confirms only that *some* save happened, not that the *correct* order was saved. A whole suite written this way can have high coverage and near-zero defect-detection power. So the bias at scale should be: relax deliberately, not reflexively. ## Intent-driven specificity (the decision rule) For each argument of a verified/stubbed call, ask: **does this argument carry the behaviour this test asserts?** - **Yes** → pin it. `eq(value)` for a single value; `argThat(...)` for a field condition; a captor if you need several assertions or good diagnostics. - **No, it's incidental** (a generated timestamp, a correlation id, a framework `Pageable`) → relax it with `any...()` so the test doesn't break when that incidental value changes. This keeps each test **sensitive to its own subject** and **robust to everything else** — the property you want from a maintainable suite. ## Choosing the tool at scale | Situation | Prefer | |---|---| | One value defines correctness | `eq(value)` | | A field/condition defines correctness | `argThat(predicate)` (add custom `toString` for diagnostics) | | Several fields matter, or you need readable failures, or to inspect a sequence | `ArgumentCaptor` + assertion library | | Argument is genuinely irrelevant | `any...()` / `nullable()` | For a large suite, `ArgumentCaptor` plus AssertJ tends to age best for complex objects: the assertions read like specifications and the failures are self-explaining, whereas dozens of inline `argThat` lambdas become hard to scan and debug. ## Guardrails to enforce the discipline - **Strict stubs**: `MockitoExtension`/`MockitoJUnitRunner.Strict` (or `mockito-junit-jupiter` strictness, default STRICT_STUBS) flags **unnecessary stubbings** and argument mismatches. This catches over-broad stubs that never fire and mixing mistakes early, instead of letting them mask gaps. - **Avoid blanket `any()` defaults** in shared test helpers/`@Before` setups — a permissive stub created centrally silently weakens every test that relies on it. - **Review for vacuity**: in code review, treat `verify(x).method(any())` on a call whose *arguments are the point* as a smell; ask what the test would catch if the implementation passed garbage. - **Prefer behaviour assertions over interaction assertions** where possible — sometimes asserting the *observable result* is stronger and less matcher-dependent than verifying the exact mock interaction. ## Worked example of the trade-off ```java // Vacuous: passes even if the wrong amount/currency is charged verify(gateway).charge(any(), any(), any()); // Intent-driven: amount & currency are the point; the idempotency key is incidental verify(gateway).charge(eq(amount), eq(Currency.USD), any(String.class)); // Or capture when several fields matter and diagnostics help ArgumentCaptor<ChargeRequest> c = ArgumentCaptor.forClass(ChargeRequest.class); verify(gateway).charge(c.capture()); assertThat(c.getValue().amount()).isEqualByComparingTo(amount); assertThat(c.getValue().currency()).isEqualTo(Currency.USD); ``` ## Bottom line Matchers are a sensitivity dial. The senior move is per-argument intent: specific on what the test asserts, lenient on the incidental, captors when objects are rich — and strict-stubs turned on so the suite tells you when a matcher is too broad or unused rather than quietly losing its teeth.