All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.mockito.Mockito Maven / Gradle / Ivy

Go to download

Mock objects library for java

There is a newer version: 5.13.0
Show newest version
/*
 * 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.framework.DefaultMockitoFramework;
import org.mockito.internal.stubbing.defaultanswers.ReturnsEmptyValues;
import org.mockito.internal.stubbing.defaultanswers.ReturnsMoreEmptyValues;
import org.mockito.internal.verification.VerificationModeFactory;
import org.mockito.junit.MockitoJUnit;
import org.mockito.junit.MockitoRule;
import org.mockito.mock.SerializableMode;
import org.mockito.runners.MockitoJUnitRunner;
import org.mockito.stubbing.Answer;
import org.mockito.stubbing.OngoingStubbing;
import org.mockito.stubbing.Stubber;
import org.mockito.verification.*;

/**
 * 
Mockito logo

 * 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

 *      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)

 *      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)

 * 
 *
 * 
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!
 *
 * 
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. Not convinced? See here.
 * verify(mockedList).get(0);
 * 

 *
 * 
    
 * 
  •  By default, for all methods that return a value, a mock will return either null, a
 * 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(someString -> someString.length() > 5);
 *
 * 

 *
 * 

 * Argument matchers allow flexible verification or stubbing.
 * {@link ArgumentMatchers Click here} {@link org.mockito.hamcrest.MockitoHamcrest 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 {@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.
 * 

 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, 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.
 *
 *
 *
 *
 * 
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. 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.
    • 
 * 

 *
 * 

 *   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: {@link MockitoJUnitRunner} or a rule: {@link MockitoRule}.
 * 

 * Read more here: {@link 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 {@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:
 * 

 *
 * 

 * 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");
 * 

 *
 *
 *
 *
 * 
11. Stubbing with callbacks

 *
 * Allows stubbing with generic {@link 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() {
 *     Object answer(InvocationOnMock invocation) {
 *         Object[] args = invocation.getArguments();
 *         Object mock = invocation.getMock();
 *         return "called with arguments: " + args;
 *     }
 * });
 *
 * //the 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 {@link Mockito#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:
 * 

 * {@link Mockito#doReturn(Object)}
 * 

 * {@link Mockito#doThrow(Throwable...)}
 * 

 * {@link Mockito#doThrow(Class)}
 * 

 * {@link Mockito#doAnswer(Answer)}
 * 

 * {@link Mockito#doNothing()}
 * 

 * {@link Mockito#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, 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 or impractical to use {@link Mockito#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);
 * 
    
 * 
    2. 
 *
 * 
  2. 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.
 * 
    3. 
 *
 * 
  3. 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.
 * 
    4. 
 * 

 *
 *
 *
 *
 * 
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: {@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:
 * 

 *   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 {@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.
 * 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 {@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!
 * 

 * 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 {@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!
 * 

 * 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 {@link 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:
 *
 * 
    
 * 
  • @{@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 mock or spy fields into tested object automatically.
 * 

 *
 * 

 * Note that @{@link InjectMocks} can also be used in combination with the @{@link 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 {@link MockitoAnnotations#initMocks(Object)}.
 * Just like for @{@link Mock} annotation you can use the built-in runner: {@link MockitoJUnitRunner} or rule:
 * {@link 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 within given time span
 *   verify(mock, timeout(100)).someMethod();
 *   //above is an alias to:
 *   verify(mock, timeout(100).times(1)).someMethod();
 *
 *   //passes when someMethod() is called *exactly* 2 times within given time span
 *   verify(mock, timeout(100).times(2)).someMethod();
 *
 *   //passes when someMethod() is called *at least* 2 times within given time span
 *   verify(mock, timeout(100).atLeast(2)).someMethod();
 *
 *   //verifies someMethod() within given time span using given verification mode
 *   //useful only if you have your own custom verification modes.
 *   verify(mock, new Timeout(100, yourOwnVerificationMode)).someMethod();
 * 

 *
 *
 *
 *
 * 
23. Automatic instantiation of @Spies,
 * @InjectMocks and constructor injection goodness (Since 1.9.0)

 *
 * 

 * Mockito will now try to instantiate @{@link Spy} and will instantiate @{@link InjectMocks} fields
 * using constructor injection, setter injection, or field injection.
 * 

 * To take advantage of this feature you need to use {@link MockitoAnnotations#initMocks(Object)}, {@link MockitoJUnitRunner}
 * or {@link MockitoRule}.
 * 

 * Read more about available tricks and the rules of injection in the javadoc for {@link 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 {@link Mockito#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 {@link Mockito#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 interactions and stubbings of the mock:
 *   MockingDetails details = mockingDetails(mock);
 *   details.getInteractions();
 *   details.getStubbings();
 *
 *   //Printing all interactions (including stubbing, unused stubs)
 *   System.out.println(mockingDetails(mock).printInvocations());
 * 

 *
 * For more information see javadoc for {@link 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 ({@link #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 {@link 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 {@link org.mockito.plugins.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 {@link BDDMockito#then(Object)}}
 *
 *
 *
 *
 * 
30. Spying or mocking abstract classes (Since 1.10.12)

 *
 * It is now possible to conveniently spy on abstract classes. Note that overusing spies hints at code design smells (see {@link #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);
 *
 * //Robust API, via settings builder:
 * OtherAbstract spy = mock(OtherAbstract.class, withSettings()
 *    .useConstructor().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 {@link MockSettings#useConstructor()}.
 *
 *
 *
 *
 * 
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 {@link 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 @{@link Mock}, @{@link Spy}, @{@link InjectMocks}, etc.
 *
 * 
    
 *     
  • Annotating the JUnit test class with a @{@link org.junit.runner.RunWith}({@link MockitoJUnitRunner}.class)
    • 
 *     
  • Invoking {@link MockitoAnnotations#initMocks(Object)} in the @{@link org.junit.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 {@link 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 {@link org.mockito.plugins.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 {@link ArgumentMatcher} to reduce the dependency on {@link ArgumentCaptor}.
 * If you need to verify that the input to a function call on a mock was correct, then you would normally
 * use the {@link 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))).willReturn(null);
 * 

 *
 * 
37. Java 8 Custom Answer Support (Since 2.1.0)

 * 

 * As the {@link 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 {@link org.mockito.invocation.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 functions answer and answerVoid can be found in {@link AdditionalAnswers} to create the answer object
 * using the interfaces in {@link org.mockito.internal.stubbing.answers.AnswerFunctionalInterfaces} support is provided
 * for functions with 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 AnswerFunctionalInterfaces.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 AnswerFunctionalInterfaces.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:
 *
 * 

 * {@literal @}{@code MyAnnotation
 *  class Foo {
 *    List 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 {@link org.mockito.plugins.MockMaker} is used.
 *
 * 
39. Mocking final types, enums and final methods (Since 2.1.0)

 *
 * Mockito now offers an {@link 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 feature is turned off by default because it is based on completely different mocking mechanism
 * that requires 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.
 *
 * 

 * 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
 */
