Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance. Project price only 1 $
You can buy this project and download/modify it how often you want.
/*
* Copyright (c) 2007 Mockito contributors
* This program is made available under the terms of the MIT License.
*/
package org.mockito;
import org.mockito.internal.MockitoCore;
import org.mockito.internal.creation.MockSettingsImpl;
import org.mockito.internal.debugging.MockitoDebuggerImpl;
import org.mockito.internal.stubbing.answers.*;
import org.mockito.internal.stubbing.defaultanswers.*;
import org.mockito.internal.verification.VerificationModeFactory;
import org.mockito.runners.MockitoJUnitRunner;
import org.mockito.stubbing.*;
import org.mockito.verification.VerificationMode;
/**
*
* Mockito library enables mocks 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.
* Also, it makes possible to access documentation straight from the IDE even if you work offline.
*
*
* Following examples mock a List, because everyone knows its interface (methods
* like add(), get(), clear() will be used).
* You probably wouldn't mock List class 'in real'.
*
*
* Once created, mock will remember all interactions. Then you can selectively
* verify whatever interaction you are interested in.
*
*
2. How about some stubbing?
*
*
* //You can mock concrete classes, not only 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 before even verify() gets executed).
* //If your code doesn't care what get(0) returns then it should not be stubbed. Not convinced? See here.
* verify(mockedList).get(0);
*
*
*
*
By default, for all methods that return value, mock returns null, an
* empty collection or appropriate primitive/primitive wrapper value (e.g: 0,
* false, ... for int/Integer, 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 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.
*
*
*
*
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 hamcrest (let's say isValid() returns your own hamcrest matcher):
* 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 allow flexible verification or stubbing.
* {@link Matchers Click 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 {@link 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 {@link ArgumentCaptor} class.
* {@link 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.
*
* E.g: (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.
*
*
*
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, atLeastOnce()).add("three times");
* verify(mockedList, atLeast(2)).add("five times");
* verify(mockedList, atMost(5)).add("three times");
*
*
*
*
* times(1) is the default. Therefore using times(1) explicitly can be
* omitted.
*
*
*
* Read more about doThrow|doAnswer family of methods in paragraph 12.
*
* Initially, {@link Mockito#stubVoid(Object)} was used for stubbing voids.
* Currently stubVoid() is deprecated in favor of {@link Mockito#doThrow(Throwable)}.
* This is because of improved readability and consistency with the family of {@link Mockito#doAnswer(Answer)} methods.
*
*
6. Verification in 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");
*
*
* 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 InOrder object passing only 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);
*
*
*
* 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. You can find further reading
* here.
*
*
* See also {@link Mockito#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.
*
* 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 {@link 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:
*
*
* Allows stubbing with generic {@link Answer} interface.
*
* Yet another controversial feature which was not included in Mockito
* originally. We recommend using simple stubbing with thenReturn() or
* thenThrow() only. Those two should be just enough to test/test-drive
* any clean & simple code.
*
*
12. doThrow()|doAnswer()|doNothing()|doReturn() family of methods for stubbing voids (mostly)
*
* Stubbing voids requires different approach from {@link Mockito#when(Object)} because the compiler does not like void methods inside brackets...
*
* {@link Mockito#doThrow(Throwable)} replaces the {@link Mockito#stubVoid(Object)} method for stubbing voids.
* The main reason is improved readability and consistency with the family of doAnswer() methods.
*
* Use doThrow() when you want to stub a void method with an exception:
*
*
* 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, the full article is here)
*
*
*
* 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!
*
* 1. Sometimes it's impossible to use {@link Mockito#when(Object)} for stubbing spies. 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);
*
*
* 2. 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.
* What will happen is the real method will be called *on mock* but *not on the real instance* you passed to the spy() method.
* Typically you may get a NullPointerException because mock instances don't have fields initiated.
*
*
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 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.
*
*
* Read more about this interesting implementation of Answer: {@link Mockito#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:
*
*
* 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 {@link ArgumentMatcher} class).
* Both techniques can be used for making sure certain arguments where 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 {@link 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 - more reading:
* here
*
* 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 {@link Mockito#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.
* See issue 55 (here)
* or 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
*
* 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 {@link Mockito#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!
*
* 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 {@link BDDMockito} class introduces an alias so that you stub method calls with {@link BDDMockito#given(Object)} method.
* Now it really nicely integrates with the given component of a BDD style test!
*
*
* 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 {@link MockSettings#serializable()}:
*
* List serializableMock = mock(List.class, withSettings().serializable());
*
* 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
*
*
21. (**New**) New annotations: @Captor, @Spy, @InjectMocks (Since 1.8.3)
*
* Release 1.8.3 brings new annotations that may be helpful on occasion:
*
*
*
@{@link Captor} simplifies creation of {@link ArgumentCaptor}
* - useful when the argument to capture is a nasty generic class and you want to avoid compiler warnings
*
@{@link Spy} - you can use it instead {@link Mockito#spy(Object)}.
*
@{@link InjectMocks} - injects mocks into tested object automatically.
*
*
* All new annotations are *only* processed on {@link MockitoAnnotations#initMocks(Object)}
*/
@SuppressWarnings("unchecked")
public class Mockito extends Matchers {
static final MockitoCore MOCKITO_CORE = new MockitoCore();
/**
* The default Answer of every mock if the mock was not stubbed.
* Typically it just returns some empty value.
*
* {@link Answer} can be used to define the return values of unstubbed invocations.
*
* This implementation first tries the global configuration.
* If there is no global configuration then it uses {@link ReturnsEmptyValues} (returns zeros, empty collections, nulls, etc.)
*/
public static final Answer RETURNS_DEFAULTS = Answers.RETURNS_DEFAULTS.get();
/**
* Optional Answer to be used with {@link Mockito#mock(Class, Answer)}
*
* {@link Answer} can be used to define the return values of unstubbed invocations.
*
* This implementation can be helpful when working with legacy code.
* Unstubbed methods often return null. If your code uses the object returned by an unstubbed call you get a NullPointerException.
* This implementation of Answer returns SmartNull instead of null.
* SmartNull gives nicer exception message than NPE because it points out the line where unstubbed method was called. You just click on the stack trace.
*
* ReturnsSmartNulls first tries to return ordinary return values (see {@link ReturnsMoreEmptyValues})
* then it tries to return SmartNull. If the return type is final then plain null is returned.
*
* ReturnsSmartNulls will be probably the default return values strategy in Mockito 2.0
*
* Example:
*
* Foo mock = (Foo.class, RETURNS_SMART_NULLS);
*
* //calling unstubbed method here:
* Stuff stuff = mock.getStuff();
*
* //using object returned by unstubbed call:
* stuff.doSomething();
*
* //Above doesn't yield NullPointerException this time!
* //Instead, SmartNullPointerException is thrown.
* //Exception's cause links to unstubbed mock.getStuff() - just click on the stack trace.
*
*/
public static final Answer RETURNS_SMART_NULLS = Answers.RETURNS_SMART_NULLS.get();
/**
* Optional Answer to be used with {@link Mockito#mock(Class, Answer)}
*
* {@link Answer} can be used to define the return values of unstubbed invocations.
*
* This implementation can be helpful when working with legacy code.
*
* ReturnsMocks first tries to return ordinary return values (see {@link ReturnsMoreEmptyValues})
* then it tries to return mocks. If the return type cannot be mocked (e.g. is final) then plain null is returned.
*
*/
public static final Answer RETURNS_MOCKS = Answers.RETURNS_MOCKS.get();
/**
* Optional Answer to be used with {@link Mockito#mock(Class, Answer)}
*
* Example that shows how deep stub works:
*
* Foo mock = mock(Foo.class, RETURNS_DEEP_STUBS);
*
* // note that we're stubbing a chain of methods here: getBar().getName()
* when(mock.getBar().getName()).thenReturn("deep");
*
* // note that we're chaining method calls: getBar().getName()
* assertEquals("deep", mock.getBar().getName());
*
*
* Verification API does not support 'chaining' so deep stub doesn't change how you do verification.
*
* WARNING:
* This feature should rarely be required for regular clean code! Leave it for legacy code.
* Mocking a mock to return a mock, to return a mock, (...), to return something meaningful
* hints at violation of Law of Demeter or mocking a value object (a well known anti-pattern).
*
* Good quote I've seen one day on the web: every time a mock returns a mock a fairy dies.
*
* This feature will not work when any return type of methods included in the chain cannot be mocked
* (for example: is a primitive or a final class). This is because of java type system.
*/
public static final Answer RETURNS_DEEP_STUBS = Answers.RETURNS_DEEP_STUBS.get();
/**
* Optional Answer to be used with {@link Mockito#mock(Class, Answer)}
*
* {@link Answer} can be used to define the return values of unstubbed invocations.
*
* This implementation can be helpful when working with legacy code.
* When this implementation is used, unstubbed methods will delegate to the real implementation.
* This is a way to create a partial mock object that calls real methods by default.
*
* 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.
*
* Example:
*
* Foo mock = mock(Foo.class, CALLS_REAL_METHODS);
*
* // this calls the real implementation of Foo.getSomething()
* value = mock.getSomething();
*
* when(mock.getSomething()).thenReturn(fakeValue);
*
* // now fakeValue is returned
* value = mock.getSomething();
*
*/
public static final Answer CALLS_REAL_METHODS = Answers.CALLS_REAL_METHODS.get();
/**
* Creates mock object of given class or interface.
*
* See examples in javadoc for {@link Mockito} class
*
* @param classToMock class or interface to mock
* @return mock object
*/
public static T mock(Class classToMock) {
return mock(classToMock, withSettings().defaultAnswer(RETURNS_DEFAULTS));
}
/**
* Specifies mock name. Naming mocks can be helpful for debugging - the name is used in all verification errors.
*
* Beware that naming mocks is not a solution for complex code which uses too many mocks or collaborators.
* If you have too many mocks then refactor the code so that it's easy to test/debug without necessity of naming mocks.
*
* If you use @Mock annotation then you've got naming mocks for free! @Mock uses field name as mock name. {@link Mock Read more.}
*
*
* See examples in javadoc for {@link Mockito} class
*
* @param classToMock class or interface to mock
* @param name of the mock
* @return mock object
*/
public static T mock(Class classToMock, String name) {
return mock(classToMock, withSettings()
.name(name)
.defaultAnswer(RETURNS_DEFAULTS));
}
/**
* @deprecated
* Please use mock(Foo.class, defaultAnswer);
*
* See {@link Mockito#mock(Class, Answer)}
*
* Why it is deprecated? ReturnValues is being replaced by Answer
* for better consistency & interoperability of the framework.
* Answer interface has been in Mockito for a while and it has the same responsibility as ReturnValues.
* There's no point in mainting exactly the same interfaces.
*
* Creates mock with a specified strategy for its return values.
* It's quite advanced feature and typically you don't need it to write decent tests.
* However it can be helpful when working with legacy systems.
*
* Obviously return values are used only when you don't stub the method call.
*
*
*
* @param classToMock class or interface to mock
* @param returnValues default return values for unstubbed methods
*
* @return mock object
*/
@Deprecated
public static T mock(Class classToMock, ReturnValues returnValues) {
return mock(classToMock, withSettings().defaultAnswer(new AnswerReturnValuesAdapter(returnValues)));
}
/**
* Creates mock with a specified strategy for its answers to interactions.
* It's quite advanced feature and typically you don't need it to write decent tests.
* However it can be helpful when working with legacy systems.
*
* It is the default answer so it will be used only when you don't stub the method call.
*
*
*
* @param classToMock class or interface to mock
* @param defaultAnswer default answer for unstubbed methods
*
* @return mock object
*/
public static T mock(Class classToMock, Answer defaultAnswer) {
return mock(classToMock, withSettings().defaultAnswer(defaultAnswer));
}
/**
* Creates a mock with some non-standard settings.
*
* The number of configuration points for a mock grows
* so we need a fluent way to introduce new configuration without adding more and more overloaded Mockito.mock() methods.
* Hence {@link MockSettings}.
*
* Use it carefully and occasionally. What might be reason your test needs non-standard mocks?
* Is the code under test so complicated that it requires non-standard mocks?
* Wouldn't you prefer to refactor the code under test so it is testable in a simple way?
*
* See also {@link Mockito#withSettings()}
*
* See examples in javadoc for {@link Mockito} class
*
* @param classToMock class or interface to mock
* @param mockSettings additional mock settings
* @return mock object
*/
public static T mock(Class classToMock, MockSettings mockSettings) {
return MOCKITO_CORE.mock(classToMock, mockSettings);
}
/**
* Creates a spy of the real object. The spy calls real methods unless they are stubbed.
*
* Real spies should be used carefully and occasionally, for example when dealing with legacy code.
*
* 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.
*
* Example:
*
*
* 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!
*
* 1. Sometimes it's impossible to use {@link Mockito#when(Object)} for stubbing spies. 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);
*
*
* 2. 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.
* What will happen is the real method will be called *on mock* but *not on the real instance* you passed to the spy() method.
* Typically you may get a NullPointerException because mock instances don't have fields initiated.
*
*
* See examples in javadoc for {@link Mockito} class
*
* @param object
* to spy on
* @return a spy of the real object
*/
public static T spy(T object) {
return MOCKITO_CORE.mock((Class) object.getClass(), withSettings()
.spiedInstance(object)
.defaultAnswer(CALLS_REAL_METHODS));
}
/**
* Stubs a method call with return value or an exception. E.g:
*
*
* stub(mock.someMethod()).toReturn(10);
*
* //you can use flexible argument matchers, e.g:
* stub(mock.someMethod(anyString())).toReturn(10);
*
* //setting exception to be thrown:
* stub(mock.someMethod("some arg")).toThrow(new RuntimeException());
*
* //you can stub with different behavior for consecutive method calls.
* //Last stubbing (e.g: toReturn("foo")) determines the behavior for further consecutive calls.
* stub(mock.someMethod("some arg"))
* .toThrow(new RuntimeException())
* .toReturn("foo");
*
*
* Some users find stub() confusing therefore {@link Mockito#when(Object)} is recommended over stub()
*
* For stubbing void methods with throwables see: {@link Mockito#doThrow(Throwable)}
*
* 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 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.
*
* Although it is possible to verify a stubbed invocation, usually it's just redundant.
* Let's say you've stubbed foo.bar().
* If your code cares what foo.bar() returns then something else breaks(often before even verify() gets executed).
* If your code doesn't care what get(0) returns then it should not be stubbed.
* Not convinced? See here.
*
* @param methodCall
* method call
* @return DeprecatedOngoingStubbing object to set stubbed value/exception
*/
public static DeprecatedOngoingStubbing stub(T methodCall) {
return MOCKITO_CORE.stub(methodCall);
}
/**
* Enables stubbing methods. Use it when you want the mock to return particular value when particular method is called.
*
* Simply put: "When the x method is called then return y".
*
* when() is a successor of deprecated {@link Mockito#stub(Object)}
*
* Examples:
*
*
* when(mock.someMethod()).thenReturn(10);
*
* //you can use flexible argument matchers, e.g:
* when(mock.someMethod(anyString())).thenReturn(10);
*
* //setting exception to be thrown:
* when(mock.someMethod("some arg")).thenThrow(new RuntimeException());
*
* //you can set different behavior for consecutive method calls.
* //Last stubbing (e.g: thenReturn("foo")) determines the behavior of further consecutive calls.
* when(mock.someMethod("some arg"))
* .thenThrow(new RuntimeException())
* .thenReturn("foo");
*
* //Alternative, shorter version for consecutive stubbing:
* when(mock.someMethod("some arg"))
* .thenReturn("one", "two");
* //is the same as:
* when(mock.someMethod("some arg"))
* .thenReturn("one")
* .thenReturn("two");
*
* //shorter version for consecutive method calls throwing exceptions:
* when(mock.someMethod("some arg"))
* .thenThrow(new RuntimeException(), new NullPointerException();
*
*
*
* For stubbing void methods with throwables see: {@link Mockito#doThrow(Throwable)}
*
* 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 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.
*
* Although it is possible to verify a stubbed invocation, usually it's just redundant.
* Let's say you've stubbed foo.bar().
* If your code cares what foo.bar() returns then something else breaks(often before even verify() gets executed).
* If your code doesn't care what get(0) returns then it should not be stubbed.
* Not convinced? See here.
*
*
* See examples in javadoc for {@link Mockito} class
* @param methodCall method to be stubbed
*/
public static OngoingStubbing when(T methodCall) {
return MOCKITO_CORE.when(methodCall);
}
/**
* Verifies certain behavior happened once
*
* Arguments passed are compared using equals() method.
* Read about {@link ArgumentCaptor} or {@link ArgumentMatcher} to find out other ways of matching / asserting arguments passed.
*
* Although it is possible to verify a stubbed invocation, usually it's just redundant.
* Let's say you've stubbed foo.bar().
* If your code cares what foo.bar() returns then something else breaks(often before even verify() gets executed).
* If your code doesn't care what get(0) returns then it should not be stubbed.
* Not convinced? See here.
*
*
* See examples in javadoc for {@link Mockito} class
*
* @param mock to be verified
* @return mock object itself
*/
public static T verify(T mock) {
return MOCKITO_CORE.verify(mock, times(1));
}
/**
* Verifies certain behavior happened at least once / exact number of times / never. E.g:
*
* verify(mock, times(5)).someMethod("was called five times");
*
* verify(mock, atLeast(2)).someMethod("was called at least two times");
*
* //you can use flexible argument matchers, e.g:
* verify(mock, atLeastOnce()).someMethod(anyString());
*
*
* times(1) is the default and can be omitted
*
* Arguments passed are compared using equals() method.
* Read about {@link ArgumentCaptor} or {@link ArgumentMatcher} to find out other ways of matching / asserting arguments passed.
*
*
* @param mock to be verified
* @param mode times(x), atLeastOnce() or never()
*
* @return mock object itself
*/
public static T verify(T mock, VerificationMode mode) {
return MOCKITO_CORE.verify(mock, mode);
}
/**
* 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.
* See issue 55 (here)
* or 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
*
*
* @param
* @param mocks to be reset
*/
public static void reset(T ... mocks) {
MOCKITO_CORE.reset(mocks);
}
/**
* Checks if any of given mocks has any unverified interaction.
*
* You can use this method after you verified your mocks - to make sure that nothing
* else was invoked on your mocks.
*
* See also {@link Mockito#never()} - it is more explicit and communicates the intent well.
*
* Stubbed invocations (if called) are also treated as interactions.
*
* 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. You can find further reading
* here.
*
* This method will also detect unverified invocations that occurred before the test method,
* for example: in setUp(), @Before method or in constructor.
* Consider writing nice code that makes interactions only in test methods.
*
*
* Example:
*
*
* //interactions
* mock.doSomething();
* mock.doSomethingUnexpected();
*
* //verification
* verify(mock).doSomething();
*
* //following will fail because 'doSomethingUnexpected()' is unexpected
* verifyNoMoreInteractions(mock);
*
*
*
* See examples in javadoc for {@link Mockito} class
*
* @param mocks to be verified
*/
public static void verifyNoMoreInteractions(Object... mocks) {
MOCKITO_CORE.verifyNoMoreInteractions(mocks);
}
/**
* Verifies that no interactions happened on given mocks.
*
* verifyZeroInteractions(mockOne, mockTwo);
*
* This method will also detect invocations
* that occurred before the test method, for example: in setUp(), @Before method or in constructor.
* Consider writing nice code that makes interactions only in test methods.
*
* See also {@link Mockito#never()} - it is more explicit and communicates the intent well.
*
* See examples in javadoc for {@link Mockito} class
*
* @param mocks to be verified
*/
public static void verifyZeroInteractions(Object... mocks) {
MOCKITO_CORE.verifyNoMoreInteractions(mocks);
}
/**
*
*
* doThrow() replaces stubVoid() because of improved readability and consistency with the family of doAnswer() methods.
*
* Originally, stubVoid() was used for stubbing void methods with exceptions. E.g:
*
*
* stubVoid(mock).toThrow(new RuntimeException()).on().someMethod();
*
* //you can stub with different behavior for consecutive calls.
* //Last stubbing (e.g. toReturn()) determines the behavior for further consecutive calls.
* stubVoid(mock)
* .toThrow(new RuntimeException())
* .toReturn()
* .on().someMethod();
*
*
* See examples in javadoc for {@link Mockito} class
*
* @deprecated Use {@link Mockito#doThrow(Throwable)} method for stubbing voids
*
* @param mock
* to stub
* @return stubbable object that allows stubbing with throwable
*/
public static VoidMethodStubbable stubVoid(T mock) {
return MOCKITO_CORE.stubVoid(mock);
}
/**
* Use doThrow() when you want to stub the void method with an exception.
*
* Stubbing voids requires different approach from {@link Mockito#when(Object)} because the compiler does not like void methods inside brackets...
*
*
* @param toBeThrown to be thrown when the stubbed method is called
* @return stubber - to select a method for stubbing
*/
public static Stubber doThrow(Throwable toBeThrown) {
return MOCKITO_CORE.doAnswer(new ThrowsException(toBeThrown));
}
/**
* Use doCallRealMethod() when you want to call the real implementation of a method.
*
* 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.
*
* See also javadoc {@link Mockito#spy(Object)} to find out more about partial mocks.
* Mockito.spy() is a recommended way of creating partial mocks.
* The reason is it guarantees real methods are called against correctly constructed object because you're responsible for constructing the object passed to spy() method.
*
* Example:
*
* Foo mock = mock(Foo.class);
* doCallRealMethod().when(mock).someVoidMethod();
*
* // this will call the real implementation of Foo.someVoidMethod()
* mock.someVoidMethod();
*
*
* See examples in javadoc for {@link Mockito} class
*
* @return stubber - to select a method for stubbing
*/
public static Stubber doCallRealMethod() {
return MOCKITO_CORE.doAnswer(new CallsRealMethods());
}
/**
* Use doAnswer() when you want to stub a void method with generic {@link Answer}.
*
* Stubbing voids requires different approach from {@link Mockito#when(Object)} because the compiler does not like void methods inside brackets...
*
* See examples in javadoc for {@link Mockito} class
*
* @param answer to answer when the stubbed method is called
* @return stubber - to select a method for stubbing
*/
public static Stubber doAnswer(Answer answer) {
return MOCKITO_CORE.doAnswer(answer);
}
/**
* Use doNothing() for setting void methods to do nothing. Beware that void methods on mocks do nothing by default!
* However, there are rare situations when doNothing() comes handy:
*
* 1. Stubbing consecutive calls on a void method:
*
* doNothing().
* doThrow(new RuntimeException())
* .when(mock).someVoidMethod();
*
* //does nothing the first time:
* mock.someVoidMethod();
*
* //throws RuntimeException the next time:
* mock.someVoidMethod();
*
*
* 2. When you spy real objects and you want the void method to do nothing:
*
* List list = new LinkedList();
* List spy = spy(list);
*
* //let's make clear() do nothing
* doNothing().when(spy).clear();
*
* spy.add("one");
*
* //clear() does nothing, so the list still contains "one"
* spy.clear();
*
*
* See examples in javadoc for {@link Mockito} class
*
* @return stubber - to select a method for stubbing
*/
public static Stubber doNothing() {
return MOCKITO_CORE.doAnswer(new DoesNothing());
}
/**
* Use doReturn() in those rare occasions when you cannot use {@link Mockito#when(Object)}.
*
* Beware that {@link Mockito#when(Object)} is always recommended for stubbing because it is argument type-safe
* and more readable (especially when stubbing consecutive calls).
*
* Here are those rare occasions when doReturn() comes handy:
*
*
* 1. When spying real objects and calling real methods on a spy brings side effects
*
*
* 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);
*
*
* 2. Overriding a previous exception-stubbing:
*
*
* when(mock.foo()).thenThrow(new RuntimeException());
*
* //Impossible: the exception-stubbed foo() method is called so RuntimeException is thrown.
* when(mock.foo()).thenReturn("bar");
*
* //You have to use doReturn() for stubbing:
* doReturn("bar").when(mock).foo();
*
*
* Above scenarios shows a tradeoff of Mockito's ellegant syntax. Note that the scenarios are very rare, though.
* Spying should be sporadic and overriding exception-stubbing is very rare. Not to mention that in general
* overridding stubbing is a potential code smell that points out too much stubbing.
*
* See examples in javadoc for {@link Mockito} class
*
* @param toBeReturned to be returned when the stubbed method is called
* @return stubber - to select a method for stubbing
*/
public static Stubber doReturn(Object toBeReturned) {
return MOCKITO_CORE.doAnswer(new Returns(toBeReturned));
}
/**
* Creates InOrder object that allows verifying mocks in order.
*
*
* InOrder inOrder = inOrder(firstMock, secondMock);
*
* inOrder.verify(firstMock).add("was called first");
* inOrder.verify(secondMock).add("was called second");
*
*
* 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 InOrder object passing only mocks that are relevant for in-order verification.
*
* InOrder verification is 'greedy'. You will hardly every notice it but
* if you want to find out more search for 'greedy' on the Mockito
* wiki pages.
*
* As of Mockito 1.8.4 you can verifyNoMoreInvocations() in order-sensitive way. Read more: {@link InOrder#verifyNoMoreInteractions()}
*
* See examples in javadoc for {@link Mockito} class
*
* @param mocks to be verified in order
*
* @return InOrder object to be used to verify in order
*/
public static InOrder inOrder(Object... mocks) {
return MOCKITO_CORE.inOrder(mocks);
}
/**
* Allows verifying exact number of invocations. E.g:
*
*
* See examples in javadoc for {@link Mockito} class
*
* @param wantedNumberOfInvocations wanted number of invocations
*
* @return verification mode
*/
public static VerificationMode times(int wantedNumberOfInvocations) {
return VerificationModeFactory.times(wantedNumberOfInvocations);
}
/**
* Alias to times(0), see {@link Mockito#times(int)}
*
* Verifies that interaction did not happen. E.g:
*
* verify(mock, never()).someMethod();
*
*
*
* If you want to verify there were NO interactions with the mock
* check out {@link Mockito#verifyZeroInteractions(Object...)}
* or {@link Mockito#verifyNoMoreInteractions(Object...)}
*
* See examples in javadoc for {@link Mockito} class
*
* @return verification mode
*/
public static VerificationMode never() {
return times(0);
}
/**
* Allows at-least-once verification. E.g:
*
*
* See examples in javadoc for {@link Mockito} class
*
* @param maxNumberOfInvocations max number of invocations
*
* @return verification mode
*/
public static VerificationMode atMost(int maxNumberOfInvocations) {
return VerificationModeFactory.atMost(maxNumberOfInvocations);
}
/**
* Allows checking if given method was the only one invoked. E.g:
*
* verify(mock, only()).someMethod();
* //above is a shorthand for following 2 lines of code:
* verify(mock).someMethod();
* verifyNoMoreInvocations(mock);
*
*
*
* See also {@link Mockito#verifyNoMoreInteractions(Object...)}
*
* See examples in javadoc for {@link Mockito} class
*
* @return verification mode
*/
public static VerificationMode only() {
return VerificationModeFactory.only();
}
/**
* First of all, in case of any trouble, I encourage you to read the Mockito FAQ: http://code.google.com/p/mockito/wiki/FAQ
*
* validateMockitoUsage() explicitly validates the framework state to detect invalid use of Mockito.
* However, this feature is optional because Mockito validates the usage all the time... but there is a gotcha so read on.
*
* Examples of incorrect use:
*
* //Oups, someone forgot thenReturn() part:
* when(mock.get());
*
* //Oups, someone put the verified method call inside verify() where it should be outside:
* verify(mock.execute());
*
* //Oups, someone has used EasyMock for too long and forgot to specify the method to verify:
* verify(mock);
*
*
* Mockito throws exceptions if you misuse it so that you know if your tests are written correctly.
* The gotcha is that Mockito does the validation next time you use the framework (e.g. next time you verify, stub, call mock etc.).
* But even though the exception might be thrown in the next test,
* the exception message contains a navigable stack trace element with location of the defect.
* Hence you can click and find the place where Mockito was misused.
*
* Sometimes though, you might want to validate the framework usage explicitly.
* For example, one of the users wanted to put validateMockitoUsage() in his @After method
* so that he knows immediately when he misused Mockito.
* Without it, he would have known about it not sooner than next time he used the framework.
* One more benefit of having validateMockitoUsage() in @After is that jUnit runner will always fail in the test method with defect
* whereas ordinary 'next-time' validation might fail the next test method.
* But even though JUnit might report next test as red, don't worry about it
* and just click at navigable stack trace element in the exception message to instantly locate the place where you misused mockito.
*
* Built-in runner: {@link MockitoJUnitRunner} does validateMockitoUsage() after each test method.
*
* Bear in mind that usually you don't have to validateMockitoUsage()
* and framework validation triggered on next-time basis should be just enough,
* mainly because of enhanced exception message with clickable location of defect.
* However, I would recommend validateMockitoUsage() if you already have sufficient test infrastructure
* (like your own runner or base class for all tests) because adding a special action to @After has zero cost.
*
* See examples in javadoc for {@link Mockito} class
*/
public static void validateMockitoUsage() {
MOCKITO_CORE.validateMockitoUsage();
}
/**
* Allows mock creation with additional mock settings.
*
* Don't use it too often.
* Consider writing simple tests that use simple mocks.
* Repeat after me: simple tests push simple, KISSy, readable & maintainable code.
* If you cannot write a test in a simple way - refactor the code under test.
*
* Examples of mock settings:
*
* //Creates mock with different default answer & name
* Foo mock = mock(Foo.class, withSettings()
* .defaultAnswer(RETURNS_SMART_NULLS)
* .name("cool mockie"));
*
* //Creates mock with different default answer, descriptive name and extra interfaces
* Foo mock = mock(Foo.class, withSettings()
* .defaultAnswer(RETURNS_SMART_NULLS)
* .name("cool mockie")
* .extraInterfaces(Bar.class));
*
* {@link MockSettings} has been introduced for two reasons.
* Firstly, to make it easy to add another mock settings when the demand comes.
* Secondly, to enable combining different mock settings without introducing zillions of overloaded mock() methods.
*
* See javadoc for {@link MockSettings} to learn about possible mock settings.
*
*
* @return mock settings instance with defaults.
*/
public static MockSettings withSettings() {
return new MockSettingsImpl().defaultAnswer(RETURNS_DEFAULTS);
}
/*
* Helps debugging failing tests. Experimental - use at your own risk.
*/
@Deprecated
static MockitoDebugger debug() {
return new MockitoDebuggerImpl();
}
}