1 /* 2 * Copyright (c) 2007 Mockito contributors 3 * This program is made available under the terms of the MIT License. 4 */ 5 6 package org.mockito.stubbing; 7 8 import org.mockito.Incubating; 9 import org.mockito.invocation.InvocationOnMock; 10 11 /** 12 * Allow to validate this answer is correct for the given invocation. 13 * 14 * <p> 15 * When tests use a shared answer implementation, it may happen the answer cannot be used 16 * with some methods. Implementing this interface indicate to Mockito it needs to verify the answer is compatible 17 * with the stubbed interaction. 18 * </p> 19 * 20 * <p> 21 * In the following example the answer is shared and work as expected... 22 * 23 * <pre class="code"><code class="java"> 24 * when(mock.someMethod(anyString())).then(doSomethingTricky()); 25 * 26 * static Answer doSomethingTricky() { 27 * return new Answer() { 28 * Object answer(InvocationOnMock invocation) { 29 * // tricky stuff 30 * } 31 * }); 32 * } 33 * </code></pre> 34 * </p> 35 * 36 * <p> 37 * ...then later there's some refactoring or some new code that want to use the answer, 38 * however it is not compatible anymore. In this example the answer may throw an exception because 39 * the Answer cannot work with the return type or some parameter types. 40 * 41 * <pre class="code"><code class="java"> 42 * when(mock.someMethod(anyString(), anyInt())).then(doSomethingTricky()); // fail at answer execution time 43 * when(mock.incompatibleMethod(anyVararg())).then(doSomethingTricky()); // fail at answer execution time 44 * </code></pre> 45 * </p> 46 * 47 * <p> 48 * Instead of having an exception raised later at answer <em>execution time</em>, one can make this answer 49 * validable at <em>stub time</em> by implementing this contract. 50 * 51 * <pre class="code"><code class="java"> 52 * when(mock.incompatibleMethod(anyVararg())).then(doSomethingTricky()); // fail at answer stub time 53 * 54 * static Answer doSomethingTricky() { 55 * return new TrickyAnswer(); 56 * } 57 * 58 * class Tricky Answer implements Answer, ValidableAnswer { 59 * public Object answer(InvocationOnMock invocation) { 60 * // tricky stuff 61 * } 62 * 63 * public void validateFor(InvocationOnMock invocation) { 64 * // perform validation for this interaction 65 * } 66 * } 67 * </code></pre> 68 * </p> 69 * 70 * @since 2.3.8 71 */ 72 @Incubating 73 public interface ValidableAnswer { 74 75 /** 76 * Validation of the answer at <em>stub time</em> for the given invocation. 77 * 78 * <p> 79 * This method will be called by Mockito. 80 * </p> 81 * 82 * <p> 83 * The implementation must throw an MockitoException to indicate that this answer is not valid for 84 * the given invocation. If the validation succeed the implementation must simply return without throwing. 85 * </p> 86 * 87 * @param invocation The stubbed invocation 88 * 89 * @since 2.3.8 90 */ validateFor(InvocationOnMock invocation)91 void validateFor(InvocationOnMock invocation); 92 93 } 94