@SuppressWarnings("unchecked")
public class Mockito extends ArgumentMatchers {

    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;

    /**
     * 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 3.0.0
     * 

     * Example:
     * 

     *   Foo mock = 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;

    /**
     * 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;

    /**
     * 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());
     * 

     * 

     *
     * 

     * 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.
     * 

     *
     * 

     * Please note that this answer will return existing mocks that matches the stub. This
     * behavior is ok with deep stubs and allows verification to work on the last mock of the chain.
     * 

     *   when(mock.getBar(anyString()).getThingy().getName()).thenReturn("deep");
     *
     *   mock.getBar("candy bar").getThingy().getName();
     *
     *   assertSame(mock.getBar(anyString()).getThingy().getName(), mock.getBar(anyString()).getThingy().getName());
     *   verify(mock.getBar("candy bar").getThingy()).getName();
     *   verify(mock.getBar(anyString()).getThingy()).getName();
     * 

     * 

     *
     * 

     * Verification only works with the last mock in the chain. You can use verification modes.
     * 

     *   when(person.getAddress(anyString()).getStreet().getName()).thenReturn("deep");
     *   when(person.getAddress(anyString()).getStreet(Locale.ITALIAN).getName()).thenReturn("deep");
     *   when(person.getAddress(anyString()).getStreet(Locale.CHINESE).getName()).thenReturn("deep");
     *
     *   person.getAddress("the docks").getStreet().getName();
     *   person.getAddress("the docks").getStreet().getLongName();
     *   person.getAddress("the docks").getStreet(Locale.ITALIAN).getName();
     *   person.getAddress("the docks").getStreet(Locale.CHINESE).getName();
     *
     *   // note that we are actually referring to the very last mock in the stubbing chain.
     *   InOrder inOrder = inOrder(
     *       person.getAddress("the docks").getStreet(),
     *       person.getAddress("the docks").getStreet(Locale.CHINESE),
     *       person.getAddress("the docks").getStreet(Locale.ITALIAN)
     *   );
     *   inOrder.verify(person.getAddress("the docks").getStreet(), times(1)).getName();
     *   inOrder.verify(person.getAddress("the docks").getStreet()).getLongName();
     *   inOrder.verify(person.getAddress("the docks").getStreet(Locale.ITALIAN), atLeast(1)).getName();
     *   inOrder.verify(person.getAddress("the docks").getStreet(Locale.CHINESE)).getName();
     * 

     * 

     *
     * 

     * How deep stub work internally?
     * 

     *   //this:
     *   Foo mock = mock(Foo.class, RETURNS_DEEP_STUBS);
     *   when(mock.getBar().getName(), "deep");
     *
     *   //is equivalent of
     *   Foo foo = mock(Foo.class);
     *   Bar bar = mock(Bar.class);
     *   when(foo.getBar()).thenReturn(bar);
     *   when(bar.getName()).thenReturn("deep");
     * 

     * 

     *
     * 

     * 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;

    /**
     * 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;

    /**
     * Optional Answer to be used with {@link Mockito#mock(Class, Answer)}.
     *
     * Allows Builder mocks to return itself whenever a method is invoked that returns a Type equal
     * to the class or a superclass.
     *
     * 
Keep in mind this answer uses the return type of a method.
     * If this type is assignable to the class of the mock, it will return the mock.
     * Therefore if you have a method returning a superclass (for example {@code Object}) it will match and return the mock.

     *
     * Consider a HttpBuilder used in a HttpRequesterWithHeaders.
     *
     * 

     * public class HttpRequesterWithHeaders {
     *
     *      private HttpBuilder builder;
     *
     *      public HttpRequesterWithHeaders(HttpBuilder builder) {
     *          this.builder = builder;
     *      }
     *
     *      public String request(String uri) {
     *          return builder.withUrl(uri)
     *                  .withHeader("Content-type: application/json")
     *                  .withHeader("Authorization: Bearer")
     *                  .request();
     *      }
     *  }
     *
     *  private static class HttpBuilder {
     *
     *      private String uri;
     *      private List<String> headers;
     *
     *      public HttpBuilder() {
     *          this.headers = new ArrayList<String>();
     *      }
     *
     *       public HttpBuilder withUrl(String uri) {
     *           this.uri = uri;
     *           return this;
     *       }
     *
     *       public HttpBuilder withHeader(String header) {
     *           this.headers.add(header);
     *           return this;
     *       }
     *
     *       public String request() {
     *          return uri + headers.toString();
     *       }
     *  }
     * 

     *
     * The following test will succeed
     *
     * 

     * @Test
     *  public void use_full_builder_with_terminating_method() {
     *      HttpBuilder builder = mock(HttpBuilder.class, RETURNS_SELF);
     *      HttpRequesterWithHeaders requester = new HttpRequesterWithHeaders(builder);
     *      String response = "StatusCode: 200";
     *
     *      when(builder.request()).thenReturn(response);
     *
     *      assertThat(requester.request("URI")).isEqualTo(response);
     *  }
     * 

     */
    public static final Answer RETURNS_SELF = Answers.RETURNS_SELF;

