单元测试 - mockito的使用
一丶mockito
github: https://github.com/mockito/mockito
二丶引入mockito框架
<dependency> <groupId>org.mockito</groupId> <artifactId>mockito-core</artifactId> <version>3.1.0</version> <scope>test</scope> </dependency>
三丶使用api
public class MockitoTests { @Test public void verifyBehaviour(){ //创建mock对象 - 接口 List mockedList=mock(List.class); //使用mock对象 模拟调用业务方法 mockedList.add("one"); mockedList.clear(); //验证调用了哪些方法 verify(mockedList).add("one"); //设定预期调用添加了"one" verify(mockedList).clear(); /* mock对象一旦被创建, 它将会记住所有调用过程.然后你可以选择验证你需要的调用过程 */ } @Test(expected = org.mockito.exceptions.verification.junit.ArgumentsAreDifferent.class) public void verifyBehaviourException(){ //创建mock对象 - 接口 List mockedList=mock(List.class); //使用mock对象 模拟调用业务方法 mockedList.add("one"); mockedList.clear(); //验证调用了哪些方法 verify(mockedList).add("two"); //设定预期添加"two", 由于实际上是调用添加"one", 不符合预期, 会抛出异常 /* mock对象一旦被创建, 它将会记住所有调用过程.然后你可以选择验证你需要的调用过程 */ } @Test public void stubbing(){ //打桩, 调用某方法固定返回某些值 //mock具体类 LinkedList mockedList=mock(LinkedList.class); //stubbing 打桩 类似初始化拥有具体数据的对象 // 调用get(0)方法, 将会返回"first" when(mockedList.get(0)).thenReturn("first"); // 调用get(1)方法, 将会返回"two" when(mockedList.get(1)).thenReturn("two"); assertEquals("first", mockedList.get(0)); assertEquals("two", mockedList.get(1)); // 因为get(999)没有打桩, 所以返回null assertEquals(null, mockedList.get(999)); } private ArgumentMatcher<Integer> isValid(){ return (i) -> { if(i==1){ return true; } return false; }; //自定义参数匹配器 } @Test public void argumentMatchers(){ //参数匹配 //mock具体类 LinkedList<String> mockedList=mock(LinkedList.class); //stubbing using built-in anyInt() argument matcher when(mockedList.get(anyInt())).thenReturn("element"); //stubbing using custom matcher (let's say isValid() returns your own matcher implementation): when(mockedList.contains(argThat(isValid()))).thenReturn(true); //following prints "element" System.out.println(mockedList.get(999)); mockedList.add("aaaaaaa"); //you can also verify using an argument matcher verify(mockedList).get(anyInt()); //argument matchers can also be written as Java 8 Lambdas verify(mockedList).add(argThat(someString -> someString.length() > 5)); /* 多参数匹配 verify(mock).someMethod(anyInt(), anyString(), eq("third argument")); //above is correct - eq() is also an argument matcher */ } @Test public void verifyNumberOfInvocation(){ //验证调用次数 //mock具体类 LinkedList<String> mockedList=mock(LinkedList.class); //using mock mockedList.add("once"); mockedList.add("twice"); mockedList.add("twice"); mockedList.add("three times"); mockedList.add("three times"); mockedList.add("three times"); //following two verifications work exactly the same - times(1) is used by default verify(mockedList).add("once"); verify(mockedList, times(1)).add("once"); //exact number of invocations verification verify(mockedList, times(2)).add("twice"); verify(mockedList, times(3)).add("three times"); //verification using never(). never() is an alias to times(0) verify(mockedList, never()).add("never happened"); //verification using atLeast()/atMost() verify(mockedList, atMostOnce()).add("once"); verify(mockedList, atLeastOnce()).add("three times"); verify(mockedList, atLeast(2)).add("three times"); verify(mockedList, atMost(5)).add("three times"); } @Test(expected = RuntimeException.class) public void stubbingMethodWithException(){ //预设调用某方法是抛出一样 //mock具体类 LinkedList<String> mockedList=mock(LinkedList.class); doThrow(new RuntimeException()).when(mockedList).clear(); //调用时将会抛出异常 RuntimeException mockedList.clear(); // Read more about doThrow()|doAnswer() family of methods in section 12. } @Test public void verifyInOrder(){ //验证调用顺序 // A. Single mock whose methods must be invoked in a particular order List singleMock = mock(List.class); //using a single mock singleMock.add("was added first"); singleMock.add("was added second"); //create an inOrder verifier for a single mock InOrder inOrder = inOrder(singleMock); //following will make sure that add is first called with "was added first", then with "was added second" inOrder.verify(singleMock).add("was added first"); inOrder.verify(singleMock).add("was added second"); // B. Multiple mocks that must be used in a particular order List firstMock = mock(List.class); List secondMock = mock(List.class); //using mocks firstMock.add("was called first"); secondMock.add("was called second"); //create inOrder object passing any mocks that need to be verified in order InOrder inOrderDevide = inOrder(firstMock, secondMock); //following will make sure that firstMock was called before secondMock inOrderDevide.verify(firstMock).add("was called first"); inOrderDevide.verify(secondMock).add("was called second"); } @Test public void redundantInvocation(){ //验证多余的验证 List mockedList = mock(List.class); //using mocks mockedList.add("one"); mockedList.add("two"); verify(mockedList).add("one"); //following verification will fail verifyNoMoreInteractions(mockedList); } // ------------------------------------- // shorthandMockCreation 注解mock //mock注解需要使用 @RunWith(MockitoJUnitRunner.class) 或者 MockitoAnnotations.initMocks() @Mock private ArticleDataBase articleDataBase; private ArticleManager articleManager; @Before public void init(){ //mock注解属性 MockitoAnnotations.initMocks(this); articleManager=new ArticleManager(articleDataBase); } //这个算是比较正式的单元测试了 @Test public void shorthandMockCreation(){ // stubbing 预设返回值 when(articleDataBase.getArticleById(1)) .thenReturn("a b c d 是中国, 古里无今算什么"); // 调用需要测试的方法 int length=articleManager.calculateArticleWords(1); // 判断结果 assertEquals(15, length); } // --------------------------- @Test public void stubbingConsecutiveCalls(){ //连续调用某个方法,返回不同的值 List<String> mockedList = mock(List.class); when(mockedList.get(0)) .thenReturn("one") .thenReturn("two"); assertEquals("one", mockedList.get(0)); assertEquals("two", mockedList.get(0)); assertEquals("two", mockedList.get(0)); } @Test public void stubbingWithCallbacks(){ //打桩时, 使用回调返回值 List<String> mockedList = mock(List.class); when(mockedList.get(0)) .thenReturn("one"); when(mockedList.get(0)).thenAnswer( new Answer() { public Object answer(InvocationOnMock invocation) { Object[] args = invocation.getArguments(); Object mock = invocation.getMock(); return "called with arguments: " + Arrays.toString(args); } }); assertEquals("called with arguments: [0]", mockedList.get(0)); } /* doReturn(Object) doThrow(Throwable...) doThrow(Class) doAnswer(Answer) doNothing() doCallRealMethod() */ @Test public void doMethod(){ List<String> mockedList = mock(List.class); when(mockedList.get(0)) .thenReturn("one"); assertEquals("one", mockedList.get(0)); assertEquals("one", mockedList.get(0)); assertEquals("one", mockedList.get(0)); assertEquals("one", mockedList.get(0)); //doReturn适用于重新打桩, 适用于spy doReturn("other") .when(mockedList) .get(0); assertEquals("other", mockedList.get(0)); } // =========================================================== // spy // =========================================================== public void spyingOnRealObjects(){ //观察真实对象 List list = new LinkedList(); List spy = spy(list); //optionally, you can stub out some methods: when(spy.size()).thenReturn(100); //调用真实方法 //using the spy calls *real* methods spy.add("one"); spy.add("two"); //prints "one" - the first element of a list System.out.println(spy.get(0)); //size() method was stubbed - 100 is printed System.out.println(spy.size()); //optionally, you can verify verify(spy).add("one"); verify(spy).add("two"); } @Test public void stubbingOnSpy(){ //对spy对象打桩 List list = new LinkedList(); List spy = spy(list); //You have to use doReturn() for stubbing doReturn("foo").when(spy).get(0); //这个会调用真实方法,所以抛出异常 // //Impossible: real method is called so spy.get(0) throws IndexOutOfBoundsException (the list is yet empty) // when(spy.get(0)).thenReturn("foo"); //注意, 不能对final方法打桩 // when you spy on real objects + you try to stub a final method = trouble } @Test public void changeDefaultReturnValuesOfUnstubbedInvocations(){ ArticleManager mock = mock(ArticleManager.class, Mockito.RETURNS_SMART_NULLS); //这里返回null ArticleDataBase dataBase=mock.getArticleDataBase(); // 抛出SmartNullPointerException, 指出哪里有空指针异常 dataBase.getArticleById(1); } @Test public void capturingArgumentsForFurtherAssertions(){ ArticleManager mock=mock(ArticleManager.class); when(mock.calculateArticleWords(9)).thenReturn(9); //调用测试方法 mock.calculateArticleWords(9); //验证调用参数 ArgumentCaptor<Integer> argument = ArgumentCaptor.forClass(Integer.class); verify(mock).calculateArticleWords(argument.capture()); assertEquals(9, argument.getValue().intValue()); } @Test public void realPartialMocks(){ // 1. 使用spy使用真实对象方法 //you can create partial mock with spy() method: List list = spy(new LinkedList()); //2. thenCallRealMethod方法调用真实方法 //you can enable partial mock capabilities selectively on mocks: ArticleManager mock = mock(ArticleManager.class); //Be sure the real implementation is 'safe'. //If real implementation throws exceptions or depends on specific state of the object then you're in trouble. when(mock.getArticleDataBase()).thenCallRealMethod(); } @Test public void resettingMocks(){ List mock = mock(List.class); when(mock.size()).thenReturn(10); mock.add(1); reset(mock); //at this point the mock forgot any interactions & stubbing } @Test public void serializableMocks(){ //创建可以序列化的mock List serializableMock = mock(List.class, withSettings().serializable()); //spy List<Object> list = new ArrayList<Object>(); List<Object> spy = mock(ArrayList.class, withSettings() .spiedInstance(list) .defaultAnswer(CALLS_REAL_METHODS) .serializable()); } @Test public void verificationWithTimeout(){ //验证超时 List mock = mock(List.class); //passes when someMethod() is called no later than within 100 ms //exits immediately when verification is satisfied (e.g. may not wait full 100 ms) verify(mock, timeout(100)).size(); //above is an alias to: verify(mock, timeout(100).times(1)).size(); //passes as soon as someMethod() has been called 2 times under 100 ms verify(mock, timeout(100).times(2)).size(); //equivalent: this also passes as soon as someMethod() has been called 2 times under 100 ms verify(mock, timeout(100).atLeast(2)).size(); } // ----------------------------------------- // 在mock时打桩 // Car boringStubbedCar = when(mock(Car.class).shiftGear()).thenThrow(EngineNotStarted.class).getMock(); // ----------------------------------------- class Lines extends ArrayList<Line> { // ... } public void betterGenericSupportWithDeepStubs(){ Lines lines = mock(Lines.class, RETURNS_DEEP_STUBS); // Now Mockito understand this is not an Object but a Line Line line = lines.iterator().next(); } }
四丶使用文档(来自Mockito.java API注释)
org.mockito
Class Mockito
java.lang.Object
org.mockito.ArgumentMatchers
org.mockito.Mockito
public class Mockito
extends ArgumentMatchers
The Mockito library enables mock creation, verification and stubbing.
This javadoc content is also available on the http://mockito.org web page. All documentation is kept in javadocs because it guarantees consistency between what's on the web and what's in the source code. It allows access to documentation straight from the IDE even if you work offline. It motivates Mockito developers to keep documentation up-to-date with the code that they write, every day, with every commit.
Contents
0. Migrating to Mockito 2 0.1 Mockito Android support 0.2 Configuration-free inline mock making 1. Let's verify some behaviour! 2. How about some stubbing? 3. Argument matchers 4. Verifying exact number of invocations / at least once / never 5. Stubbing void methods with exceptions 6. Verification in order 7. Making sure interaction(s) never happened on mock 8. Finding redundant invocations 9. Shorthand for mocks creation - @Mock annotation 10. Stubbing consecutive calls (iterator-style stubbing) 11. Stubbing with callbacks 12. doReturn()|doThrow()|doAnswer()|doNothing()|doCallRealMethod() family of methods 13. Spying on real objects 14. Changing default return values of unstubbed invocations (Since 1.7) 15. Capturing arguments for further assertions (Since 1.8.0) 16. Real partial mocks (Since 1.8.0) 17. Resetting mocks (Since 1.8.0) 18. Troubleshooting & validating framework usage (Since 1.8.0) 19. Aliases for behavior driven development (Since 1.8.0) 20. Serializable mocks (Since 1.8.1) 21. New annotations: @Captor, @Spy, @InjectMocks (Since 1.8.3) 22. Verification with timeout (Since 1.8.5) 23. Automatic instantiation of @Spies, @InjectMocks and constructor injection goodness (Since 1.9.0) 24. One-liner stubs (Since 1.9.0) 25. Verification ignoring stubs (Since 1.9.0) 26. Mocking details (Improved in 2.2.x) 27. Delegate calls to real instance (Since 1.9.5) 28. MockMaker API (Since 1.9.5) 29. BDD style verification (Since 1.10.0) 30. Spying or mocking abstract classes (Since 1.10.12, further enhanced in 2.7.13 and 2.7.14) 31. Mockito mocks can be serialized / deserialized across classloaders (Since 1.10.0) 32. Better generic support with deep stubs (Since 1.10.0) 33. Mockito JUnit rule (Since 1.10.17) 34. Switch on or off plugins (Since 1.10.15) 35. Custom verification failure message (Since 2.1.0) 36. Java 8 Lambda Matcher Support (Since 2.1.0) 37. Java 8 Custom Answer Support (Since 2.1.0) 38. Meta data and generic type retention (Since 2.1.0) 39. Mocking final types, enums and final methods (Since 2.1.0) 40. Improved productivity and cleaner tests with "stricter" Mockito (Since 2.+) 41. Advanced public API for framework integrations (Since 2.10.+) 42. New API for integrations: listening on verification start events (Since 2.11.+) 43. New API for integrations: MockitoSession is usable by testing frameworks (Since 2.15.+) 44. Deprecated org.mockito.plugins.InstantiatorProvider as it was leaking internal API. it was replaced by org.mockito.plugins.InstantiatorProvider2 (Since 2.15.4) 45. New JUnit Jupiter (JUnit5+) extension 46. New Mockito.lenient() and MockSettings.lenient() methods (Since 2.20.0) 47. New API for clearing mock state in inline mocking (Since 2.25.0)
0. Migrating to Mockito 2
In order to continue improving Mockito and further improve the unit testing experience, we want you to upgrade to 2.1.0! Mockito follows semantic versioning and contains breaking changes only on major version upgrades. In the lifecycle of a library, breaking changes are necessary to roll out a set of brand new features that alter the existing behavior or even change the API. For a comprehensive guide on the new release including incompatible changes, see 'What's new in Mockito 2 ' wiki page. We hope that you enjoy Mockito 2!
0.1. Mockito Android support
With Mockito version 2.6.1 we ship "native" Android support. To enable Android support, add the `mockito-android` library as dependency to your project. This artifact is published to the same Mockito organization and can be imported for Android as follows:
repositories {
jcenter()
}
dependencies {
testCompile "org.mockito:mockito-core:+"
androidTestCompile "org.mockito:mockito-android:+"
}
You can continue to run the same unit tests on a regular VM by using the `mockito-core` artifact in your "testCompile" scope as shown above. Be aware that you cannot use the inline mock maker on Android due to limitations in the Android VM. If you encounter issues with mocking on Android, please open an issue on the official issue tracker . Do provide the version of Android you are working on and dependencies of your project.
0.2. Configuration-free inline mock making
Starting with version 2.7.6, we offer the 'mockito-inline' artifact that enables inline mock making without configuring the MockMaker extension file. To use this, add the `mockito-inline` instead of the `mockito-core` artifact as follows:
repositories {
jcenter()
}
dependencies {
testCompile "org.mockito:mockito-inline:+"
}
Be aware that this artifact may be abolished when the inline mock making feature is integrated into the default mock maker.
For more information about inline mock making, see section 39.
1. Let's verify some behaviour!
The following examples mock a List, because most people are familiar with the interface (such as the add(), get(), clear() methods). In reality, please don't mock the List class. Use a real instance instead.
//Let's import Mockito statically so that the code looks clearer
import static org.mockito.Mockito.*;
//mock creation
List mockedList = mock(List.class);
//using mock object
mockedList.add("one");
mockedList.clear();
//verification
verify(mockedList).add("one");
verify(mockedList).clear();
Once created, a mock will remember all interactions. Then you can selectively verify whatever interactions you are interested in.
2. How about some stubbing?
//You can mock concrete classes, not just interfaces
LinkedList mockedList = mock(LinkedList.class);
//stubbing
when(mockedList.get(0)).thenReturn("first");
when(mockedList.get(1)).thenThrow(new RuntimeException());
//following prints "first"
System.out.println(mockedList.get(0));
//following throws runtime exception
System.out.println(mockedList.get(1));
//following prints "null" because get(999) was not stubbed
System.out.println(mockedList.get(999));
//Although it is possible to verify a stubbed invocation, usually it's just redundant
//If your code cares what get(0) returns, then something else breaks (often even before verify() gets executed).
//If your code doesn't care what get(0) returns, then it should not be stubbed.
verify(mockedList).get(0);
By default, for all methods that return a value, a mock will return either null, a primitive/primitive wrapper value, or an empty collection, as appropriate. For example 0 for an int/Integer and false for a boolean/Boolean.
Stubbing can be overridden: for example common stubbing can go to fixture setup but the test methods can override it. Please note that overridding stubbing is a potential code smell that points out too much stubbing
Once stubbed, the method will always return a stubbed value, regardless of how many times it is called.
Last stubbing is more important - when you stubbed the same method with the same arguments many times. Other words: the order of stubbing matters but it is only meaningful rarely, e.g. when stubbing exactly the same method calls or sometimes when argument matchers are used, etc.
3. Argument matchers
Mockito verifies argument values in natural java style: by using an equals() method. Sometimes, when extra flexibility is required then you might use argument matchers:
//stubbing using built-in anyInt() argument matcher
when(mockedList.get(anyInt())).thenReturn("element");
//stubbing using custom matcher (let's say isValid() returns your own matcher implementation):
when(mockedList.contains(argThat(isValid()))).thenReturn("element");
//following prints "element"
System.out.println(mockedList.get(999));
//you can also verify using an argument matcher
verify(mockedList).get(anyInt());
//argument matchers can also be written as Java 8 Lambdas
verify(mockedList).add(argThat(someString -> someString.length() > 5));
Argument matchers allow flexible verification or stubbing. Click here or here to see more built-in matchers and examples of custom argument matchers / hamcrest matchers.
For information solely on custom argument matchers check out javadoc for ArgumentMatcher class.
Be reasonable with using complicated argument matching. The natural matching style using equals() with occasional anyX() matchers tend to give clean & simple tests. Sometimes it's just better to refactor the code to allow equals() matching or even implement equals() method to help out with testing.
Also, read section 15 or javadoc for ArgumentCaptor class. ArgumentCaptor is a special implementation of an argument matcher that captures argument values for further assertions.
Warning on argument matchers:
If you are using argument matchers, all arguments have to be provided by matchers.
The following example shows verification but the same applies to stubbing:
verify(mock).someMethod(anyInt(), anyString(), eq("third argument"));
//above is correct - eq() is also an argument matcher
verify(mock).someMethod(anyInt(), anyString(), "third argument");
//above is incorrect - exception will be thrown because third argument is given without an argument matcher.
Matcher methods like anyObject(), eq() do not return matchers. Internally, they record a matcher on a stack and return a dummy value (usually null). This implementation is due to static type safety imposed by the java compiler. The consequence is that you cannot use anyObject(), eq() methods outside of verified/stubbed method.
4. Verifying exact number of invocations / at least x / never
//using mock
mockedList.add("once");
mockedList.add("twice");
mockedList.add("twice");
mockedList.add("three times");
mockedList.add("three times");
mockedList.add("three times");
//following two verifications work exactly the same - times(1) is used by default
verify(mockedList).add("once");
verify(mockedList, times(1)).add("once");
//exact number of invocations verification
verify(mockedList, times(2)).add("twice");
verify(mockedList, times(3)).add("three times");
//verification using never(). never() is an alias to times(0)
verify(mockedList, never()).add("never happened");
//verification using atLeast()/atMost()
verify(mockedList, atMostOnce()).add("once");
verify(mockedList, atLeastOnce()).add("three times");
verify(mockedList, atLeast(2)).add("three times");
verify(mockedList, atMost(5)).add("three times");
times(1) is the default. Therefore using times(1) explicitly can be omitted.
5. Stubbing void methods with exceptions
doThrow(new RuntimeException()).when(mockedList).clear();
//following throws RuntimeException:
mockedList.clear();
Read more about doThrow()|doAnswer() family of methods in section 12.
6. Verification in order
// A. Single mock whose methods must be invoked in a particular order
List singleMock = mock(List.class);
//using a single mock
singleMock.add("was added first");
singleMock.add("was added second");
//create an inOrder verifier for a single mock
InOrder inOrder = inOrder(singleMock);
//following will make sure that add is first called with "was added first", then with "was added second"
inOrder.verify(singleMock).add("was added first");
inOrder.verify(singleMock).add("was added second");
// B. Multiple mocks that must be used in a particular order
List firstMock = mock(List.class);
List secondMock = mock(List.class);
//using mocks
firstMock.add("was called first");
secondMock.add("was called second");
//create inOrder object passing any mocks that need to be verified in order
InOrder inOrder = inOrder(firstMock, secondMock);
//following will make sure that firstMock was called before secondMock
inOrder.verify(firstMock).add("was called first");
inOrder.verify(secondMock).add("was called second");
// Oh, and A + B can be mixed together at will
Verification in order is flexible - you don't have to verify all interactions one-by-one but only those that you are interested in testing in order.
Also, you can create an InOrder object passing only the mocks that are relevant for in-order verification.
7. Making sure interaction(s) never happened on mock
//using mocks - only mockOne is interacted
mockOne.add("one");
//ordinary verification
verify(mockOne).add("one");
//verify that method was never called on a mock
verify(mockOne, never()).add("two");
//verify that other mocks were not interacted
verifyZeroInteractions(mockTwo, mockThree);
8. Finding redundant invocations
//using mocks
mockedList.add("one");
mockedList.add("two");
verify(mockedList).add("one");
//following verification will fail
verifyNoMoreInteractions(mockedList);
A word of warning: Some users who did a lot of classic, expect-run-verify mocking tend to use verifyNoMoreInteractions() very often, even in every test method. verifyNoMoreInteractions() is not recommended to use in every test method. verifyNoMoreInteractions() is a handy assertion from the interaction testing toolkit. Use it only when it's relevant. Abusing it leads to overspecified, less maintainable tests.
See also never() - it is more explicit and communicates the intent well.
9. Shorthand for mocks creation - @Mock annotation
Minimizes repetitive mock creation code.
Makes the test class more readable.
Makes the verification error easier to read because the field name is used to identify the mock.
public class ArticleManagerTest {
@Mock private ArticleCalculator calculator;
@Mock private ArticleDatabase database;
@Mock private UserProvider userProvider;
private ArticleManager manager;
Important! This needs to be somewhere in the base class or a test runner:
MockitoAnnotations.initMocks(testClass);
You can use built-in runner: MockitoJUnitRunner or a rule: MockitoRule. For JUnit5 tests, refer to the JUnit5 extension described in section 45.
Read more here: MockitoAnnotations
10. Stubbing consecutive calls (iterator-style stubbing)
Sometimes we need to stub with different return value/exception for the same method call. Typical use case could be mocking iterators. Original version of Mockito did not have this feature to promote simple mocking. For example, instead of iterators one could use Iterable or simply collections. Those offer natural ways of stubbing (e.g. using real collections). In rare scenarios stubbing consecutive calls could be useful, though:
when(mock.someMethod("some arg"))
.thenThrow(new RuntimeException())
.thenReturn("foo");
//First call: throws runtime exception:
mock.someMethod("some arg");
//Second call: prints "foo"
System.out.println(mock.someMethod("some arg"));
//Any consecutive call: prints "foo" as well (last stubbing wins).
System.out.println(mock.someMethod("some arg"));
Alternative, shorter version of consecutive stubbing:
when(mock.someMethod("some arg"))
.thenReturn("one", "two", "three");
Warning : if instead of chaining .thenReturn() calls, multiple stubbing with the same matchers or arguments is used, then each stubbing will override the previous one:
//All mock.someMethod("some arg") calls will return "two"
when(mock.someMethod("some arg"))
.thenReturn("one")
when(mock.someMethod("some arg"))
.thenReturn("two")
11. Stubbing with callbacks
Allows stubbing with generic Answer interface.
Yet another controversial feature which was not included in Mockito originally. We recommend simply stubbing with thenReturn() or thenThrow(), which should be enough to test/test-drive any clean & simple code. However, if you do have a need to stub with the generic Answer interface, here is an example:
when(mock.someMethod(anyString())).thenAnswer(
new Answer() {
public Object answer(InvocationOnMock invocation) {
Object[] args = invocation.getArguments();
Object mock = invocation.getMock();
return "called with arguments: " + Arrays.toString(args);
}
});
//Following prints "called with arguments: [foo]"
System.out.println(mock.someMethod("foo"));
12. doReturn()|doThrow()| doAnswer()|doNothing()|doCallRealMethod() family of methods
Stubbing void methods requires a different approach from when(Object) because the compiler does not like void methods inside brackets...
Use doThrow() when you want to stub a void method with an exception:
doThrow(new RuntimeException()).when(mockedList).clear();
//following throws RuntimeException:
mockedList.clear();
You can use doThrow(), doAnswer(), doNothing(), doReturn() and doCallRealMethod() in place of the corresponding call with when(), for any method. It is necessary when you
stub void methods
stub methods on spy objects (see below)
stub the same method more than once, to change the behaviour of a mock in the middle of a test.
but you may prefer to use these methods in place of the alternative with when(), for all of your stubbing calls.
Read more about these methods:
doReturn(Object)
doThrow(Throwable...)
doThrow(Class)
doAnswer(Answer)
doNothing()
doCallRealMethod()
13. Spying on real objects
You can create spies of real objects. When you use the spy then the real methods are called (unless a method was stubbed).
Real spies should be used carefully and occasionally, for example when dealing with legacy code.
Spying on real objects can be associated with "partial mocking" concept. Before the release 1.8, Mockito spies were not real partial mocks. The reason was we thought partial mock is a code smell. At some point we found legitimate use cases for partial mocks (3rd party interfaces, interim refactoring of legacy code).
List list = new LinkedList();
List spy = spy(list);
//optionally, you can stub out some methods:
when(spy.size()).thenReturn(100);
//using the spy calls *real* methods
spy.add("one");
spy.add("two");
//prints "one" - the first element of a list
System.out.println(spy.get(0));
//size() method was stubbed - 100 is printed
System.out.println(spy.size());
//optionally, you can verify
verify(spy).add("one");
verify(spy).add("two");
Important gotcha on spying real objects!
Sometimes it's impossible or impractical to use when(Object) for stubbing spies. Therefore when using spies please consider doReturn|Answer|Throw() family of methods for stubbing. Example:
List list = new LinkedList();
List spy = spy(list);
//Impossible: real method is called so spy.get(0) throws IndexOutOfBoundsException (the list is yet empty)
when(spy.get(0)).thenReturn("foo");
//You have to use doReturn() for stubbing
doReturn("foo").when(spy).get(0);
Mockito *does not* delegate calls to the passed real instance, instead it actually creates a copy of it. So if you keep the real instance and interact with it, don't expect the spied to be aware of those interaction and their effect on real instance state. The corollary is that when an *unstubbed* method is called *on the spy* but *not on the real instance*, you won't see any effects on the real instance.
Watch out for final methods. Mockito doesn't mock final methods so the bottom line is: when you spy on real objects + you try to stub a final method = trouble. Also you won't be able to verify those method as well.
14. Changing default return values of unstubbed invocations (Since 1.7)
You can create a mock with specified strategy for its return values. It's quite an advanced feature and typically you don't need it to write decent tests. However, it can be helpful for working with legacy systems.
It is the default answer so it will be used only when you don't stub the method call.
Foo mock = mock(Foo.class, Mockito.RETURNS_SMART_NULLS);
Foo mockTwo = mock(Foo.class, new YourOwnAnswer());
Read more about this interesting implementation of Answer: RETURNS_SMART_NULLS
15. Capturing arguments for further assertions (Since 1.8.0)
Mockito verifies argument values in natural java style: by using an equals() method. This is also the recommended way of matching arguments because it makes tests clean & simple. In some situations though, it is helpful to assert on certain arguments after the actual verification. For example:
ArgumentCaptor<Person> argument = ArgumentCaptor.forClass(Person.class);
verify(mock).doSomething(argument.capture());
assertEquals("John", argument.getValue().getName());
Warning: it is recommended to use ArgumentCaptor with verification but not with stubbing. Using ArgumentCaptor with stubbing may decrease test readability because captor is created outside of assert (aka verify or 'then') block. Also it may reduce defect localization because if stubbed method was not called then no argument is captured.
In a way ArgumentCaptor is related to custom argument matchers (see javadoc for ArgumentMatcher class). Both techniques can be used for making sure certain arguments were passed to mocks. However, ArgumentCaptor may be a better fit if:
custom argument matcher is not likely to be reused
you just need it to assert on argument values to complete verification
Custom argument matchers via ArgumentMatcher are usually better for stubbing.
16. Real partial mocks (Since 1.8.0)
Finally, after many internal debates & discussions on the mailing list, partial mock support was added to Mockito. Previously we considered partial mocks as code smells. However, we found a legitimate use case for partial mocks.
Before release 1.8 spy() was not producing real partial mocks and it was confusing for some users. Read more about spying: here or in javadoc for spy(Object) method.
//you can create partial mock with spy() method:
List list = spy(new LinkedList());
//you can enable partial mock capabilities selectively on mocks:
Foo mock = mock(Foo.class);
//Be sure the real implementation is 'safe'.
//If real implementation throws exceptions or depends on specific state of the object then you're in trouble.
when(mock.someMethod()).thenCallRealMethod();
As usual you are going to read the partial mock warning: Object oriented programming is more less tackling complexity by dividing the complexity into separate, specific, SRPy objects. How does partial mock fit into this paradigm? Well, it just doesn't... Partial mock usually means that the complexity has been moved to a different method on the same object. In most cases, this is not the way you want to design your application.
However, there are rare cases when partial mocks come handy: dealing with code you cannot change easily (3rd party interfaces, interim refactoring of legacy code etc.) However, I wouldn't use partial mocks for new, test-driven & well-designed code.
17. Resetting mocks (Since 1.8.0)
Smart Mockito users hardly use this feature because they know it could be a sign of poor tests. Normally, you don't need to reset your mocks, just create new mocks for each test method.
Instead of reset() please consider writing simple, small and focused test methods over lengthy, over-specified tests. First potential code smell is reset() in the middle of the test method. This probably means you're testing too much. Follow the whisper of your test methods: "Please keep us small & focused on single behavior". There are several threads about it on mockito mailing list.
The only reason we added reset() method is to make it possible to work with container-injected mocks. For more information see FAQ (here ).
Don't harm yourself. reset() in the middle of the test method is a code smell (you're probably testing too much).
List mock = mock(List.class);
when(mock.size()).thenReturn(10);
mock.add(1);
reset(mock);
//at this point the mock forgot any interactions & stubbing
18. Troubleshooting & validating framework usage (Since 1.8.0)
First of all, in case of any trouble, I encourage you to read the Mockito FAQ: https://github.com/mockito/mockito/wiki/FAQ
In case of questions you may also post to mockito mailing list: http://groups.google.com/group/mockito
Next, you should know that Mockito validates if you use it correctly all the time. However, there's a gotcha so please read the javadoc for validateMockitoUsage()
19. Aliases for behavior driven development (Since 1.8.0)
Behavior Driven Development style of writing tests uses //given //when //then comments as fundamental parts of your test methods. This is exactly how we write our tests and we warmly encourage you to do so!
Start learning about BDD here: http://en.wikipedia.org/wiki/Behavior_Driven_Development
The problem is that current stubbing api with canonical role of when word does not integrate nicely with //given //when //then comments. It's because stubbing belongs to given component of the test and not to the when component of the test. Hence BDDMockito class introduces an alias so that you stub method calls with BDDMockito.given(Object) method. Now it really nicely integrates with the given component of a BDD style test!
Here is how the test might look like:
import static org.mockito.BDDMockito.*;
Seller seller = mock(Seller.class);
Shop shop = new Shop(seller);
public void shouldBuyBread() throws Exception {
//given
given(seller.askForBread()).willReturn(new Bread());
//when
Goods goods = shop.buyBread();
//then
assertThat(goods, containBread());
}
20. Serializable mocks (Since 1.8.1)
Mocks can be made serializable. With this feature you can use a mock in a place that requires dependencies to be serializable.
WARNING: This should be rarely used in unit testing.
The behaviour was implemented for a specific use case of a BDD spec that had an unreliable external dependency. This was in a web environment and the objects from the external dependency were being serialized to pass between layers.
To create serializable mock use MockSettings.serializable():
List serializableMock = mock(List.class, withSettings().serializable());
The mock can be serialized assuming all the normal serialization requirements are met by the class.
Making a real object spy serializable is a bit more effort as the spy(...) method does not have an overloaded version which accepts MockSettings. No worries, you will hardly ever use it.
List<Object> list = new ArrayList<Object>();
List<Object> spy = mock(ArrayList.class, withSettings()
.spiedInstance(list)
.defaultAnswer(CALLS_REAL_METHODS)
.serializable());
21. New annotations: @Captor, @Spy, @InjectMocks (Since 1.8.3)
Release 1.8.3 brings new annotations that may be helpful on occasion:
@Captor simplifies creation of ArgumentCaptor - useful when the argument to capture is a nasty generic class and you want to avoid compiler warnings
@Spy - you can use it instead spy(Object).
@InjectMocks - injects mock or spy fields into tested object automatically.
Note that @InjectMocks can also be used in combination with the @Spy annotation, it means that Mockito will inject mocks into the partial mock under test. This complexity is another good reason why you should only use partial mocks as a last resort. See point 16 about partial mocks.
All new annotations are *only* processed on MockitoAnnotations.initMocks(Object). Just like for @Mock annotation you can use the built-in runner: MockitoJUnitRunner or rule: MockitoRule.
22. Verification with timeout (Since 1.8.5)
Allows verifying with timeout. It causes a verify to wait for a specified period of time for a desired interaction rather than fails immediately if had not already happened. May be useful for testing in concurrent conditions.
This feature should be used rarely - figure out a better way of testing your multi-threaded system.
Not yet implemented to work with InOrder verification.
Examples:
//passes when someMethod() is called no later than within 100 ms
//exits immediately when verification is satisfied (e.g. may not wait full 100 ms)
verify(mock, timeout(100)).someMethod();
//above is an alias to:
verify(mock, timeout(100).times(1)).someMethod();
//passes as soon as someMethod() has been called 2 times under 100 ms
verify(mock, timeout(100).times(2)).someMethod();
//equivalent: this also passes as soon as someMethod() has been called 2 times under 100 ms
verify(mock, timeout(100).atLeast(2)).someMethod();
23. Automatic instantiation of @Spies, @InjectMocks and constructor injection goodness (Since 1.9.0)
Mockito will now try to instantiate @Spy and will instantiate @InjectMocks fields using constructor injection, setter injection, or field injection.
To take advantage of this feature you need to use MockitoAnnotations.initMocks(Object), MockitoJUnitRunner or MockitoRule.
Read more about available tricks and the rules of injection in the javadoc for InjectMocks
//instead:
@Spy BeerDrinker drinker = new BeerDrinker();
//you can write:
@Spy BeerDrinker drinker;
//same applies to @InjectMocks annotation:
@InjectMocks LocalPub;
24. One-liner stubs (Since 1.9.0)
Mockito will now allow you to create mocks when stubbing. Basically, it allows to create a stub in one line of code. This can be helpful to keep test code clean. For example, some boring stub can be created & stubbed at field initialization in a test:
public class CarTest {
Car boringStubbedCar = when(mock(Car.class).shiftGear()).thenThrow(EngineNotStarted.class).getMock();
@Test public void should... {}
25. Verification ignoring stubs (Since 1.9.0)
Mockito will now allow to ignore stubbing for the sake of verification. Sometimes useful when coupled with verifyNoMoreInteractions() or verification inOrder(). Helps avoiding redundant verification of stubbed calls - typically we're not interested in verifying stubs.
Warning, ignoreStubs() might lead to overuse of verifyNoMoreInteractions(ignoreStubs(...)); Bear in mind that Mockito does not recommend bombarding every test with verifyNoMoreInteractions() for the reasons outlined in javadoc for verifyNoMoreInteractions(Object...)
Some examples:
verify(mock).foo();
verify(mockTwo).bar();
//ignores all stubbed methods:
verifyNoMoreInteractions(ignoreStubs(mock, mockTwo));
//creates InOrder that will ignore stubbed
InOrder inOrder = inOrder(ignoreStubs(mock, mockTwo));
inOrder.verify(mock).foo();
inOrder.verify(mockTwo).bar();
inOrder.verifyNoMoreInteractions();
Advanced examples and more details can be found in javadoc for ignoreStubs(Object...)
26. Mocking details (Improved in 2.2.x)
Mockito offers API to inspect the details of a mock object. This API is useful for advanced users and mocking framework integrators.
//To identify whether a particular object is a mock or a spy:
Mockito.mockingDetails(someObject).isMock();
Mockito.mockingDetails(someObject).isSpy();
//Getting details like type to mock or default answer:
MockingDetails details = mockingDetails(mock);
details.getMockCreationSettings().getTypeToMock();
details.getMockCreationSettings().getDefaultAnswer();
//Getting invocations and stubbings of the mock:
MockingDetails details = mockingDetails(mock);
details.getInvocations();
details.getStubbings();
//Printing all interactions (including stubbing, unused stubs)
System.out.println(mockingDetails(mock).printInvocations());
For more information see javadoc for MockingDetails.
27. Delegate calls to real instance (Since 1.9.5)
Useful for spies or partial mocks of objects that are difficult to mock or spy using the usual spy API. Since Mockito 1.10.11, the delegate may or may not be of the same type as the mock. If the type is different, a matching method needs to be found on delegate type otherwise an exception is thrown. Possible use cases for this feature:
Final classes but with an interface
Already custom proxied object
Special objects with a finalize method, i.e. to avoid executing it 2 times
The difference with the regular spy:
The regular spy (spy(Object)) contains all state from the spied instance and the methods are invoked on the spy. The spied instance is only used at mock creation to copy the state from. If you call a method on a regular spy and it internally calls other methods on this spy, those calls are remembered for verifications, and they can be effectively stubbed.
The mock that delegates simply delegates all methods to the delegate. The delegate is used all the time as methods are delegated onto it. If you call a method on a mock that delegates and it internally calls other methods on this mock, those calls are not remembered for verifications, stubbing does not have effect on them, too. Mock that delegates is less powerful than the regular spy but it is useful when the regular spy cannot be created.
See more information in docs for AdditionalAnswers.delegatesTo(Object).
28. MockMaker API (Since 1.9.5)
Driven by requirements and patches from Google Android guys Mockito now offers an extension point that allows replacing the proxy generation engine. By default, Mockito uses Byte Buddy to create dynamic proxies.
The extension point is for advanced users that want to extend Mockito. For example, it is now possible to use Mockito for Android testing with a help of dexmaker .
For more details, motivations and examples please refer to the docs for MockMaker.
29. BDD style verification (Since 1.10.0)
Enables Behavior Driven Development (BDD) style verification by starting verification with the BDD then keyword.
given(dog.bark()).willReturn(2);
// when
...
then(person).should(times(2)).ride(bike);
For more information and an example see BDDMockito.then(Object)
30. Spying or mocking abstract classes (Since 1.10.12, further enhanced in 2.7.13 and 2.7.14)
It is now possible to conveniently spy on abstract classes. Note that overusing spies hints at code design smells (see spy(Object)).
Previously, spying was only possible on instances of objects. New API makes it possible to use constructor when creating an instance of the mock. This is particularly useful for mocking abstract classes because the user is no longer required to provide an instance of the abstract class. At the moment, only parameter-less constructor is supported, let us know if it is not enough.
//convenience API, new overloaded spy() method:
SomeAbstract spy = spy(SomeAbstract.class);
//Mocking abstract methods, spying default methods of an interface (only available since 2.7.13)
Function function = spy(Function.class);
//Robust API, via settings builder:
OtherAbstract spy = mock(OtherAbstract.class, withSettings()
.useConstructor().defaultAnswer(CALLS_REAL_METHODS));
//Mocking an abstract class with constructor arguments (only available since 2.7.14)
SomeAbstract spy = mock(SomeAbstract.class, withSettings()
.useConstructor("arg1", 123).defaultAnswer(CALLS_REAL_METHODS));
//Mocking a non-static inner abstract class:
InnerAbstract spy = mock(InnerAbstract.class, withSettings()
.useConstructor().outerInstance(outerInstance).defaultAnswer(CALLS_REAL_METHODS));
For more information please see MockSettings.useConstructor(Object...).
31. Mockito mocks can be serialized / deserialized across classloaders (Since 1.10.0)
Mockito introduces serialization across classloader. Like with any other form of serialization, all types in the mock hierarchy have to serializable, inclusing answers. As this serialization mode require considerably more work, this is an opt-in setting.
// use regular serialization
mock(Book.class, withSettings().serializable());
// use serialization across classloaders
mock(Book.class, withSettings().serializable(ACROSS_CLASSLOADERS));
For more details see MockSettings.serializable(SerializableMode).
32. Better generic support with deep stubs (Since 1.10.0)
Deep stubbing has been improved to find generic information if available in the class. That means that classes like this can be used without having to mock the behavior.
class Lines extends List<Line> {
// ...
}
lines = mock(Lines.class, RETURNS_DEEP_STUBS);
// Now Mockito understand this is not an Object but a Line
Line line = lines.iterator().next();
Please note that in most scenarios a mock returning a mock is wrong.
33. Mockito JUnit rule (Since 1.10.17)
Mockito now offers a JUnit rule. Until now in JUnit there were two ways to initialize fields annotated by Mockito annotations such as @Mock, @Spy, @InjectMocks, etc.
Annotating the JUnit test class with a @RunWith(MockitoJUnitRunner.class)
Invoking MockitoAnnotations.initMocks(Object) in the @Before method
Now you can choose to use a rule :
@RunWith(YetAnotherRunner.class)
public class TheTest {
@Rule public MockitoRule mockito = MockitoJUnit.rule();
// ...
}
For more information see MockitoJUnit.rule().
34. Switch on or off plugins (Since 1.10.15)
An incubating feature made it's way in mockito that will allow to toggle a mockito-plugin. More information here PluginSwitch.
35. Custom verification failure message (Since 2.1.0)
Allows specifying a custom message to be printed if verification fails.
Examples:
// will print a custom message on verification failure
verify(mock, description("This will print on failure")).someMethod();
// will work with any verification mode
verify(mock, times(2).description("someMethod should be called twice")).someMethod();
36. Java 8 Lambda Matcher Support (Since 2.1.0)
You can use Java 8 lambda expressions with ArgumentMatcher to reduce the dependency on ArgumentCaptor. If you need to verify that the input to a function call on a mock was correct, then you would normally use the ArgumentCaptor to find the operands used and then do subsequent assertions on them. While for complex examples this can be useful, it's also long-winded.
Writing a lambda to express the match is quite easy. The argument to your function, when used in conjunction with argThat, will be passed to the ArgumentMatcher as a strongly typed object, so it is possible to do anything with it.
Examples:
// verify a list only had strings of a certain length added to it
// note - this will only compile under Java 8
verify(list, times(2)).add(argThat(string -> string.length() < 5));
// Java 7 equivalent - not as neat
verify(list, times(2)).add(argThat(new ArgumentMatcher (){
public boolean matches(String arg) {
return arg.length() < 5;
}
}));
// more complex Java 8 example - where you can specify complex verification behaviour functionally
verify(target, times(1)).receiveComplexObject(argThat(obj -> obj.getSubObject().get(0).equals("expected")));
// this can also be used when defining the behaviour of a mock under different inputs
// in this case if the input list was fewer than 3 items the mock returns null
when(mock.someMethod(argThat(list -> list.size()<3))).thenReturn(null);
37. Java 8 Custom Answer Support (Since 2.1.0)
As the Answer interface has just one method it is already possible to implement it in Java 8 using a lambda expression for very simple situations. The more you need to use the parameters of the method call, the more you need to typecast the arguments from InvocationOnMock.
Examples:
// answer by returning 12 every time
doAnswer(invocation -> 12).when(mock).doSomething();
// answer by using one of the parameters - converting into the right
// type as your go - in this case, returning the length of the second string parameter
// as the answer. This gets long-winded quickly, with casting of parameters.
doAnswer(invocation -> ((String)invocation.getArgument(1)).length())
.when(mock).doSomething(anyString(), anyString(), anyString());
For convenience it is possible to write custom answers/actions, which use the parameters to the method call, as Java 8 lambdas. Even in Java 7 and lower these custom answers based on a typed interface can reduce boilerplate. In particular, this approach will make it easier to test functions which use callbacks. The methods answer and answerVoid can be used to create the answer. They rely on the related answer interfaces in org.mockito.stubbing that support answers up to 5 parameters.
Examples:
// Example interface to be mocked has a function like:
void execute(String operand, Callback callback);
// the example callback has a function and the class under test
// will depend on the callback being invoked
void receive(String item);
// Java 8 - style 1
doAnswer(AdditionalAnswers. answerVoid((operand, callback) -> callback.receive("dummy"))
.when(mock).execute(anyString(), any(Callback.class));
// Java 8 - style 2 - assuming static import of AdditionalAnswers
doAnswer(answerVoid((String operand, Callback callback) -> callback.receive("dummy"))
.when(mock).execute(anyString(), any(Callback.class));
// Java 8 - style 3 - where mocking function to is a static member of test class
private static void dummyCallbackImpl(String operation, Callback callback) {
callback.receive("dummy");
}
doAnswer(answerVoid(TestClass::dummyCallbackImpl)
.when(mock).execute(anyString(), any(Callback.class));
// Java 7
doAnswer(answerVoid(new VoidAnswer2 () {
public void answer(String operation, Callback callback) {
callback.receive("dummy");
}})).when(mock).execute(anyString(), any(Callback.class));
// returning a value is possible with the answer() function
// and the non-void version of the functional interfaces
// so if the mock interface had a method like
boolean isSameString(String input1, String input2);
// this could be mocked
// Java 8
doAnswer(AdditionalAnswers. answer((input1, input2) -> input1.equals(input2))))
.when(mock).execute(anyString(), anyString());
// Java 7
doAnswer(answer(new Answer2 () {
public String answer(String input1, String input2) {
return input1 + input2;
}})).when(mock).execute(anyString(), anyString());
38. Meta data and generic type retention (Since 2.1.0)
Mockito now preserves annotations on mocked methods and types as well as generic meta data. Previously, a mock type did not preserve annotations on types unless they were explicitly inherited and never retained annotations on methods. As a consequence, the following conditions now hold true:
@MyAnnotation
class Foo {
List<String> bar() { ... }
}
Class<?> mockType = mock(Foo.class).getClass();
assert mockType.isAnnotationPresent(MyAnnotation.class);
assert mockType.getDeclaredMethod("bar").getGenericReturnType() instanceof ParameterizedType;
When using Java 8, Mockito now also preserves type annotations. This is default behavior and might not hold if an alternative MockMaker is used.
39. Mocking final types, enums and final methods (Since 2.1.0)
Mockito now offers an Incubating, optional support for mocking final classes and methods. This is a fantastic improvement that demonstrates Mockito's everlasting quest for improving testing experience. Our ambition is that Mockito "just works" with final classes and methods. Previously they were considered unmockable, preventing the user from mocking. We already started discussing how to make this feature enabled by default. Currently, the feature is still optional as we wait for more feedback from the community.
This alternative mock maker which uses a combination of both Java instrumentation API and sub-classing rather than creating a new class to represent a mock. This way, it becomes possible to mock final types and methods.
This mock maker is turned off by default because it is based on completely different mocking mechanism that requires more feedback from the community. It can be activated explicitly by the mockito extension mechanism, just create in the classpath a file /mockito-extensions/org.mockito.plugins.MockMaker containing the value mock-maker-inline.
As a convenience, the Mockito team provides an artifact where this mock maker is preconfigured. Instead of using the mockito-core artifact, include the mockito-inline artifact in your project. Note that this artifact is likely to be discontinued once mocking of final classes and methods gets integrated into the default mock maker.
Some noteworthy notes about this mock maker:
Mocking final types and enums is incompatible with mock settings like :
explicitly serialization support withSettings().serializable()
extra-interfaces withSettings().extraInterfaces()
Some methods cannot be mocked
Package-visible methods of java.*
native methods
This mock maker has been designed around Java Agent runtime attachment ; this require a compatible JVM, that is part of the JDK (or Java 9 VM). When running on a non-JDK VM prior to Java 9, it is however possible to manually add the Byte Buddy Java agent jar using the -javaagent parameter upon starting the JVM.
If you are interested in more details of this feature please read the javadoc of org.mockito.internal.creation.bytebuddy.InlineByteBuddyMockMaker
40. Improved productivity and cleaner tests with "stricter" Mockito (Since 2.+)
To quickly find out how "stricter" Mockito can make you more productive and get your tests cleaner, see:
Strict stubbing with JUnit Rules - MockitoRule.strictness(Strictness) with Strictness.STRICT_STUBS
Strict stubbing with JUnit Runner - MockitoJUnitRunner.StrictStubs
Strict stubbing if you cannot use runner/rule (like TestNG) - MockitoSession
Unnecessary stubbing detection with MockitoJUnitRunner
Stubbing argument mismatch warnings, documented in MockitoHint
Mockito is a "loose" mocking framework by default. Mocks can be interacted with without setting any expectations beforehand. This is intentional and it improves the quality of tests by forcing users to be explicit about what they want to stub / verify. It is also very intuitive, easy to use and blends nicely with "given", "when", "then" template of clean test code. This is also different from the classic mocking frameworks of the past, they were "strict" by default.
Being "loose" by default makes Mockito tests harder to debug at times. There are scenarios where misconfigured stubbing (like using a wrong argument) forces the user to run the test with a debugger. Ideally, tests failures are immediately obvious and don't require debugger to identify the root cause. Starting with version 2.1 Mockito has been getting new features that nudge the framework towards "strictness". We want Mockito to offer fantastic debuggability while not losing its core mocking style, optimized for intuitiveness, explicitness and clean test code.
Help Mockito! Try the new features, give us feedback, join the discussion about Mockito strictness at GitHub issue 769 .
41. Advanced public API for framework integrations (Since 2.10.+)
In Summer 2017 we decided that Mockito should offer better API for advanced framework integrations. The new API is not intended for users who want to write unit tests. It is intended for other test tools and mocking frameworks that need to extend or wrap Mockito with some custom logic. During the design and implementation process (issue 1110 ) we have developed and changed following public API elements:
New MockitoPlugins - Enables framework integrators to get access to default Mockito plugins. Useful when one needs to implement custom plugin such as MockMaker and delegate some behavior to the default Mockito implementation.
New MockSettings.build(Class) - Creates immutable view of mock settings used later by Mockito. Useful for creating invocations with InvocationFactory or when implementing custom MockHandler.
New MockingDetails.getMockHandler() - Other frameworks may use the mock handler to programmatically simulate invocations on mock objects.
New MockHandler.getMockSettings() - Useful to get hold of the setting the mock object was created with.
New InvocationFactory - Provides means to create instances of Invocation objects. Useful for framework integrations that need to programmatically simulate method calls on mock objects.
New MockHandler.getInvocationContainer() - Provides access to invocation container object which has no methods (marker interface). Container is needed to hide the internal implementation and avoid leaking it to the public API.
Changed Stubbing - it now extends Answer interface. It is backwards compatible because Stubbing interface is not extensible (see NotExtensible). The change should be seamless to our users.
Deprecated InternalMockHandler - In order to accommodate API changes we needed to deprecate this interface. The interface was always documented as internal, we don't have evidence it was used by the community. The deprecation should be completely seamless for our users.
NotExtensible - Public annotation that indicates to the user that she should not provide custom implementations of given type. Helps framework integrators and our users understand how to use Mockito API safely.
Do you have feedback? Please leave comment in issue 1110 .
42. New API for integrations: listening on verification start events (Since 2.11.+)
Framework integrations such as Spring Boot needs public API to tackle double-proxy use case (issue 1191 ). We added:
New VerificationStartedListener and VerificationStartedEvent enable framework integrators to replace the mock object for verification. The main driving use case is Spring Boot integration. For details see Javadoc for VerificationStartedListener.
New public method MockSettings.verificationStartedListeners(VerificationStartedListener...) allows to supply verification started listeners at mock creation time.
New handy method MockingDetails.getMock() was added to make the MockingDetails API more complete. We found this method useful during the implementation.
43. New API for integrations: MockitoSession is usable by testing frameworks (Since 2.15.+)
MockitoSessionBuilder and MockitoSession were enhanced to enable reuse by testing framework integrations (e.g. MockitoRule for JUnit):
MockitoSessionBuilder.initMocks(Object...) allows to pass in multiple test class instances for initialization of fields annotated with Mockito annotations like Mock. This method is useful for advanced framework integrations (e.g. JUnit Jupiter), when a test uses multiple, e.g. nested, test class instances.
MockitoSessionBuilder.name(String) allows to pass a name from the testing framework to the MockitoSession that will be used for printing warnings when Strictness.WARN is used.
MockitoSessionBuilder.logger(MockitoSessionLogger) makes it possible to customize the logger used for hints/warnings produced when finishing mocking (useful for testing and to connect reporting capabilities provided by testing frameworks such as JUnit Jupiter).
MockitoSession.setStrictness(Strictness) allows to change the strictness of a MockitoSession for one-off scenarios, e.g. it enables configuring a default strictness for all tests in a class but makes it possible to change the strictness for a single or a few tests.
MockitoSession.finishMocking(Throwable) was added to avoid confusion that may arise because there are multiple competing failures. It will disable certain checks when the supplied failure is not null.
44. Deprecated org.mockito.plugins.InstantiatorProvider as it was leaking internal API. it was replaced by org.mockito.plugins.InstantiatorProvider2 (Since 2.15.4)
InstantiatorProvider returned an internal API. Hence it was deprecated and replaced by InstantiatorProvider2. Old instantiator providers will continue to work, but it is recommended to switch to the new API.
45. New JUnit Jupiter (JUnit5+) extension
For integration with JUnit Jupiter (JUnit5+), use the `org.mockito:mockito-junit-jupiter` artifact. For more information about the usage of the integration, see the JavaDoc of MockitoExtension.
46. New Mockito.lenient() and MockSettings.lenient() methods (Since 2.20.0)
Strict stubbing feature is available since early Mockito 2. It is very useful because it drives cleaner tests and improved productivity. Strict stubbing reports unnecessary stubs, detects stubbing argument mismatch and makes the tests more DRY (Strictness.STRICT_STUBS). This comes with a trade-off: in some cases, you may get false negatives from strict stubbing. To remedy those scenarios you can now configure specific stubbing to be lenient, while all the other stubbings and mocks use strict stubbing:
lenient().when(mock.foo()).thenReturn("ok");
If you want all the stubbings on a given mock to be lenient, you can configure the mock accordingly:
Foo mock = Mockito.mock(Foo.class, withSettings().lenient());
For more information refer to lenient(). Let us know how do you find the new feature by opening a GitHub issue to discuss!
47. New API for clearing mock state in inline mocking (Since 2.25.0)
In certain specific, rare scenarios (issue #1619 ) inline mocking causes memory leaks. There is no clean way to mitigate this problem completely. Hence, we introduced a new API to explicitly clear mock state (only make sense in inline mocking!). See example usage in MockitoFramework.clearInlineMocks(). If you have feedback or a better idea how to solve the problem please reach out.
Direct Known Subclasses:
BDDMockito
Maven: org.mockito:mockito-core:3.1.0
`Mockito` on localhost