Home | History | Annotate | Download | only in junit 
      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  *     &#064;Rule public MockitoRule rule = MockitoJUnit.rule().strictness(Strictness.STRICT_STUBS);
     58  *
     59  *     &#064;Mock
     60  *     private List list;
     61  *
     62  *     &#064;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      *     &#064;Rule
     96      *     public MockitoRule rule = MockitoJUnit.rule().silent();
     97      *
     98      * }
     99      * </code></pre>
    100      *
    101      * @since 2.1.0
    102      */
    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      *     &#064;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      *     &#064;Rule
    130      *     public MockitoRule rule = MockitoJUnit.rule().strictness(Strictness.STRICT_STUBS);
    131      *
    132      *     &#064;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
    150     MockitoRule strictness(Strictness strictness);
    151 }
    152