How do you write a custom Hamcrest matcher, and when is it worth doing over a plain assertion or allOf?

## Why a custom matcher Matchers are reusable, self-describing condition objects. Writing your own pays off when a check is (1) **repeated** across many tests, (2) **domain-specific** so a tailored message reads better than a generic one, or (3) needed as a **Mockito argument matcher** (`argThat`) as well as in assertions — the same object serves both. If you just need 'x > 0 and x < 100 once', use `allOf(...)` or two `assertThat` lines. A class is overhead; reach for it when reuse or message quality justifies it. ## The recipe (TypeSafeMatcher) Extend `TypeSafeMatcher<T>` (it handles null/type checks and casting for you), implement two methods, optionally a third, and add a **static factory** so call sites read fluently. ```java import org.hamcrest.Description; import org.hamcrest.Matcher; import org.hamcrest.TypeSafeMatcher; public final class IsPaidOrder extends TypeSafeMatcher<Order> { @Override protected boolean matchesSafely(Order order) { // the check return order.getStatus() == Status.PAID; } @Override public void describeTo(Description description) { // the 'Expected:' line description.appendText("a paid order"); } @Override protected void describeMismatchSafely(Order order, Description mismatch) { mismatch.appendText("was an order with status ").appendValue(order.getStatus()); } public static Matcher<Order> isPaid() { // the factory return new IsPaidOrder(); } } ``` Usage: ```java import static com.example.IsPaidOrder.isPaid; assertThat(order, isPaid()); // failure: Expected: a paid order but: was an order with status <PENDING> ``` ## The three methods - **`matchesSafely(T item)`** — return the boolean result. TypeSafeMatcher already returned `false` for null/wrong type before calling this, so you can assume the item is a non-null `Order`. - **`describeTo(Description)`** — append the *expectation* in domain words. Keep it noun-phrase-like ('a paid order') so it reads after 'Expected:'. - **`describeMismatchSafely(T, Description)`** *(optional)* — append what was actually wrong. If you skip it you get the default 'was <item>'; a tailored message is usually the whole reason to write the matcher. ## Parameterised matchers Factories can take arguments to build a configurable matcher: ```java public static Matcher<Order> hasTotal(Matcher<BigDecimal> amountMatcher) { ... } // assertThat(order, hasTotal(greaterThan(BigDecimal.TEN))); ``` Accepting a *nested matcher* (rather than a raw value) keeps your matcher composable, the Hamcrest way. ## Generics & the factory return type Return `Matcher<T>` from the factory (not the concrete class) so callers depend on the interface. For matchers usable across types you sometimes see `Matcher<? super T>`; for most domain matchers a plain `Matcher<Order>` is fine. ## The shorthand: FeatureMatcher For 'extract a property, then apply a sub-matcher' cases, `FeatureMatcher<T,U>` removes boilerplate: you implement `featureValueOf(T)` to pull the property and pass descriptions to the constructor, then it delegates matching to a supplied sub-matcher — great for `hasTotal`-style accessors. ## When NOT to - One-off checks → `allOf`/separate assertions. - When AssertJ's fluent extracting/`satisfies` already reads well in your codebase. - When the 'matcher' would just wrap `equalTo` on a field with no better message. ## Terms - *Static factory method*: a static method returning a new object, used so call sites read fluently. - *Generics (`<T>`)*: type parameters letting the matcher be type-checked for a specific type. - *DRY*: 'Don't Repeat Yourself' — extract repeated logic. - *Argument matcher (Mockito)*: a matcher used to specify expected arguments in stubbing/verification.