org.mockito.quality

Interface MockitoHint

public interface MockitoHint

Stubbing hints were introduced in Mockito 2 in order to improve debuggability while keeping backwards compatibility. As Mockito 2 evolved, hints are replaced by "strict stubbing" API (Strictness). In Mockito 3 we won't be needing hints because Strictness.STRICT_STUBS will be the default for all mocks.

Why hints? To improve productivity when writing Java tests stubbing hints and warnings are printed to standard output.

Hints contain clickable links that take you right to the line of code that contains a possible problem. Those are hints - they not necessarily indicate real problems 100% of the time. This way the developer can:

1. produce cleaner tests - by detecting and removing unused stubs
2. understand why test fails - by detecting stubs that were ineffective due to argument mismatch

We would appreciate feedback about this feature so that we can make Mockito better! Our goal is to provide maximum productivity when testing Java. Join the discussion in issue 384.

How to take advantage of the hints? Use:

• MockitoJUnit.rule()
• MockitoJUnitRunner
• MockitoSession

Cleaner tests without unnecessary stubs

Unnecessary stubs are stubbed method calls that were never realized during test execution. To find out more and see the example test code, see UnnecessaryStubbingException.

Better failure diagnostics by detecting mismatched stubs

When the test fails for a wrong reason, sometimes it's because stubbed method was called with incorrect argument(s). In this scenario, the problem is not often obvious. Hence, Mockito generates a hint to the standard output indicating this scenario. Hint contains a clickable link to the line of code where the potential problem is.

Example:

Let's say the test fails on assertion. Let's say the underlying reason is a stubbed method that was called with different arguments:

 //test:
 Dictionary dictionary = new Dictionary(translator);
 when(translator.translate("Mockito")).thenReturn("cool framework");
 String translated = dictionary.search("Mockito");
 assertEquals("cool framework", translated);

 //code:
 public String search(String word) {
     ...
     return translator.translate("oups");

 

On standard output you'll see a hint with clickable links to both locations: a) stubbing declaration and b) the method call on a stub with mismatched argument.

Note that it is just a warning, not an assertion. The test fails on assertion because it is the assertion's duty to document what the test stands for and what behavior it proves. Hints just makes it quicker to figure out if the test fails for the right reason.

Feedback is very welcome at issue 384.

Since:

2.1.0