    /**
     * 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));
    }

    /**
     * Returns a MockingDetails instance that enables inspecting a particular object for Mockito related information.
     * Can be used to find out if given object is a Mockito mock
     * or to find out if a given mock is a spy or mock.
     * 

     * In future Mockito versions MockingDetails may grow and provide other useful information about the mock,
     * e.g. invocations, stubbing info, etc.
     *
     * @param toInspect - object to inspect. null input is allowed.
     * @return A {@link org.mockito.MockingDetails} instance.
     * @since 1.9.5
     */
    public static MockingDetails mockingDetails(Object toInspect) {
        return MOCKITO_CORE.mockingDetails(toInspect);
    }

    /**
     * Creates mock with a specified strategy for its answers to interactions.
     * It's quite an 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, RETURNS_SMART_NULLS);
     *   Foo mockTwo = mock(Foo.class, new YourOwnAnswer());
     * 

     *
     * 
See examples in javadoc for {@link Mockito} class

     *
     * @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}.
     * 

     *   Listener mock = mock(Listener.class, withSettings()
     *     .name("firstListner").defaultBehavior(RETURNS_SMART_NULLS));
     *   );
     * 

     * 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 tackles 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 or impractical to use {@link Mockito#when(Object)} for stubbing spies.
     * Therefore for spies it is recommended to always use doReturn|Answer|Throw()|CallRealMethod
     * 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);
     * 
    
     * 
    2. 
     *
     * 
  2. 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.
    3. 
     *
     * 
  3. 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.
     * 
    4. 
     * 

     * 

     * See examples in javadoc for {@link Mockito} class
     *
     * 
Note that the spy won't have any annotations of the spied type, because CGLIB won't rewrite them.
     * It may troublesome for code that rely on the spy to have these annotations.

     *
     *
     * @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));
    }

    /**
     * Please refer to the documentation of {@link #spy(Object)}.
     * Overusing spies hints at code design smells.
     * 

     * This method, in contrast to the original {@link #spy(Object)}, creates a spy based on class instead of an object.
     * Sometimes it is more convenient to create spy based on the class and avoid providing an instance of a spied object.
     * This is particularly useful for spying on abstract classes because they cannot be instantiated.
     * See also {@link MockSettings#useConstructor()}.
     * 

     * Examples:
     * 

     *   SomeAbstract spy = spy(SomeAbstract.class);
     *
     *   //Robust API, via settings builder:
     *   OtherAbstract spy = mock(OtherAbstract.class, withSettings()
     *      .useConstructor().defaultAnswer(CALLS_REAL_METHODS));
     *
     *   //Mocking a non-static inner abstract class:
     *   InnerAbstract spy = mock(InnerAbstract.class, withSettings()
     *      .useConstructor().outerInstance(outerInstance).defaultAnswer(CALLS_REAL_METHODS));
     * 

     *
     * @param classToSpy the class to spy
     * @param  type of the spy
     * @return a spy of the provided class
     * @since 1.10.12
     */
    @Incubating
    public static  T spy(Class classToSpy) {
        return MOCKITO_CORE.mock(classToSpy, withSettings()
                .useConstructor()
                .defaultAnswer(CALLS_REAL_METHODS));
    }

