1 /* 2 * Copyright (c) 2007 Mockito contributors 3 * This program is made available under the terms of the MIT License. 4 */ 5 package org.mockito; 6 7 import org.mockito.listeners.InvocationListener; 8 import org.mockito.mock.MockCreationSettings; 9 import org.mockito.stubbing.Answer; 10 11 import java.io.Serializable; 12 13 /** 14 * Allows mock creation with additional mock settings. 15 * <p/> 16 * Don't use it too often. 17 * Consider writing simple tests that use simple mocks. 18 * Repeat after me: simple tests push simple, KISSy, readable & maintainable code. 19 * If you cannot write a test in a simple way - refactor the code under test. 20 * <p/> 21 * Examples of mock settings: 22 * <pre class="code"><code class="java"> 23 * //Creates mock with different default answer & name 24 * Foo mock = mock(Foo.class, withSettings() 25 * .defaultAnswer(RETURNS_SMART_NULLS) 26 * .name("cool mockie") 27 * ); 28 * 29 * //Creates mock with different default answer, descriptive name and extra interfaces 30 * Foo mock = mock(Foo.class, withSettings() 31 * .defaultAnswer(RETURNS_SMART_NULLS) 32 * .name("cool mockie") 33 * .extraInterfaces(Bar.class)); 34 * </code></pre> 35 * {@link MockSettings} has been introduced for two reasons. 36 * Firstly, to make it easy to add another mock setting when the demand comes. 37 * Secondly, to enable combining together different mock settings without introducing zillions of overloaded mock() methods. 38 */ 39 public interface MockSettings extends Serializable { 40 41 /** 42 * Specifies extra interfaces the mock should implement. Might be useful for legacy code or some corner cases. 43 * For background, see issue 51 <a href="http://code.google.com/p/mockito/issues/detail?id=51">here</a> 44 * <p> 45 * This mysterious feature should be used very occasionally. 46 * The object under test should know exactly its collaborators & dependencies. 47 * If you happen to use it often than please make sure you are really producing simple, clean & readable code. 48 * <p> 49 * Examples: 50 * <pre class="code"><code class="java"> 51 * Foo foo = mock(Foo.class, withSettings().extraInterfaces(Bar.class, Baz.class)); 52 * 53 * //now, the mock implements extra interfaces, so following casting is possible: 54 * Bar bar = (Bar) foo; 55 * Baz baz = (Baz) foo; 56 * </code></pre> 57 * 58 * @param interfaces extra interfaces the should implement. 59 * @return settings instance so that you can fluently specify other settings 60 */ extraInterfaces(Class<?>.... interfaces)61 MockSettings extraInterfaces(Class<?>... interfaces); 62 63 /** 64 * Specifies mock name. Naming mocks can be helpful for debugging - the name is used in all verification errors. 65 * <p> 66 * Beware that naming mocks is not a solution for complex code which uses too many mocks or collaborators. 67 * <b>If you have too many mocks then refactor the code</b> so that it's easy to test/debug without necessity of naming mocks. 68 * <p> 69 * <b>If you use @Mock annotation then you've got naming mocks for free!</b> @Mock uses field name as mock name. {@link Mock Read more.} 70 * <p> 71 * Examples: 72 * <pre class="code"><code class="java"> 73 * Foo foo = mock(Foo.class, withSettings().name("foo")); 74 * 75 * //Below does exactly the same: 76 * Foo foo = mock(Foo.class, "foo"); 77 * </code></pre> 78 * @param name the name of the mock, later used in all verification errors 79 * @return settings instance so that you can fluently specify other settings 80 */ name(String name)81 MockSettings name(String name); 82 83 /** 84 * Specifies the instance to spy on. Makes sense only for spies/partial mocks. 85 * 86 * Sets the instance that will be spied. Actually copies the internal fields of the passed instance to the mock. 87 * <p> 88 * As usual you are going to read <b>the partial mock warning</b>: 89 * Object oriented programming is more or less about tackling complexity by dividing the complexity into separate, specific, SRPy objects. 90 * How does partial mock fit into this paradigm? Well, it just doesn't... 91 * Partial mock usually means that the complexity has been moved to a different method on the same object. 92 * In most cases, this is not the way you want to design your application. 93 * <p> 94 * However, there are rare cases when partial mocks come handy: 95 * dealing with code you cannot change easily (3rd party interfaces, interim refactoring of legacy code etc.) 96 * However, I wouldn't use partial mocks for new, test-driven & well-designed code. 97 * <p> 98 * Enough warnings about partial mocks, see an example how spiedInstance() works: 99 * <pre class="code"><code class="java"> 100 * Foo foo = mock(Foo.class, withSettings().spiedInstance(fooInstance)); 101 * 102 * //Below does exactly the same: 103 * Foo foo = spy(fooInstance); 104 * </code></pre> 105 * 106 * About stubbing for a partial mock, as it is a spy it will always call the real method, unless you use the 107 * <code>doReturn</code>|<code>Throw</code>|<code>Answer</code>|<code>CallRealMethod</code> stubbing style. Example: 108 * 109 * <pre class="code"><code class="java"> 110 * List list = new LinkedList(); 111 * List spy = spy(list); 112 * 113 * //Impossible: real method is called so spy.get(0) throws IndexOutOfBoundsException (the list is yet empty) 114 * when(spy.get(0)).thenReturn("foo"); 115 * 116 * //You have to use doReturn() for stubbing 117 * doReturn("foo").when(spy).get(0); 118 * </code> 119 * 120 * @param instance to spy on 121 * @return settings instance so that you can fluently specify other settings 122 */ spiedInstance(Object instance)123 MockSettings spiedInstance(Object instance); 124 125 /** 126 * Specifies default answers to interactions. 127 * It's quite advanced feature and typically you don't need it to write decent tests. 128 * However it can be helpful when working with legacy systems. 129 * <p> 130 * It is the default answer so it will be used <b>only when you don't</b> stub the method call. 131 * 132 * <pre class="code"><code class="java"> 133 * Foo mock = mock(Foo.class, withSettings().defaultAnswer(RETURNS_SMART_NULLS)); 134 * Foo mockTwo = mock(Foo.class, withSettings().defaultAnswer(new YourOwnAnswer())); 135 * 136 * //Below does exactly the same: 137 * Foo mockTwo = mock(Foo.class, new YourOwnAnswer()); 138 * </code></pre> 139 * 140 * @param defaultAnswer default answer to be used by mock when not stubbed 141 * @return settings instance so that you can fluently specify other settings 142 */ 143 @SuppressWarnings("unchecked") defaultAnswer(Answer defaultAnswer)144 MockSettings defaultAnswer(Answer defaultAnswer); 145 146 /** 147 * Configures the mock to be serializable. With this feature you can use a mock in a place that requires dependencies to be serializable. 148 * <p> 149 * WARNING: This should be rarely used in unit testing. 150 * <p> 151 * The behaviour was implemented for a specific use case of a BDD spec that had an unreliable external dependency. This 152 * was in a web environment and the objects from the external dependency were being serialized to pass between layers. 153 * <p> 154 * Example: 155 * <pre class="code"><code class="java"> 156 * List serializableMock = mock(List.class, withSettings().serializable()); 157 * </code></pre> 158 * 159 * @return settings instance so that you can fluently specify other settings 160 * @since 1.8.1 161 */ serializable()162 MockSettings serializable(); 163 164 /** 165 * Enables real-time logging of method invocations on this mock. Can be used 166 * during test debugging in order to find wrong interactions with this mock. 167 * <p> 168 * Invocations are logged as they happen to the standard output stream. 169 * <p> 170 * Calling this method multiple times makes no difference. 171 * <p> 172 * Example: 173 * <pre class="code"><code class="java"> 174 * List mockWithLogger = mock(List.class, withSettings().verboseLogging()); 175 * </code></pre> 176 * 177 * @return settings instance so that you can fluently specify other settings 178 */ verboseLogging()179 MockSettings verboseLogging(); 180 181 /** 182 * Registers a listener for method invocations on this mock. The listener is 183 * notified every time a method on this mock is called. 184 * <p> 185 * Multiple listeners may be added, but the same object is only added once. 186 * The order, in which the listeners are added, is not guaranteed to be the 187 * order in which the listeners are notified. 188 * 189 * Example: 190 * <pre class="code"><code class="java"> 191 * List mockWithListener = mock(List.class, withSettings().invocationListeners(new YourInvocationListener())); 192 * </code></pre> 193 * 194 * See the {@link InvocationListener listener interface} for more details. 195 * 196 * @param listeners The invocation listeners to add. May not be null. 197 * @return settings instance so that you can fluently specify other settings 198 */ invocationListeners(InvocationListener... listeners)199 MockSettings invocationListeners(InvocationListener... listeners); 200 201 /** 202 * Sets whether this mock should only provide stubbing of methods. 203 * A stub-only mock does not record method 204 * invocations, thus saving memory but 205 * disallowing verification of invocations. 206 * <p> 207 * Example: 208 * <pre class="code"><code class="java"> 209 * List stubOnly = mock(List.class, withSettings().stubOnly()); 210 * </code></pre> 211 * 212 * @return settings instance so that you can fluently specify other settings 213 */ stubOnly()214 MockSettings stubOnly();} 215