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