Mockito Matcher

matcher 개념

matcher = “인자 매칭 규칙”

• any() = 아무 값이면 매치
• eq(x) = equals 기준으로 x와 같으면 매치
• isNull() = null이면 매치
• argThat { ... } = 사용자 정의 조건이면 매치

핵심 동작: “스택에 기록 + 더미값(dummy value) 반환”

Mockito 공식 Javadoc은 matcher가 이렇게 동작한다고 명시한다.

• any(), eq()는 matcher를 반환하는 게 아니라
• 매칭 규칙을 내부 스택에 기록하고
• 컴파일러 타입 요구 때문에 더미 값(대개 null)을 반환한다
• 그래서 any(), eq() 같은 matcher는 verified/stubbed method 바깥에서 사용하면 안 된다

Q) “matcher로 표시된 값은 테스트할 때 규칙에 맞는 랜덤값이 들어간다고 보면 되나?”

• 아니다. matcher가 값을 “생성”하지 않는다.
• SUT가 실제로 전달한 값이 들어오고, matcher는 그 값이 규칙에 맞는지 판정한다.
• 단, matcher를 실수로 SUT 호출 인자에 넣으면 matcher가 반환한 더미값(null 등) 이 실제 인자로 들어가 흐름이 달라질 수 있다.

---

해당 개념이 필요한 이유

• 유연한 인자 조건을 표현하기 위해(값이 아니라 규칙)
• 변동 값(UUID·시간 등) 때문에 테스트가 자주 깨지는 걸 줄이기 위해
• 중요한 인자만 정확히 검증하고 나머지는 단순화해 의도를 명확히 하기 위해

AS-IS / TO-BE 예시

예: 결제 요청을 보내는 로직에서 requestId는 매번 바뀌고, userId/amount만 정확히 검증하고 싶다.

data class PayRequest(val userId: String, val requestId: String, val amount: Int)
 
interface PaymentGateway {
    fun send(req: PayRequest)
}
 
class PaymentService(private val gateway: PaymentGateway) {
    fun pay(userId: String, amount: Int) {
        val req = PayRequest(
            userId = userId,
            requestId = java.util.UUID.randomUUID().toString(), // 매번 바뀜
            amount = amount
        )
        gateway.send(req)
    }
}

AS-IS (matcher가 없을 때)

@Test
fun `pay sends request`() {
    val gateway = mock<PaymentGateway>()
    val sut = PaymentService(gateway)
 
    sut.pay("u-1", 1000)
 
    // ❌ requestId가 매번 달라서 기대값을 고정하기 어려움 → 테스트가 취약해짐
    verify(gateway).send(PayRequest("u-1", "고정값-불가능", 1000))
}

TO-BE (matcher 도입 후)

@Test
fun `pay sends request - rule based`() {
    val gateway = mock<PaymentGateway>()
    val sut = PaymentService(gateway)
 
    sut.pay("u-1", 1000)
 
    // ✅ requestId는 "있기만 하면 됨", userId/amount는 정확히 확인
    verify(gateway).send(
        argThat { userId == "u-1" && amount == 1000 && requestId.isNotBlank() }
    )
}

flowchart TD
  A[테스트에서 인자 검증 필요] --> B{인자가 항상 고정값인가?}
  B -- Yes --> C[raw 값으로 verify/stub 가능]
  B -- No --> D[AS-IS: 값 고정 어려움 → 테스트 취약/의미 약화]
  D --> E[TO-BE: matcher로 '규칙' 선언]
  E --> H[의도 선명 + 변경에 덜 깨짐]

matcher 규칙 3개

규칙 1. matcher를 하나라도 쓰면, 모든 인자를 matcher로 통일

Mockito Javadoc의 대표 경고다.

// ✅ OK
verify(gateway).send(anyInt(), anyString(), eq("third"))
 
// ❌ NG: matcher + raw 값 혼용 → 예외
verify(gateway).send(anyInt(), anyString(), "third")

Q) “그럼 eq는 정확한 값을 감싸기 위한 규칙이라고 보면 되나?”
맞다. eq(value)는 “정확한 값이어야 함”을 matcher로 표현하면서, “matcher 통일 규칙”을 지키게 해준다.

규칙 2. matcher는 verify / stubbing 안에서만

matcher는 “스택에 기록 + 더미값 반환” 방식이므로, verified/stubbed method 바깥(= SUT 호출 인자)에서 사용하면 안 된다.

• ✅ verify(mock).doSomething(any())
• ✅ whenever(mock.load(eq("id"))).thenReturn(data)
• ❌ sut.process(any()) ← SUT 호출 인자에 matcher 사용

