How do Mockito matchers work

Question

Mockito argument matchers  such as any  argThat  eq  same  and ArgumentCaptor capture    behave very differently from Hamcrest matchers    Mockito matchers frequently cause InvalidUseOfMatchersException  even in code that executes long after any matchers were used  Mockito matchers are beholden to weird rules  such as only requiring the use of Mockito matchers for all arguments if one argument in a given method uses a matcher  Mockito matchers can cause NullPointerException when overriding Answers or when using  Integer  any   etc  Refactoring code with Mockito matchers in certain ways can produce exceptions and unexpected behavior  and may fail entirely    Why are Mockito matchers designed like this  and how are they implemented

User · Answer

Just a small addition to Jeff Bowman s excellent answer  as I found this question when searching for a solution to one of my own problems   If a call to a method matches more than one mock s when trained calls  the order of the when calls is important  and should be from the most wider to the most specific  Starting from one of Jeff s examples   when foo quux anyInt    anyInt     thenReturn true   when foo quux anyInt    eq 5    thenReturn false     is the order that ensures the  probably  desired result   foo quux 3   any int    8   any other int than 5      returns true foo quux 2   any int    5    returns false   If you inverse the when calls then the result would always be true

User · Answer

Mockito matchers are static methods and calls to those methods  which stand in for arguments during calls to when and verify  Hamcrest matchers  archived version   or Hamcrest-style matchers  are stateless  general-purpose object instances that implement Matcher lt T gt  and expose a method matches T  that returns true if the object matches the Matcher s criteria  They are intended to be free of side effects  and are generally used in assertions such as the one below     Mockito     verify foo  setPowerLevel gt 9000       Hamcrest    assertThat foo getPowerLevel    is greaterThan 9000      Mockito matchers exist  separate from Hamcrest-style matchers  so that descriptions of matching expressions fit directly into method invocations  Mockito matchers return T where Hamcrest matcher methods return Matcher objects  of type Matcher lt T gt    Mockito matchers are invoked through static methods such as eq  any  gt  and startsWith on org mockito Matchers and org mockito AdditionalMatchers  There are also adapters  which have changed across Mockito versions   For Mockito 1 x  Matchers featured some calls  such as intThat or argThat  are Mockito matchers that directly accept Hamcrest matchers as parameters  ArgumentMatcher lt T gt  extended org hamcrest Matcher lt T gt   which was used in the internal Hamcrest representation and was a Hamcrest matcher base class instead of any sort of Mockito matcher  For Mockito 2 0   Mockito no longer has a direct dependency on Hamcrest  Matchers calls phrased as intThat or argThat wrap ArgumentMatcher lt T gt  objects that no longer implement org hamcrest Matcher lt T gt  but are used in similar ways  Hamcrest adapters such as argThat and intThat are still available  but have moved to MockitoHamcrest instead   Regardless of whether the matchers are Hamcrest or simply Hamcrest-style  they can be adapted like so     Mockito matcher intThat adapting Hamcrest-style matcher is greaterThan          verify foo  setPowerLevel intThat is greaterThan 9000       In the above statement  foo setPowerLevel is a method that accepts an int  is greaterThan 9000   returns a Matcher lt Integer gt   which wouldn t work as a setPowerLevel argument  The Mockito matcher intThat wraps that Hamcrest-style Matcher and returns an int so it can appear as an argument  Mockito matchers like gt 9000  would wrap that entire expression into a single call  as in the first line of example code  What matchers do return when foo quux 3  5   thenReturn true    When not using argument matchers  Mockito records your argument values and compares them with their equals methods  when foo quux eq 3   eq 5    thenReturn true         same as above when foo quux anyInt    gt 5    thenReturn true      this one s different  When you call a matcher like any or gt  greater than   Mockito stores a matcher object that causes Mockito to skip that equality check and apply your match of choice  In the case of argumentCaptor capture   it stores a matcher that saves its argument instead for later inspection  Matchers return dummy values such as zero  empty collections  or null  Mockito tries to return a safe  appropriate dummy value  like 0 for anyInt   or any Integer class  or an empty List lt String gt  for anyListOf String class   Because of type erasure  though  Mockito lacks type information to return any value but null for any   or argThat       which can cause a NullPointerException if trying to  quot auto-unbox quot  a null primitive value  Matchers like eq and gt take parameter values  ideally  these values should be computed before the stubbing verification starts  Calling a mock in the middle of mocking another call can interfere with stubbing  Matcher methods can t be used as return values  there is no way to phrase thenReturn anyInt    or thenReturn any Foo class   in Mockito  for instance  Mockito needs to know exactly which instance to return in stubbing calls  and will not choose an arbitrary return value for you  Implementation details Matchers are stored  as Hamcrest-style object matchers  in a stack contained in a class called ArgumentMatcherStorage  MockitoCore and Matchers each own a ThreadSafeMockingProgress instance  which statically contains a ThreadLocal holding MockingProgress instances  It s this MockingProgressImpl that holds a concrete ArgumentMatcherStorageImpl  Consequently  mock and matcher state is static but thread-scoped consistently between the Mockito and Matchers classes  Most matcher calls only add to this stack  with an exception for matchers like and  or  and not  This perfectly corresponds to  and relies on  the evaluation order of Java  which evaluates arguments left-to-right before invoking a method  when foo quux anyInt    and gt 10   lt 20     thenReturn true    6        5    1         4   2       3   This will   Add anyInt   to the stack  Add gt 10  to the stack  Add lt 20  to the stack  Remove gt 10  and lt 20  and add and gt 10   lt 20    Call foo quux 0  0   which  unless otherwise stubbed  returns the default value false  Internally Mockito marks quux int  int  as the most recent call  Call when false   which discards its argument and prepares to stub method quux int  int  identified in 5  The only two valid states are with stack length 0  equality  or 2  matchers   and there are two matchers on the stack  steps 1 and 4   so Mockito stubs the method with an any   matcher for its first argument and and gt 10   lt 20   for its second argument and clears the stack   This demonstrates a few rules   Mockito can t tell the difference between quux anyInt    0  and quux 0  anyInt     They both look like a call to quux 0  0  with one int matcher on the stack  Consequently  if you use one matcher  you have to match all arguments   Call order isn t just important  it s what makes this all work  Extracting matchers to variables generally doesn t work  because it usually changes the call order  Extracting matchers to methods  however  works great  int between10And20   and gt 10   lt 20       BAD    when foo quux anyInt    between10And20   thenReturn true      Mockito sees the stack as the opposite  and gt 10   lt 20    anyInt     public static int anyIntBetween10And20     return and gt 10   lt 20         OK     when foo quux anyInt    anyIntBetween10And20     thenReturn true      The helper method calls the matcher methods in the right order    The stack changes often enough that Mockito can t police it very carefully  It can only check the stack when you interact with Mockito or a mock  and has to accept matchers without knowing whether they re used immediately or abandoned accidentally  In theory  the stack should always be empty outside of a call to when or verify  but Mockito can t check that automatically  You can check manually with Mockito validateMockitoUsage     In a call to when  Mockito actually calls the method in question  which will throw an exception if you ve stubbed the method to throw an exception  or require non-zero or non-null values   doReturn and doAnswer  etc  do not invoke the actual method and are often a useful alternative   If you had called a mock method in the middle of stubbing  e g  to calculate an answer for an eq matcher   Mockito would check the stack length against that call instead  and likely fail   If you try to do something bad  like stubbing verifying a final method  Mockito will call the real method and also leave extra matchers on the stack  The final method call may not throw an exception  but you may get an InvalidUseOfMatchersException from the stray matchers when you next interact with a mock    Common problems  InvalidUseOfMatchersException   Check that every single argument has exactly one matcher call  if you use matchers at all  and that you haven t used a matcher outside of a when or verify call  Matchers should never be used as stubbed return values or fields variables   Check that you re not calling a mock as a part of providing a matcher argument   Check that you re not trying to stub verify a final method with a matcher  It s a great way to leave a matcher on the stack  and unless your final method throws an exception  this might be the only time you realize the method you re mocking is final     NullPointerException with primitive arguments   Integer  any   returns null while any Integer class  returns 0  this can cause a NullPointerException if you re expecting an int instead of an Integer  In any case  prefer anyInt    which will return zero and also skip the auto-boxing step   NullPointerException or other exceptions  Calls to when foo bar any     thenReturn baz  will actually call foo bar null   which you might have stubbed to throw an exception when receiving a null argument  Switching to doReturn baz  when foo  bar any    skips the stubbed behavior    General troubleshooting  Use MockitoJUnitRunner  or explicitly call validateMockitoUsage in your tearDown or  After method  which the runner would do for you automatically   This will help determine whether you ve misused matchers   For debugging purposes  add calls to validateMockitoUsage in your code directly  This will throw if you have anything on the stack  which is a good warning of a bad symptom

[java] How do Mockito matchers work?

Examples related to java

Examples related to mocking

Examples related to mockito