org.mockito.quality.MockitoHint Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of mockito-core Show documentation
Mock objects library for java
The newest version!
/*
 * Copyright (c) 2016 Mockito contributors
 * This program is made available under the terms of the MIT License.
 */
package org.mockito.quality;

import org.mockito.MockitoSession;
import org.mockito.junit.MockitoJUnitRunner;

/**
 * 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 ({@link Strictness}).
 * In Mockito 3 we won't be needing hints because {@link 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:
 * 

 *   produce cleaner tests - by detecting and removing unused stubs
 *   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:
 * 

 *     {@link org.mockito.junit.MockitoJUnit#rule()}
 *     {@link MockitoJUnitRunner}
 *     {@link 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 {@link org.mockito.exceptions.misusing.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
 */
public interface MockitoHint {}