    /**
     * 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".
     *
     * 

     * 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
     * @return OngoingStubbing object used to stub fluently.
     *         Do not create a reference to this returned object.
     */
    public static  OngoingStubbing when(T methodCall) {
        return MOCKITO_CORE.when(methodCall);
    }

    /**
     * Verifies certain behavior happened once.
     * 

     * Alias to verify(mock, times(1)) E.g:
     * 

     *   verify(mock).someMethod("some arg");
     * 

     * Above is equivalent to:
     * 

     *   verify(mock, times(1)).someMethod("some arg");
     * 

     * 

     * 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.
     * For more information see the 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  The Type of the mocks
     * @param mocks to be reset
     */
    public static  void reset(T ... mocks) {
        MOCKITO_CORE.reset(mocks);
    }

    /**
     * Use this method in order to only clear invocations, when stubbing is non-trivial. Use-cases can be:
     * 
    
     *     
  • You are using a dependency injection framework to inject your mocks.
    • 
     *     
  • The mock is used in a stateful scenario. For example a class is Singleton which depends on your mock.
    • 
     * 

     *
     * Try to avoid this method at all costs. Only clear invocations if you are unable to efficiently test your program.
     * @param  The type of the mocks
     * @param mocks The mocks to clear the invocations for
     */
    public static  void clearInvocations(T ... mocks) {
        MOCKITO_CORE.clearInvocations(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);
    }

