org.mockito.exceptions.misusing

Class PotentialStubbingProblem

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

org.mockito.exceptions.base.MockitoException

org.mockito.exceptions.misusing.PotentialStubbingProblem

All Implemented Interfaces:

Serializable

public class PotentialStubbingProblem
extends MockitoException

PotentialStubbingProblem improves productivity by failing the test early when the user misconfigures mock's stubbing.

PotentialStubbingProblem exception is a part of "strict stubbing" Mockito API intended to drive cleaner tests and better productivity with Mockito mocks. For more information see Strictness.

PotentialStubbingProblem is thrown when mocked method is stubbed with some argument in test but then invoked with different argument in the code. This scenario is called "stubbing argument mismatch".

Example:

 //test method:
 given(mock.getSomething(100)).willReturn(something);

 //code under test:
 Something something = mock.getSomething(50); // <-- stubbing argument mismatch
 

The stubbing argument mismatch typically indicates:

1. Mistake, typo or misunderstanding in the test code, the argument(s) used when declaring stubbing are different by mistake
2. Mistake, typo or misunderstanding in the code under test, the argument(s) used when invoking stubbed method are different by mistake
3. Intentional use of stubbed method with different argument, either in the test (more stubbing) or in code under test

User mistake (use case 1 and 2) make up 95% of the stubbing argument mismatch cases. PotentialStubbingProblem improves productivity in those scenarios by failing early with clean message pointing out the incorrect stubbing or incorrect invocation of stubbed method. In remaining 5% of the cases (use case 3) PotentialStubbingProblem can give false negative signal indicating non-existing problem. The exception message contains information how to opt-out from the feature. Mockito optimizes for enhanced productivity of 95% of the cases while offering opt-out for remaining 5%. False negative signal for edge cases is a trade-off for general improvement of productivity.

What to do if you fall into use case 3 (false negative signal)? You have 2 options:

1. Do you see this exception because you're stubbing the same method multiple times in the same test? In that case, please use BDDMockito.willReturn(Object) or Mockito.doReturn(Object) family of methods for stubbing. Convenient stubbing via Mockito.when(Object) has its drawbacks: the framework cannot distinguish between actual invocation on mock (real code) and the stubbing declaration (test code). Hence the need to use BDDMockito.willReturn(Object) or Mockito.doReturn(Object) for certain edge cases. It is a well known limitation of Mockito API and another example how Mockito optimizes its clean API for 95% of the cases while still supporting edge cases.
2. Reduce the strictness level in the test method (only for JUnit Rules):

   
    public class ExampleTest {
        @Rule
        public MockitoRule rule = MockitoJUnit.rule().strictness(Strictness.STRICT_STUBS);
   
        @Test public void exampleTest() {
            //Change the strictness level only for this test method:
            mockito.strictness(Strictness.LENIENT);
   
            //remaining test code
        }
    }
    

   Currently, reducing strictness is only available to JUnit rules. If you need it in a different context let us know at issue 857.
3. To opt-out in Mockito 2.x, simply remove the strict stubbing setting in the test class.

Mockito team is very eager to hear feedback about "strict stubbing" feature, let us know by commenting on GitHub issue 769. Strict stubbing is an attempt to improve testability and productivity with Mockito. Tell us what you think!

Since:

2.3.0

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
PotentialStubbingProblem(String message)

Method Summary

Methods inherited from class org.mockito.exceptions.base.MockitoException

getUnfilteredStackTrace

Methods inherited from class java.lang.Throwable

fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

PotentialStubbingProblem

public PotentialStubbingProblem(String message)