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.MockSettings; 9 import org.mockito.Mockito; 10 import org.mockito.MockitoAnnotations; 11 import org.mockito.MockitoSession; 12 import org.mockito.exceptions.misusing.PotentialStubbingProblem; 13 import org.mockito.quality.MockitoHint; 14 import org.mockito.quality.Strictness; 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#openMocks(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="https://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 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 */ silent()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" - ({@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 * See Javadoc for {@link Strictness} to learn how strictness influences the behavior of the JUnit rule. 120 * See {@link Strictness#STRICT_STUBS} to learn why is it recommended to use "strict stubbing". 121 * <p> 122 * It is possible to tweak the strictness per test method. 123 * Why would you need it? See the use cases in Javadoc for {@link PotentialStubbingProblem} class. 124 * In order to tweak strictness per stubbing see {@link Mockito#lenient()}, per mock see {@link MockSettings#lenient()}. 125 * 126 * <pre class="code"><code class="java"> 127 * public class ExampleTest { 128 * @Rule 129 * public MockitoRule rule = MockitoJUnit.rule().strictness(Strictness.STRICT_STUBS); 130 * 131 * @Test public void exampleTest() { 132 * //Change the strictness level only for this test method 133 * //Useful for edge cases (see Javadoc for PotentialStubbingProblem class) 134 * mockito.strictness(Strictness.LENIENT); 135 * 136 * //remaining test code 137 * } 138 * } 139 * </code></pre> 140 * 141 * "Strict stubs" are planned to be the default for Mockito v3</li> 142 * We are very eager to hear feedback about "strict stubbing" feature, let us know by commenting on GitHub 143 * <a href="https://github.com/mockito/mockito/issues/769">issue 769</a>. 144 * Strict stubbing is an attempt to improve testability and productivity with Mockito. Tell us what you think! 145 * 146 * @since 2.3.0 147 */ strictness(Strictness strictness)148 MockitoRule strictness(Strictness strictness); 149 } 150