Interface MockSettings
-
- All Superinterfaces:
Serializable
@NotExtensible public interface MockSettings extends Serializable
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 and 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 and 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));
MockSettings
has been introduced for two reasons. Firstly, to make it easy to add another mock setting when the demand comes. Secondly, to enable combining different mock settings without introducing zillions of overloaded mock() methods.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description <T> MockCreationSettings<T>
build(Class<T> typeToMock)
Creates immutable view of mock settings used later by Mockito.<T> MockCreationSettings<T>
buildStatic(Class<T> classToMock)
Creates immutable view of mock settings used later by Mockito, for use within a static mocking.MockSettings
defaultAnswer(Answer defaultAnswer)
Specifies default answers to interactions.MockSettings
extraInterfaces(Class<?>... interfaces)
Specifies extra interfaces the mock should implement.MockSettings
genericTypeToMock(Type genericTypeToMock)
Specifies the generic type of the mock, preserving the information lost to Java type erasure.MockSettings
invocationListeners(InvocationListener... listeners)
Registers a listener for method invocations on this mock.MockSettings
lenient()
Deprecated.Usestrictness(Strictness)
instead.MockSettings
mockMaker(String mockMaker)
Specifies theMockMaker
for the mock.MockSettings
name(String name)
Specifies mock name.MockSettings
outerInstance(Object outerClassInstance)
Makes it possible to mock non-static inner classes in conjunction withuseConstructor(Object...)
.MockSettings
serializable()
Configures the mock to be serializable.MockSettings
serializable(SerializableMode mode)
Configures the mock to be serializable with a specific serializable mode.MockSettings
spiedInstance(Object instance)
Specifies the instance to spy on.MockSettings
strictness(Strictness strictness)
Specifies strictness level for the mock.MockSettings
stubbingLookupListeners(StubbingLookupListener... listeners)
Add stubbing lookup listener to the mock object.MockSettings
stubOnly()
A stub-only mock does not record method invocations, thus saving memory but disallowing verification of invocations.MockSettings
useConstructor(Object... args)
Mockito attempts to use constructor when creating instance of the mock.MockSettings
verboseLogging()
Enables real-time logging of method invocations on this mock.MockSettings
verificationStartedListeners(VerificationStartedListener... listeners)
Registers a listener(s) that will be notified when user starts verification.MockSettings
withoutAnnotations()
By default, Mockito makes an attempt to preserve all annotation metadata on the mocked type and its methods to mirror the mocked type as closely as possible.
-
-
-
Method Detail
-
extraInterfaces
MockSettings extraInterfaces(Class<?>... interfaces)
Specifies extra interfaces the mock should implement. Might be useful for legacy code or some corner cases.This mysterious feature should be used very occasionally. The object under test should know exactly its collaborators and dependencies. If you happen to use it often than please make sure you are really producing simple, clean and readable code.
Examples:
Foo foo = mock(Foo.class, withSettings().extraInterfaces(Bar.class, Baz.class)); //now, the mock implements extra interfaces, so following casting is possible: Bar bar = (Bar) foo; Baz baz = (Baz) foo;
- Parameters:
interfaces
- extra interfaces the mock should implement.- Returns:
- settings instance so that you can fluently specify other settings
-
name
MockSettings name(String name)
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.
Read more.
Examples:
Foo foo = mock(Foo.class, withSettings().name("foo")); //Below does exactly the same: Foo foo = mock(Foo.class, "foo");
- Parameters:
name
- the name of the mock, later used in all verification errors- Returns:
- settings instance so that you can fluently specify other settings
-
spiedInstance
MockSettings spiedInstance(Object instance)
Specifies the instance to spy on. Makes sense only for spies/partial mocks. Sets the instance that will be spied. Actually copies the internal fields of the passed instance to the mock.As usual, you are going to read the partial mock warning: Object oriented programming is more or less about 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 and well-designed code.
Enough warnings about partial mocks, see an example how spiedInstance() works:
About stubbing for a partial mock, as it is a spy it will always call the real method, unless you use theFoo foo = mock(Foo.class, withSettings().spiedInstance(fooInstance)); //Below does exactly the same: Foo foo = spy(fooInstance);
doReturn
|Throw
|Answer
|CallRealMethod
stubbing style. 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);
- Parameters:
instance
- to spy on- Returns:
- settings instance so that you can fluently specify other settings
-
defaultAnswer
MockSettings defaultAnswer(Answer defaultAnswer)
Specifies default 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.
Foo mock = mock(Foo.class, withSettings().defaultAnswer(RETURNS_SMART_NULLS)); Foo mockTwo = mock(Foo.class, withSettings().defaultAnswer(new YourOwnAnswer())); //Below does exactly the same: Foo mockTwo = mock(Foo.class, new YourOwnAnswer());
- Parameters:
defaultAnswer
- default answer to be used by mock when not stubbed- Returns:
- settings instance so that you can fluently specify other settings
-
serializable
MockSettings serializable()
Configures the mock to be 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.
Example:
List serializableMock = mock(List.class, withSettings().serializable());
- Returns:
- settings instance so that you can fluently specify other settings
- Since:
- 1.8.1
-
serializable
MockSettings serializable(SerializableMode mode)
Configures the mock to be serializable with a specific serializable mode. 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.
List serializableMock = mock(List.class, withSettings().serializable(SerializableMode.ACROSS_CLASSLOADERS));
- Parameters:
mode
- serialization mode- Returns:
- settings instance so that you can fluently specify other settings
- Since:
- 1.10.0
-
verboseLogging
MockSettings verboseLogging()
Enables real-time logging of method invocations on this mock. Can be used during test debugging in order to find wrong interactions with this mock.Invocations are logged as they happen to the standard output stream.
Calling this method multiple times makes no difference.
Example:
List mockWithLogger = mock(List.class, withSettings().verboseLogging());
- Returns:
- settings instance so that you can fluently specify other settings
-
stubbingLookupListeners
MockSettings stubbingLookupListeners(StubbingLookupListener... listeners)
Add stubbing lookup listener to the mock object. Multiple listeners may be added, and they will be notified in an orderly fashion. For use cases and more info seeStubbingLookupListener
. Example:List mockWithListener = mock(List.class, withSettings().stubbingLookupListeners(new YourStubbingLookupListener()));
- Parameters:
listeners
- The stubbing lookup listeners to add. May not be null.- Returns:
- settings instance so that you can fluently specify other settings
- Since:
- 2.24.6
-
invocationListeners
MockSettings invocationListeners(InvocationListener... listeners)
Registers a listener for method invocations on this mock. The listener is notified every time a method on this mock is called.Multiple listeners may be added, and they will be notified in the order they were supplied. Example:
See theList mockWithListener = mock(List.class, withSettings().invocationListeners(new YourInvocationListener()));
listener interface
for more details.- Parameters:
listeners
- The invocation listeners to add. May not be null.- Returns:
- settings instance so that you can fluently specify other settings
-
verificationStartedListeners
MockSettings verificationStartedListeners(VerificationStartedListener... listeners)
Registers a listener(s) that will be notified when user starts verification. SeeVerificationStartedListener
on how such listener can be useful.When multiple listeners are added, they are notified in order they were supplied. There is no reason to supply multiple listeners, but we wanted to keep the API simple and consistent with
invocationListeners(InvocationListener...)
.Throws exception when any of the passed listeners is null or when the entire vararg array is null.
- Parameters:
listeners
- to be notified when user starts verification.- Returns:
- settings instance so that you can fluently specify other settings
- Since:
- 2.11.0
-
stubOnly
MockSettings stubOnly()
A stub-only mock does not record method invocations, thus saving memory but disallowing verification of invocations.Example:
List stubOnly = mock(List.class, withSettings().stubOnly());
- Returns:
- settings instance so that you can fluently specify other settings
-
useConstructor
MockSettings useConstructor(Object... args)
Mockito attempts to use constructor when creating instance of the mock. This is particularly useful for spying on abstract classes. See alsoMockito.spy(Class)
.Example:
//Robust API, via settings builder: OtherAbstract spy = mock(OtherAbstract.class, withSettings() .useConstructor().defaultAnswer(CALLS_REAL_METHODS)); //Mocking an abstract class with constructor arguments 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));
- Parameters:
args
- The arguments to pass to the constructor. Not passing any arguments means that a parameter-less constructor will be called- Returns:
- settings instance so that you can fluently specify other settings
- Since:
- 2.7.14 (useConstructor with no arguments was supported since 1.10.12)
-
outerInstance
MockSettings outerInstance(Object outerClassInstance)
Makes it possible to mock non-static inner classes in conjunction withuseConstructor(Object...)
.Example:
InnerClass mock = mock(InnerClass.class, withSettings() .useConstructor().outerInstance(outerInstance).defaultAnswer(CALLS_REAL_METHODS));
- Returns:
- settings instance so that you can fluently specify other settings
- Since:
- 1.10.12
-
withoutAnnotations
MockSettings withoutAnnotations()
By default, Mockito makes an attempt to preserve all annotation metadata on the mocked type and its methods to mirror the mocked type as closely as possible. If this is not desired, this option can be used to disable this behavior.- Returns:
- settings instance so that you can fluently specify other settings
- Since:
- 1.10.13
-
build
<T> MockCreationSettings<T> build(Class<T> typeToMock)
Creates immutable view of mock settings used later by Mockito. Framework integrators can use this method to create instances of creation settings and use them in advanced use cases, for example to create invocations withInvocationFactory
, or to implement customMockHandler
. SinceMockCreationSettings
isNotExtensible
, Mockito public API needs a creation method for this type.- Type Parameters:
T
- type to mock- Parameters:
typeToMock
- class to mock- Returns:
- immutable view of mock settings
- Since:
- 2.10.0
-
buildStatic
<T> MockCreationSettings<T> buildStatic(Class<T> classToMock)
Creates immutable view of mock settings used later by Mockito, for use within a static mocking. Framework integrators can use this method to create instances of creation settings and use them in advanced use cases, for example to create invocations withInvocationFactory
, or to implement customMockHandler
. SinceMockCreationSettings
isNotExtensible
, Mockito public API needs a creation method for this type.- Type Parameters:
T
- type to mock- Parameters:
classToMock
- class to mock- Returns:
- immutable view of mock settings
- Since:
- 2.10.0
-
lenient
@Deprecated MockSettings lenient()
Deprecated.Usestrictness(Strictness)
instead. Lenient mocks bypass "strict stubbing" validation (seeStrictness.STRICT_STUBS
). When mock is declared as lenient none of its stubbings will be checked for potential stubbing problems such as 'unnecessary stubbing' (UnnecessaryStubbingException
) or for 'stubbing argument mismatch'PotentialStubbingProblem
.
For more information and an elaborate example, seeFoo mock = mock(Foo.class, withSettings.lenient());
Mockito.lenient()
.
-
strictness
MockSettings strictness(Strictness strictness)
Specifies strictness level for the mock. The default strictness level is determined by the rule/runner used. If you are using no rule/runner, the default strictness level is LENIENTFoo defaultStrictMock = mock(Foo.class); Foo explicitStrictMock = mock(Foo.class, withSettings().strictness(Strictness.STRICT_STUBS)); Foo lenientMock = mock(Foo.class, withSettings().strictness(Strictness.LENIENT));
- Parameters:
strictness
- the strictness level to set on mock- Returns:
- settings instance so that you can fluently specify other settings
- Since:
- 4.6.0
-
mockMaker
MockSettings mockMaker(String mockMaker)
Specifies theMockMaker
for the mock. The default depends on your project as described in the class documentation ofMockMaker
. You should usually use the default, this option primarily exists to ease migrations. You may specify either one of the constants fromMockMakers
,Object mock = Mockito.mock(Object.class, Mockito.withSettings() .mockMaker(MockMakers.INLINE));
or thebinary name
of a class which implements theMockMaker
interface.Object mock = Mockito.mock(Object.class, Mockito.withSettings() .mockMaker("org.awesome.mockito.AwesomeMockMaker"));
- Parameters:
mockMaker
- theMockMaker
to use for the mock- Returns:
- settings instance so that you can fluently specify other settings
- Since:
- 4.8.0
-
genericTypeToMock
MockSettings genericTypeToMock(Type genericTypeToMock)
Specifies the generic type of the mock, preserving the information lost to Java type erasure.- Parameters:
genericTypeToMock
-- Returns:
-
-