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