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.quality; 6 7 import org.mockito.MockitoSession; 8 import org.mockito.junit.MockitoJUnitRunner; 9 10 /** 11 * Stubbing hints were introduced in Mockito 2 in order to improve debuggability while keeping backwards compatibility. 12 * As Mockito 2 evolved, hints are replaced by "strict stubbing" API ({@link Strictness}). 13 * In Mockito 3 we won't be needing hints because {@link Strictness#STRICT_STUBS} will be the default for all mocks. 14 * <p> 15 * Why hints? 16 * To improve productivity when writing Java tests 17 * stubbing hints and warnings are printed to standard output. 18 * <p> 19 * Hints contain clickable links that take you right to the line of code that contains a possible problem. 20 * Those are hints - they not necessarily indicate real problems 100% of the time. 21 * This way the developer can: 22 * <ol> 23 * <li>produce cleaner tests - by detecting and removing unused stubs</li> 24 * <li>understand why test fails - by detecting stubs that were ineffective due to argument mismatch</li> 25 * </ol> 26 * We would appreciate feedback about this feature so that we can make Mockito better! 27 * Our goal is to provide maximum productivity when testing Java. 28 * Join the discussion in <a href="https://github.com/mockito/mockito/issues/384">issue 384</a>. 29 * <p> 30 * How to take advantage of the hints? Use: 31 * <ul> 32 * <li>{@link org.mockito.junit.MockitoJUnit#rule()}</li> 33 * <li>{@link MockitoJUnitRunner}</li> 34 * <li>{@link MockitoSession}</li> 35 * </ul> 36 * 37 * <h3>Cleaner tests without unnecessary stubs</h3> 38 * Unnecessary stubs are stubbed method calls that were never realized during test execution. 39 * To find out more and see the example test code, see {@link org.mockito.exceptions.misusing.UnnecessaryStubbingException}. 40 * 41 * <h3>Better failure diagnostics by detecting mismatched stubs</h3> 42 * 43 * When the test fails for a wrong reason, sometimes it's because stubbed method was called with incorrect argument(s). 44 * In this scenario, the problem is not often obvious. 45 * Hence, Mockito generates a hint to the standard output indicating this scenario. 46 * Hint contains a clickable link to the line of code where the potential problem is. 47 * <p> 48 * Example: 49 * 50 * <p> 51 * Let's say the test fails on assertion. 52 * Let's say the underlying reason is a stubbed method that was called with different arguments: 53 * <pre class="code"><code class="java"> 54 * //test: 55 * Dictionary dictionary = new Dictionary(translator); 56 * when(translator.translate("Mockito")).thenReturn("cool framework"); 57 * String translated = dictionary.search("Mockito"); 58 * assertEquals("cool framework", translated); 59 * 60 * //code: 61 * public String search(String word) { 62 * ... 63 * return translator.translate("oups"); 64 * 65 * </code></pre> 66 * On standard output you'll see a hint with clickable links to both locations: 67 * a) stubbing declaration and b) the method call on a stub with mismatched argument. 68 * <p> 69 * Note that it is just a warning, not an assertion. 70 * The test fails on assertion because it is the assertion's duty 71 * to document what the test stands for and what behavior it proves. 72 * Hints just makes it quicker to figure out if the test fails for the right reason. 73 * <p> 74 * Feedback is very welcome at <a href="https://github.com/mockito/mockito/issues/384">issue 384</a>. 75 * 76 * @since 2.1.0 77 */ 78 public interface MockitoHint { 79 } 80