org.mockito.junit

Interface MockitoRule

All Superinterfaces:

org.junit.rules.MethodRule

public interface MockitoRule
extends org.junit.rules.MethodRule

Mockito JUnit Rule helps keeping tests clean. It initializes mocks, validates usage and detects incorrect stubbing. Make sure to configure your rule with strictness(Strictness) which automatically detects stubbing argument mismatches and is planned to be the default in Mockito v3.

Since Mockito 2.1.0, JUnit rule emits stubbing warnings and hints to System output (see MockitoHint). The JUnit rule can be used instead of MockitoJUnitRunner. It requires JUnit at least 4.7.

The rule adds following behavior:

• Since 2.1.0, stubbing warnings and hints are printed to System output. Hints contain clickable links that take you right to the line of code that contains a possible problem. Please give us feedback about the stubbing warnings of JUnit rules in the issue tracker (issue 384). It's a new feature of Mockito 2.1.0. It aims to help debugging tests. If you wish the previous behavior, see silent(). However, we would really like to know why do you wish to silence the warnings! See also MockitoHint.
• Initializes mocks annotated with Mock, so that explicit usage of MockitoAnnotations.initMocks(Object) is not necessary. Mocks are initialized before each test method.
• Validates framework usage after each test method. See javadoc for Mockito.validateMockitoUsage().
• It is highly recommended to use the rule with strictness(Strictness) configured to Strictness.STRICT_STUBS. It drives cleaner tests and improves debugging experience. The only reason this feature is not turned on by default is because it would have been an incompatible change and Mockito strictly follows semantic versioning.

Example use:

 public class ExampleTest {

     //Creating new rule with recommended Strictness setting
     @Rule public MockitoRule rule = MockitoJUnit.rule().strictness(Strictness.STRICT_STUBS);

     @Mock
     private List list;

     @Test
     public void shouldDoSomething() {
         list.add(100);
     }
 }
 

If you would like to take advantage of Mockito JUnit rule features but you cannot use the rule because, for example, you use TestNG, there is a solution! MockitoSession API is intended to offer cleaner tests and improved debuggability to users that cannot use Mockito's built-in JUnit support (runner or the rule).

Since:

1.10.17

Method Summary

Modifier and Type	Method and Description
MockitoRule	silent() Rule will not report stubbing warnings during test execution.
MockitoRule	strictness(Strictness strictness) The strictness, especially "strict stubs" (Strictness.STRICT_STUBS) helps debugging and keeping tests clean.

Methods inherited from interface org.junit.rules.MethodRule

apply

Method Detail

silent

MockitoRule silent()

Rule will not report stubbing warnings during test execution. By default, stubbing warnings are printed to Standard output to help debugging. Equivalent of configuring strictness(Strictness) with Strictness.LENIENT.

Please give us feedback about the stubbing warnings of JUnit rules by commenting on GitHub issue 769. It's a new feature of Mockito 2.1.0. It aims to help debugging tests. We want to make sure the feature is useful. We would really like to know why do you wish to silence the warnings! See also MockitoHint.

Example:

 public class ExampleTest {

     @Rule
     public MockitoRule rule = MockitoJUnit.rule().silent();

 }
 

Since:

2.1.0

strictness

@Incubating
MockitoRule strictness(Strictness strictness)

The strictness, especially "strict stubs" (Strictness.STRICT_STUBS) helps debugging and keeping tests clean. It's a new feature introduced in Mockito 2.3. Other levels of strictness - "Warn" - current default (Strictness.WARN) and "lenient" (silent()) strictness were already present in Mockito 2.1.0. Version 2.3.0 introduces "strict stubs" (Strictness.STRICT_STUBS).

 public class ExampleTest {
     @Rule
     public MockitoRule rule = MockitoJUnit.rule().strictness(Strictness.STRICT_STUBS);
 }
 

How strictness level influences the behavior of JUnit rule:

1. Strictness.LENIENT - equivalent of silent() - no added behavior. The default of Mockito 1.x
2. Strictness.WARN - helps keeping tests clean and with debuggability. Reports console warnings about unused stubs and stubbing argument mismatches (see MockitoHint). The default of Mockito 2.x
3. Strictness.STRICT_STUBS - ensures clean tests, reduces test code duplication, improves debuggability. See the details in the Javadoc for Strictness.STRICT_STUBS.

It is possible to tweak the strictness per test method. Why would you need it? See the use cases in Javadoc for PotentialStubbingProblem class.

 public class ExampleTest {
     @Rule
     public MockitoRule rule = MockitoJUnit.rule().strictness(Strictness.STRICT_STUBS);

     @Test public void exampleTest() {
         //Change the strictness level only for this test method
         //Useful for edge cases (see Javadoc for PotentialStubbingProblem class)
         mockito.strictness(Strictness.LENIENT);

         //remaining test code
     }
 }
 

"Strict stubs" are tentatively planned to be the default for Mockito v3

We are very eager to hear feedback about "strict stubbing" feature, let us know by commenting on GitHub issue 769. Strict stubbing is an attempt to improve testability and productivity with Mockito. Tell us what you think!

Since:

2.3.0