규칙 3. null은 “의도적으로” 매칭한다

any(Class) / anyInt 같은 타입 체크 matcher는 null을 매칭하지 않는다는 점이 Javadoc에 명시되어 있다. null이 필요하면 isNull()을 선택하는 것이 가장 명확하다.

---

doReturn)에서 matcher 사용하는 법

whenever(...).thenReturn(...) 기본 형태

interface FeatureFlagClient {
    fun isEnabled(key: String, userId: String): Boolean
}
 
val client = mock<FeatureFlagClient>()
 
// stubbing: 특정 조건이면 true를 반환
whenever(client.isEnabled(eq("NEW_UI"), eq("u-1"))).thenReturn(true)

stubbing에서도 “matcher를 하나라도 쓰면 전부 matcher”

아래는 stubbing에서 흔히 만나는 InvalidUseOfMatchersException 패턴이다. (규칙 #1 위반)

// ❌ raw + matcher 혼용
whenever(client.isEnabled("NEW_UI", any())).thenReturn(true)
 
// ✅ 전부 matcher로 통일
whenever(client.isEnabled(eq("NEW_UI"), any())).thenReturn(true)

3.3 null이 들어올 수 있으면 isNull() 또는 nullable 허용 matcher를 선택

Mockito 관점에서 가장 명확한 선택은 isNull()이다.

interface TokenStore {
    fun find(tokenId: String?): String?
}
 
val store = mock<TokenStore>()
 
whenever(store.find(isNull())).thenReturn("guest-token")

doReturn(...).whenever(...)는 언제 쓰나?

Mockito는 doReturn() | doThrow() | doAnswer() ... 같은 do-패밀리 API를 제공한다.

실무 팁(특히 spy 상황):

• whenever(spy.method())는 spy의 실제 메서드가 먼저 실행될 수 있어 위험한 경우가 있다.
• 이런 경우 doReturn(x).whenever(spy).method(...) 형태로 “실제 호출 없이” 스텁을 걸 수 있다.

val spyClient = spy(RealClient())
 
doReturn("cached").whenever(spyClient).fetch(eq("key"))

---

자주 나오는 에러 로그를 “규칙”으로 환원하기

InvalidUseOfMatchersException: X matchers expected, Y recorded

의미(거의 항상): 같은 호출에서 matcher와 raw 값을 섞었다.
해결: raw 값을 eq(...)로 감싸서 “전부 matcher”로 만들거나, 전부 raw로 바꾼다.

// ❌
verify(gateway).send(any(), "tenantA")
 
// ✅
verify(gateway).send(any(), eq("tenantA"))

Argument(s) are different! Wanted ... Actual ...

의미: 호출은 있었는데, 인자가 기대와 다르다.

자주 나오는 원인:

• null이 실제로 들어오는데 any(Class)/primitive 계열로 검증해서 실패
  • 해결: null이면 isNull()로 의도를 명확히

verify(store).find(isNull())

Wanted but not invoked (Actually, there were zero interactions with this mock)

의미: 해당 mock에 대해 원하는 호출 자체가 없었다.

우선순위 체크리스트:

1. SUT가 해당 로직 분기/상태를 실제로 타는지(조건/입력/상태)
2. stubbing이 매칭 실패해서 중간에 흐름이 끊긴 건 아닌지(특히 matcher 혼용/nullable)
3. 비동기/코루틴이라면 테스트 스케줄러 밖 디스패처/스코프에서 실행 중인 건 아닌지
4. “검증 대상” mock 인스턴스가 맞는지(다른 인스턴스를 주입/생성한 건 아닌지)

---

최종 요약(운영 규칙 6줄)

1. matcher는 “값”이 아니라 “판정 규칙”이다.
2. matcher를 하나라도 쓰면 모든 인자를 matcher로 통일한다.
3. matcher는 verify/stubbing 안에서만 사용한다. (SUT 호출에는 실제 값만)
4. 값 고정이 필요하면 eq(value)를 쓴다. (정확한 값도 matcher로 표현)
5. null은 isNull()로 의도를 명확히 한다. (any(Class)/primitive 계열 matcher는 null 미매칭)
6. spy에서 실제 호출을 피해야 하면 doReturn(...).whenever(...)를 고려한다.

---

참고(공식)

• Mockito ArgumentMatchers
• Mockito Mockito
• mockito-kotlin Wiki (Mocking and verifying)
• mockito-kotlin Wiki (Stubbing)