1 /* 2 * Copyright (c) 2016 Mockito contributors 3 * This program is made available under the terms of the MIT License. 4 */ 5 package org.mockito.junit; 6 7 import org.junit.rules.MethodRule; 8 import org.mockito.Incubating; 9 import org.mockito.MockSettings; 10 import org.mockito.Mockito; 11 import org.mockito.MockitoAnnotations; 12 import org.mockito.MockitoSession; 13 import org.mockito.quality.MockitoHint; 14 import org.mockito.quality.Strictness; 15 import org.mockito.exceptions.misusing.PotentialStubbingProblem; 16 17 /** 18 * Mockito JUnit Rule helps keeping tests clean. 19 * It initializes mocks, validates usage and detects incorrect stubbing. 20 * Make sure to configure your rule with {@link #strictness(Strictness)} which automatically 21 * detects <strong>stubbing argument mismatches</strong> and is planned to be the default in Mockito v3. 22 * <p> 23 * Since Mockito 2.1.0, JUnit rule emits stubbing warnings and hints to System output (see {@link MockitoHint}). 24 * The JUnit rule can be used instead of {@link MockitoJUnitRunner}. 25 * It requires JUnit at least 4.7. 26 * <p> 27 * The rule adds following behavior: 28 * <ul> 29 * <li> 30 * Since 2.1.0, stubbing warnings and hints are printed to System output. 31 * Hints contain clickable links that take you right to the line of code that contains a possible problem. 32 * <strong>Please</strong> give us feedback about the stubbing warnings of JUnit rules in the issue tracker 33 * (<a href="https://github.com/mockito/mockito/issues/384">issue 384</a>). 34 * It's a new feature of Mockito 2.1.0. It aims to help debugging tests. 35 * If you wish the previous behavior, see {@link MockitoRule#silent()}. 36 * However, we would really like to know why do you wish to silence the warnings! 37 * See also {@link MockitoHint}. 38 * <li> 39 * Initializes mocks annotated with {@link org.mockito.Mock}, 40 * so that explicit usage of {@link MockitoAnnotations#initMocks(Object)} is not necessary. 41 * Mocks are initialized before each test method. 42 * <li> 43 * Validates framework usage after each test method. See javadoc for {@link org.mockito.Mockito#validateMockitoUsage()}. 44 * <li> 45 * It is highly recommended to use the rule with {@link #strictness(Strictness)} configured to {@link Strictness#STRICT_STUBS}. 46 * It drives cleaner tests and improves debugging experience. 47 * The only reason this feature is not turned on by default 48 * is because it would have been an incompatible change 49 * and Mockito strictly follows <a href="http://semver.org">semantic versioning</a>. 50 * 51 * </ul> 52 * Example use: 53 * <pre class="code"><code class="java"> 54 * public class ExampleTest { 55 * 56 * //Creating new rule with recommended Strictness setting 57 * @Rule public MockitoRule rule = MockitoJUnit.rule().strictness(Strictness.STRICT_STUBS); 58 * 59 * @Mock 60 * private List list; 61 * 62 * @Test 63 * public void shouldDoSomething() { 64 * list.add(100); 65 * } 66 * } 67 * </code></pre> 68 * 69 * If you would like to take advantage of Mockito JUnit rule features 70 * but you cannot use the rule because, for example, you use TestNG, there is a solution! 71 * {@link MockitoSession} API is intended to offer cleaner tests and improved debuggability 72 * to users that cannot use Mockito's built-in JUnit support (runner or the rule). 73 * 74 * @since 1.10.17 75 */ 76 public interface MockitoRule extends MethodRule { 77 78 /** 79 * Rule will not report stubbing warnings during test execution. 80 * By default, stubbing warnings are printed to Standard output to help debugging. 81 * Equivalent of configuring {@link #strictness(Strictness)} with {@link Strictness#LENIENT}. 82 * <p> 83 * <strong>Please</strong> give us feedback about the stubbing warnings of JUnit rules 84 * by commenting on GitHub <a href="https://github.com/mockito/mockito/issues/769">issue 769</a>. 85 * It's a new feature of Mockito 2.1.0. It aims to help debugging tests. 86 * We want to make sure the feature is useful. 87 * We would really like to know why do you wish to silence the warnings! 88 * See also {@link MockitoHint}. 89 * <p> 90 * 91 * Example: 92 * <pre class="code"><code class="java"> 93 * public class ExampleTest { 94 * 95 * @Rule 96 * public MockitoRule rule = MockitoJUnit.rule().silent(); 97 * 98 * } 99 * </code></pre> 100 * 101 * @since 2.1.0 102 */ silent()103 MockitoRule silent(); 104 105 /** 106 * The strictness, especially "strict stubs" ({@link Strictness#STRICT_STUBS}) 107 * helps debugging and keeping tests clean. 108 * It's a new feature introduced in Mockito 2.3. 109 * Other levels of strictness - "warn" - ({@link Strictness#WARN}) 110 * and "lenient" ({@link MockitoRule#silent()}) strictness were already present in Mockito 2.1.0. 111 * Version 2.3.0 introduces "strict stubs" ({@link Strictness#STRICT_STUBS}). 112 * 113 * <pre class="code"><code class="java"> 114 * public class ExampleTest { 115 * @Rule 116 * public MockitoRule rule = MockitoJUnit.rule().strictness(Strictness.STRICT_STUBS); 117 * } 118 * </code></pre> 119 * 120 * See Javadoc for {@link Strictness} to learn how strictness influences the behavior of the JUnit rule. 121 * See {@link Strictness#STRICT_STUBS} to learn why is it recommended to use "strict stubbing". 122 * <p> 123 * It is possible to tweak the strictness per test method. 124 * Why would you need it? See the use cases in Javadoc for {@link PotentialStubbingProblem} class. 125 * In order to tweak strictness per stubbing see {@link Mockito#lenient()}, per mock see {@link MockSettings#lenient()}. 126 * 127 * <pre class="code"><code class="java"> 128 * public class ExampleTest { 129 * @Rule 130 * public MockitoRule rule = MockitoJUnit.rule().strictness(Strictness.STRICT_STUBS); 131 * 132 * @Test public void exampleTest() { 133 * //Change the strictness level only for this test method 134 * //Useful for edge cases (see Javadoc for PotentialStubbingProblem class) 135 * mockito.strictness(Strictness.LENIENT); 136 * 137 * //remaining test code 138 * } 139 * } 140 * </code></pre> 141 * 142 * "Strict stubs" are planned to be the default for Mockito v3</li> 143 * We are very eager to hear feedback about "strict stubbing" feature, let us know by commenting on GitHub 144 * <a href="https://github.com/mockito/mockito/issues/769">issue 769</a>. 145 * Strict stubbing is an attempt to improve testability and productivity with Mockito. Tell us what you think! 146 * 147 * @since 2.3.0 148 */ 149 @Incubating strictness(Strictness strictness)150 MockitoRule strictness(Strictness strictness); 151 } 152