    /**
     * 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...
     * 

     * Example:
     *
     * 

     *   doThrow(new RuntimeException()).when(mock).someVoidMethod();
     * 

     *
     * @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.stubber().doThrow(toBeThrown);
    }

    /**
     * Use doThrow() when you want to stub the void method with an exception.
     * 

     * A new exception instance will be created for each method invocation.
     * 

     * Stubbing voids requires different approach from {@link Mockito#when(Object)} because the compiler
     * does not like void methods inside brackets...
     * 

     * Example:
     *
     * 

     *   doThrow(RuntimeException.class).when(mock).someVoidMethod();
     * 

     *
     * @param toBeThrown to be thrown when the stubbed method is called
     * @return stubber - to select a method for stubbing
     * @since 2.1.0
     */
    public static Stubber doThrow(Class toBeThrown) {
        return MOCKITO_CORE.stubber().doThrow(toBeThrown);
    }

    /**
     * Same as {@link #doThrow(Class)} but sets consecutive exception classes to be thrown. Remember to use
     * doThrow() when you want to stub the void method to throw several exception of specified class.
     * 

     * A new exception instance will be created for each method invocation.
     * 

     * Stubbing voids requires different approach from {@link Mockito#when(Object)} because the compiler
     * does not like void methods inside brackets...
     * 

     * Example:
     *
     * 

     *   doThrow(RuntimeException.class, BigFailure.class).when(mock).someVoidMethod();
     * 

     *
     * @param toBeThrown to be thrown when the stubbed method is called
     * @param toBeThrownNext next to be thrown when the stubbed method is called
     * @return stubber - to select a method for stubbing
     * @since 2.1.0
     */
    // Additional method helps users of JDK7+ to hide heap pollution / unchecked generics array creation
    @SuppressWarnings ({"unchecked", "varargs"})
    public static Stubber doThrow(Class toBeThrown, Class... toBeThrownNext) {
        return MOCKITO_CORE.stubber().doThrow(toBeThrown, toBeThrownNext);
    }


    /**
     * 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
     * @since 1.9.5
     */
    public static Stubber doCallRealMethod() {
        return MOCKITO_CORE.stubber().doCallRealMethod();
    }

    /**
     * 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...
     * 

     * Example:
     *
     * 

     *  doAnswer(new Answer() {
     *      public Object answer(InvocationOnMock invocation) {
     *          Object[] args = invocation.getArguments();
     *          Mock mock = invocation.getMock();
     *          return null;
     *      }})
     *  .when(mock).someMethod();
     * 

     * 

     * 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.stubber().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. 
     * 
  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();
     * 
    
     * 
    3. 
     * 

     * 

     * See examples in javadoc for {@link Mockito} class
     *
     * @return stubber - to select a method for stubbing
     */
    public static Stubber doNothing() {
        return MOCKITO_CORE.stubber().doNothing();
    }

    /**
     * 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. 
     *
     * 
  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();
     * 
    
     * 
    3. 
     * 

     *
     * Above scenarios shows a tradeoff of Mockito's elegant 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.stubber().doReturn(toBeReturned);
    }

    /**
     * Same as {@link #doReturn(Object)} but sets consecutive values to be returned. Remember to 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", "bar", "qix");
     *
     *   //You have to use doReturn() for stubbing:
     *   doReturn("foo", "bar", "qix").when(spy).get(0);
     * 
    
     * 
    2. 
     *
     * 
  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", "foo", "qix");
     *
     *   //You have to use doReturn() for stubbing:
     *   doReturn("bar", "foo", "qix").when(mock).foo();
     * 
    
     * 
    3. 
     * 

     *
     * Above scenarios shows a trade-off of Mockito's elegant 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
     * @param toBeReturnedNext to be returned in consecutive calls when the stubbed method is called
     * @return stubber - to select a method for stubbing
     * @since 2.1.0
     */
    @SuppressWarnings({"unchecked", "varargs"})
    public static Stubber doReturn(Object toBeReturned, Object... toBeReturnedNext) {
        return MOCKITO_CORE.stubber().doReturn(toBeReturned, toBeReturnedNext);
    }

