Argument Matchers

## What a mock and a stub are In unit testing, a **mock** is a fake implementation of a dependency (an interface or class) that records the calls made to it and returns whatever you tell it to. **Mockito** is the most common Java mocking library. You create a mock with `mock(Service.class)`, tell it how to respond with `when(mock.method(...)).thenReturn(...)` (this is **stubbing**), and later assert it was called with `verify(mock).method(...)` (this is **verification**). ## The problem matchers solve When you write `when(repo.findById(42L)).thenReturn(user)`, Mockito records that the stub fires only when `findById` is called with an argument **equal to** `42L`. That exact-value matching is fine when you control and care about the value. But often you don't: maybe the argument is a freshly-generated UUID, the current time, or an object whose `equals` is awkward. In those cases you want to say "match *any* argument" or "match an argument satisfying *this rule*". That rule object is an **argument matcher**. ## How matchers actually work (the mechanism) A matcher is **not** a value. `any()` does not return the argument; it returns a dummy (often `null` or a zero) and, as a side effect, **pushes a matcher object onto an internal thread-local stack** inside Mockito. When you then call the mocked method, Mockito pops those matchers off the stack and associates one with each argument position. This side-effect mechanism is the reason for the strict mixing rule discussed in a related question — Mockito can only tell positions apart by counting pushed matchers. ## The built-in matchers (all static methods of `org.mockito.ArgumentMatchers`) - `any()` — matches anything, **including null** (in modern Mockito). `any(Foo.class)` matches any non-null instance of `Foo` and, importantly, **does not match null**. - `anyInt()`, `anyLong()`, `anyBoolean()`, `anyDouble()`, … — match any value of that **primitive** type; they never match null (a primitive can't be null). - `anyString()` — any non-null String. `anyList()`, `anyMap()`, `anyCollection()` — any non-null collection of that kind. - `eq(value)` — matches arguments that are `.equals(value)`. This is what a plain literal compiles to conceptually. - `isNull()` / `isNotNull()` / `nullable(Class)` — match null, non-null, or "null or an instance of the class". - `argThat(predicate)` — match using a custom rule (covered in its own question). ## When to use which Use the **most specific matcher that still expresses your intent**. If the test genuinely doesn't care about an argument, `any()`/`anyInt()` documents that. If one argument matters and the rest don't, pin the one that matters with `eq(...)` and relax the others with `any...()`. Over-using `any()` everywhere is a smell: it can hide bugs where the code passes the wrong value, because the stub or verification still matches. ## Why a literal is an implicit eq() When you write `verify(mock).save(user)`, Mockito treats `user` as `eq(user)` — it compares with `equals`. This is why you can usually mix literals and matchers conceptually, even though the **syntactic** mixing rule forbids leaving some positions as raw literals once any position uses a matcher. ## Bottom line Matchers let a test assert *behaviour* ("save was called once with this id") without coupling to *incidental values* ("…and exactly this timestamp"), making tests both more robust and more readable — as long as you stay specific enough to still catch real defects.