eq() Matcher and Mixing Rules
Fast recall
Quick revision
Core answer
Interview-ready guide
Interview answer
eq is a Mockito matcher that wraps a literal value so it acts like a matcher.
You need it because of Mockito's rule that says you can't mix matchers with real values in the same method call. If you use anyString or any for one argument, all the other arguments have to be matchers too. So if you want one argument to be an exact value and another to be flexible, you wrap the exact value with eq.
For example, when you stub updateUser with a specific user ID but accept any user data, you write when updateUser of eq of userId comma any of UserData dot class. If you forget the eq and just pass userId directly, Mockito throws InvalidUseOfMatchersException because it sees one raw value and one matcher, and it can't handle that mix.
The reason is that matchers record themselves on an internal stack, and raw values don't, so Mockito loses track of which argument is which. eq is basically a pass-through—eq of 123 matches exactly 123, nothing fancy. It's just there to put the value into matcher mode.
The same rule applies in verify calls, not just when. One thing to watch: for objects, eq uses the equals method, so if your class doesn't override equals, it'll use reference equality and might not match the way you expect. Bottom line, use eq whenever you're mixing exact values with flexible matchers.
eq() Matcher and Mixing Rules
Direct Answer
eq(value) wraps a literal value as an argument matcher. You must use it when mixing matchers with real values in the same method call, because Mockito requires all arguments to be matchers or none. For example, when(mock.method(eq(id), anyString())) is valid, but when(mock.method(id, anyString())) throws InvalidUseOfMatchersException.
Code Example
@ExtendWith(MockitoExtension.class)
class PaymentServiceTest {
@Mock
private PaymentGateway paymentGateway;
@InjectMocks
private PaymentService paymentService;
@Test
void shouldProcessPaymentForSpecificMerchant() {
var merchantId = "MERCH_12345";
// CORRECT: eq() wraps the exact merchantId, any() for the amount
when(paymentGateway.charge(eq(merchantId), any(BigDecimal.class)))
.thenReturn(new PaymentResult("SUCCESS"));
var result = paymentService.processPayment(merchantId, new BigDecimal("99.99"));
assertThat(result.getStatus()).isEqualTo("SUCCESS");
verify(paymentGateway).charge(eq(merchantId), any(BigDecimal.class)); // Same rule in verify
}
@Test
void incorrectMixingCausesException() {
// WRONG: This throws InvalidUseOfMatchersException
// when(paymentGateway.charge("MERCH_12345", any(BigDecimal.class)))
}
}
Common Mistakes & Pitfalls
- Forgetting eq() and hitting InvalidUseOfMatchersException: Freshers write when(mock.method(realValue, anyString())) without realizing realValue needs eq(realValue)—the test fails with a cryptic exception.
- Overusing eq() when it's not needed: Writing when(mock.method(eq("a"), eq("b"))) when no matchers are involved—just use when(mock.method("a", "b")), it's simpler and clearer.
- Not knowing eq() is a pass-through: Thinking eq() does something special beyond matching the exact value—it's literally just a wrapper to satisfy the matcher-mode requirement.
- Misunderstanding what eq() matches: Freshers sometimes think eq() is like equals() in Java—it is for primitives and strings, but for objects it uses equals() method, so if your object doesn't override equals(), eq() uses reference equality.
Check your understanding
Answer these without looking back at the article.
- What happens internally in Mockito's matcher stack when you mix real values and matchers?
- Is eq() different from passing the raw value directly when all arguments are real values?
Looking for a structured roadmap?
Every module on this page is also part of the full Java backend interview track.