    /**
     * Creates {@link org.mockito.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', but you will hardly ever notice it.
     * If you want to find out more, read
     * this wiki page.
     * 

     * 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);
    }

    /**
     * Ignores stubbed methods of given mocks 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 {@link Mockito#verifyNoMoreInteractions(Object...)}
     * Other words: all *stubbed* methods of given mocks are marked *verified* so that they don't get in a way during verifyNoMoreInteractions().
     * 

     * This method changes the input mocks! This method returns input mocks just for convenience.
     * 

     * Ignored stubs will also be ignored for verification inOrder, including {@link org.mockito.InOrder#verifyNoMoreInteractions()}.
     * See the second example.
     * 

     * Example:
     * 

     *  //mocking lists for the sake of the example (if you mock List in real you will burn in hell)
     *  List mock1 = mock(List.class), mock2 = mock(List.class);
     *
     *  //stubbing mocks:
     *  when(mock1.get(0)).thenReturn(10);
     *  when(mock2.get(0)).thenReturn(20);
     *
     *  //using mocks by calling stubbed get(0) methods:
     *  System.out.println(mock1.get(0)); //prints 10
     *  System.out.println(mock2.get(0)); //prints 20
     *
     *  //using mocks by calling clear() methods:
     *  mock1.clear();
     *  mock2.clear();
     *
     *  //verification:
     *  verify(mock1).clear();
     *  verify(mock2).clear();
     *
     *  //verifyNoMoreInteractions() fails because get() methods were not accounted for.
     *  try { verifyNoMoreInteractions(mock1, mock2); } catch (NoInteractionsWanted e);
     *
     *  //However, if we ignore stubbed methods then we can verifyNoMoreInteractions()
     *  verifyNoMoreInteractions(ignoreStubs(mock1, mock2));
     *
     *  //Remember that ignoreStubs() *changes* the input mocks and returns them for convenience.
     * 

     * Ignoring stubs can be used with verification in order:
     * 

     *  List list = mock(List.class);
     *  when(mock.get(0)).thenReturn("foo");
     *
     *  list.add(0);
     *  System.out.println(list.get(0)); //we don't want to verify this
     *  list.clear();
     *
     *  InOrder inOrder = inOrder(ignoreStubs(list));
     *  inOrder.verify(list).add(0);
     *  inOrder.verify(list).clear();
     *  inOrder.verifyNoMoreInteractions();
     * 

     *
     * @since 1.9.0
     * @param mocks input mocks that will be changed
     * @return the same mocks that were passed in as parameters
     */
    public static Object[] ignoreStubs(Object... mocks) {
        return MOCKITO_CORE.ignoreStubs(mocks);
    }

    /**
     * Allows verifying exact number of invocations. E.g:
     * 

     *   verify(mock, times(2)).someMethod("some arg");
     * 

     *
     * 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:
     * 

     *   verify(mock, atLeastOnce()).someMethod("some arg");
     * 

     * Alias to atLeast(1).
     * 

     * See examples in javadoc for {@link Mockito} class
     *
     * @return verification mode
     */
    public static VerificationMode atLeastOnce() {
        return VerificationModeFactory.atLeastOnce();
    }

    /**
     * Allows at-least-x verification. E.g:
     * 

     *   verify(mock, atLeast(3)).someMethod("some arg");
     * 

     *
     * See examples in javadoc for {@link Mockito} class
     *
     * @param minNumberOfInvocations minimum number of invocations
     *
     * @return verification mode
     */
    public static VerificationMode atLeast(int minNumberOfInvocations) {
        return VerificationModeFactory.atLeast(minNumberOfInvocations);
    }

    /**
     * Allows at-most-x verification. E.g:
     * 

     *   verify(mock, atMost(3)).someMethod("some arg");
     * 

     *
     * 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 non-greedy verification in order.  For example
     * 

     *   inOrder.verify( mock, calls( 2 )).someMethod( "some arg" );
     * 

     * 
    
     * 
  • will not fail if the method is called 3 times, unlike times( 2 )
    • 
     * 
  • will not mark the third invocation as verified, unlike atLeast( 2 )
    • 
     * 

     * This verification mode can only be used with in order verification.
     * @param wantedNumberOfInvocations number of invocations to verify
     * @return  verification mode
     */
    public static VerificationMode calls( int wantedNumberOfInvocations ){
        return VerificationModeFactory.calls( wantedNumberOfInvocations );
    }

    /**
     * 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();
    }

    /**
     * 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 has not already happened. May be useful for testing in concurrent
     * conditions.
     * 

     * This differs from {@link Mockito#after after()} in that after() will wait the full period, unless
     * the final test result is known early (e.g. if a never() fails), whereas timeout() will stop early as soon
     * as verification passes, producing different behaviour when used with times(2), for example, which can pass
     * and then later fail. In that case, timeout would pass as soon as times(2) passes, whereas after would run until
     * times(2) failed, and then fail.
     * 

     * This feature should be used rarely - figure out a better way of testing your multi-threaded system.
     * 

     *   //passes when someMethod() is called within given time span
     *   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 before the given timeout
     *   verify(mock, timeout(100).times(2)).someMethod();
     *
     *   //equivalent: this also passes as soon as someMethod() has been called 2 times before the given timeout
     *   verify(mock, timeout(100).atLeast(2)).someMethod();
     *
     *   //verifies someMethod() within given time span using given verification mode
     *   //useful only if you have your own custom verification modes.
     *   verify(mock, new Timeout(100, yourOwnVerificationMode)).someMethod();
     * 

     *
     * See examples in javadoc for {@link Mockito} class
     *
     * @param millis - time span in milliseconds
     *
     * @return verification mode
     */
    public static VerificationWithTimeout timeout(long millis) {
        return new Timeout(millis, VerificationModeFactory.times(1));
    }

    /**
     * Allows verifying over a given period. It causes a verify to wait for a specified period of time for a desired
     * interaction rather than failing immediately if has not already happened. May be useful for testing in concurrent
     * conditions.
     * 

     * This differs from {@link Mockito#timeout timeout()} in that after() will wait the full period, whereas timeout()
     * will stop early as soon as verification passes, producing different behaviour when used with times(2), for example,
     * which can pass and then later fail. In that case, timeout would pass as soon as times(2) passes, whereas after would
     * run the full time, which point it will fail, as times(2) has failed.
     * 

     * 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.
     * 

     *   //passes after 100ms, if someMethod() has only been called once at that time.
     *   verify(mock, after(100)).someMethod();
     *   //above is an alias to:
     *   verify(mock, after(100).times(1)).someMethod();
     *
     *   //passes if someMethod() is called *exactly* 2 times after the given timespan
     *   verify(mock, after(100).times(2)).someMethod();
     *
     *   //passes if someMethod() has not been called after the given timespan
     *   verify(mock, after(100).never()).someMethod();
     *
     *   //verifies someMethod() after a given time span using given verification mode
     *   //useful only if you have your own custom verification modes.
     *   verify(mock, new After(100, yourOwnVerificationMode)).someMethod();
     * 

     *
     * See examples in javadoc for {@link Mockito} class
     *
     * @param millis - time span in milliseconds
     *
     * @return verification mode
     */
    public static VerificationAfterDelay after(long millis) {
        return new After(millis, VerificationModeFactory.times(1));
    }

    /**
     * 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
     * 

     * 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:
     * 

     * //Oops, thenReturn() part is missing:
     * when(mock.get());
     *
     * //Oops, verified method call is inside verify() where it should be on the outside:
     * verify(mock.execute());
     *
     * //Oops, missing 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 and rule 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.
     * 

     * Both built-in runner: {@link MockitoJUnitRunner} and rule: {@link MockitoRule} do 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);
    }

    /**
     * Adds a description to be printed if verification fails.
     * 

     * verify(mock, description("This will print on failure")).someMethod("some arg");
     * 

     * @param description The description to print on failure.
     * @return verification mode
     * @since 2.1.0
     */
    public static VerificationMode description(String description) {
        return times(1).description(description);
    }

    /**
     * @deprecated - please use {@link MockingDetails#printInvocations()}.
     */
    @Deprecated
    static MockitoDebugger debug() {
        return new MockitoDebuggerImpl();
    }

    /**
     * For advanced users or framework integrators. See {@link MockitoFramework} class.
     *
     * @since 2.1.0
     */
    @Incubating
    public static MockitoFramework framework() {
        return new DefaultMockitoFramework();
    }
}
    

    

    
            
    
            







    
© 2015 - 2024 Weber Informatics LLC | Privacy Policy