| /* |
| * Copyright (c) 2007 Mockito contributors |
| * This program is made available under the terms of the MIT License. |
| */ |
| package org.mockito; |
| |
| import java.util.Collection; |
| import org.mockito.internal.stubbing.answers.ReturnsArgumentAt; |
| import org.mockito.internal.stubbing.answers.ReturnsElementsOf; |
| import org.mockito.internal.stubbing.defaultanswers.ForwardsInvocations; |
| import org.mockito.stubbing.Answer; |
| import org.mockito.stubbing.Answer1; |
| import org.mockito.stubbing.Answer2; |
| import org.mockito.stubbing.Answer3; |
| import org.mockito.stubbing.Answer4; |
| import org.mockito.stubbing.Answer5; |
| import org.mockito.stubbing.VoidAnswer1; |
| import org.mockito.stubbing.VoidAnswer2; |
| import org.mockito.stubbing.VoidAnswer3; |
| import org.mockito.stubbing.VoidAnswer4; |
| import org.mockito.stubbing.VoidAnswer5; |
| |
| import static org.mockito.internal.stubbing.answers.AnswerFunctionalInterfaces.toAnswer; |
| |
| /** |
| * Additional answers provides factory methods for answers. |
| * |
| * <p>Currently offer answers that can return the parameter of an invocation at a certain position, |
| * along with answers that draw on a strongly typed interface to provide a neater way to write custom answers |
| * that either return a value or are void (see answer interfaces in {@link org.mockito.stubbing}). |
| * |
| * <p>See factory methods for more information : {@link #returnsFirstArg}, {@link #returnsSecondArg}, |
| * {@link #returnsLastArg}, {@link #returnsArgAt}, {@link #answer} and {@link #answerVoid} |
| * |
| * @since 1.9.5 |
| */ |
| @SuppressWarnings("unchecked") |
| public class AdditionalAnswers { |
| /** |
| * Returns the first parameter of an invocation. |
| * |
| * <p> |
| * This additional answer could be used at stub time using the |
| * <code>then|do|will{@link org.mockito.stubbing.Answer}</code> methods. For example : |
| * |
| * <pre class="code"><code class="java"> |
| * given(carKeyFob.authenticate(carKey)).will(returnsFirstArg()); |
| * doAnswer(returnsFirstArg()).when(carKeyFob).authenticate(carKey); |
| * </code></pre> |
| * </p> |
| * |
| * <p> |
| * This methods works with varargs as well, mockito will expand the vararg to return the argument |
| * at the given position. Suppose the following signature : |
| * |
| * <pre class="code"><code class="java"> |
| * interface Person { |
| * Dream remember(Dream... dreams); |
| * } |
| * |
| * // returns dream1 |
| * given(person.remember(dream1, dream2, dream3, dream4)).will(returnsFirstArg()); |
| * </code></pre> |
| * |
| * Mockito will return the vararg array if the first argument is a vararg in the method |
| * and if the return type has the same type as the vararg array. |
| * |
| * <pre class="code"><code class="java"> |
| * interface Person { |
| * Dream[] remember(Dream... otherDreams); |
| * } |
| * |
| * // returns otherDreams (happens to be a 4 elements array) |
| * given(person.remember(dream1, dream2, dream3, dream4)).will(returnsFirstArg()); |
| * </code></pre> |
| * </p> |
| * |
| * @param <T> Return type of the invocation. |
| * @return Answer that will return the first argument of the invocation. |
| * |
| * @since 1.9.5 |
| */ |
| public static <T> Answer<T> returnsFirstArg() { |
| return (Answer<T>) new ReturnsArgumentAt(0); |
| } |
| |
| /** |
| * Returns the second parameter of an invocation. |
| * |
| * <p> |
| * This additional answer could be used at stub time using the |
| * <code>then|do|will{@link org.mockito.stubbing.Answer}</code> methods. For example : |
| * |
| * <pre class="code"><code class="java"> |
| * given(trader.apply(leesFormula, onCreditDefaultSwap)).will(returnsSecondArg()); |
| * doAnswer(returnsSecondArg()).when(trader).apply(leesFormula, onCreditDefaultSwap); |
| * </code></pre> |
| * </p> |
| * |
| * <p> |
| * This methods works with varargs as well, mockito will expand the vararg to return the argument |
| * at the given position. Suppose the following signature : |
| * |
| * <pre class="code"><code class="java"> |
| * interface Person { |
| * Dream remember(Dream dream, Dream... otherDreams); |
| * } |
| * |
| * // returns dream2 |
| * given(person.remember(dream1, dream2, dream3, dream4)).will(returnsSecondArg()); |
| * </code></pre> |
| * |
| * Mockito will return the vararg array if the second argument is a vararg in the method |
| * and if the return type has the same type as the vararg array. |
| * |
| * <pre class="code"><code class="java"> |
| * interface Person { |
| * Dream[] remember(Dream dream1, Dream... otherDreams); |
| * } |
| * |
| * // returns otherDreams (happens to be a 3 elements array) |
| * given(person.remember(dream1, dream2, dream3, dream4)).will(returnsSecondArg()); |
| * </code></pre> |
| * </p> |
| * |
| * @param <T> Return type of the invocation. |
| * @return Answer that will return the second argument of the invocation. |
| * |
| * @since 1.9.5 |
| */ |
| public static <T> Answer<T> returnsSecondArg() { |
| return (Answer<T>) new ReturnsArgumentAt(1); |
| } |
| |
| /** |
| * Returns the last parameter of an invocation. |
| * |
| * <p> |
| * This additional answer could be used at stub time using the |
| * <code>then|do|will{@link org.mockito.stubbing.Answer}</code> methods. For example : |
| * |
| * <pre class="code"><code class="java"> |
| * given(person.remember(dream1, dream2, dream3, dream4)).will(returnsLastArg()); |
| * doAnswer(returnsLastArg()).when(person).remember(dream1, dream2, dream3, dream4); |
| * </code></pre> |
| * </p> |
| * |
| * <p> |
| * This methods works with varargs as well, mockito will expand the vararg to return the argument |
| * at the given position. Suppose the following signature : |
| * |
| * <pre class="code"><code class="java"> |
| * interface Person { |
| * Dream remember(Dream dream, Dream... otherDreams); |
| * } |
| * |
| * // returns dream4 |
| * given(person.remember(dream1, dream2, dream3, dream4)).will(returnsLastArg()); |
| * </code></pre> |
| * |
| * Mockito will return the vararg array if the given {@code position} targets the vararg index in the method |
| * and if the return type has the same type as the vararg array. |
| * |
| * <pre class="code"><code class="java"> |
| * interface Person { |
| * Dream[] remember(Dream dream1, Dream dream2, Dream dream3, Dream... otherDreams); |
| * } |
| * |
| * // returns otherDreams (happens to be a single element array) |
| * given(person.remember(dream1, dream2, dream3, dream4)).will(returnsLastArg()); |
| * </code></pre> |
| * </p> |
| * |
| * @param <T> Return type of the invocation. |
| * @return Answer that will return the last argument of the invocation. |
| * |
| * @since 1.9.5 |
| */ |
| public static <T> Answer<T> returnsLastArg() { |
| return (Answer<T>) new ReturnsArgumentAt(ReturnsArgumentAt.LAST_ARGUMENT); |
| } |
| |
| /** |
| * Returns the parameter of an invocation at the given position. |
| * |
| * <p> |
| * This additional answer could be used at stub time using the |
| * <code>then|do|will{@link org.mockito.stubbing.Answer}</code> methods. For example : |
| * |
| * <pre class="code"><code class="java"> |
| * given(person.remember(dream1, dream2, dream3, dream4)).will(returnsArgAt(3)); |
| * doAnswer(returnsArgAt(3)).when(person).remember(dream1, dream2, dream3, dream4); |
| * </code></pre> |
| * </p> |
| * |
| * <p> |
| * This methods works with varargs as well, mockito will expand the vararg to return the argument |
| * at the given position. Suppose the following signature : |
| * |
| * <pre class="code"><code class="java"> |
| * interface Person { |
| * Dream remember(Dream dream, Dream... otherDreams); |
| * } |
| * |
| * // returns dream 3 |
| * given(person.remember(dream1, dream2, dream3, dream4)).will(returnsArgAt(2)); |
| * </code></pre> |
| * |
| * Mockito will return the vararg array if the given {@code position} targets the vararg index in the method |
| * and if the return type has the same type as the vararg array. |
| * |
| * <pre class="code"><code class="java"> |
| * interface Person { |
| * Dream[] remember(Dream dream, Dream... otherDreams); |
| * } |
| * |
| * // returns otherDreams array (contains dream2, dream,3, dream4) |
| * given(person.remember(dream1, dream2, dream3, dream4)).will(returnsArgAt(1)); |
| * </code></pre> |
| * </p> |
| * |
| * @param <T> Return type of the invocation. |
| * @param position index of the argument from the list of arguments. |
| * @return Answer that will return the argument from the given position in the argument's list |
| * |
| * @since 1.9.5 |
| */ |
| public static <T> Answer<T> returnsArgAt(int position) { |
| return (Answer<T>) new ReturnsArgumentAt(position); |
| } |
| |
| /** |
| * An answer that directly forwards the calls to the delegate. The delegate may or may not be of the same type as the mock. |
| * If the type is different, a matching method needs to be found on delegate type otherwise an exception is thrown. |
| * <p> |
| * Useful for spies or partial mocks of objects that are difficult to mock |
| * or spy using the usual spy API. Possible use cases: |
| * <ul> |
| * <li>Final classes but with an interface</li> |
| * <li>Already custom proxied object</li> |
| * <li>Special objects with a finalize method, i.e. to avoid executing it 2 times</li> |
| * </ul> |
| * |
| * <p> |
| * The difference with the regular spy: |
| * <ul> |
| * <li> |
| * The regular spy ({@link Mockito#spy(Object)}) contains <strong>all</strong> state from the spied instance |
| * and the methods are invoked on the spy. The spied instance is only used at mock creation to copy the state from. |
| * If you call a method on a regular spy and it internally calls other methods on this spy, those calls are remembered |
| * for verifications, and they can be effectively stubbed. |
| * </li> |
| * <li> |
| * The mock that delegates simply delegates all methods to the delegate. |
| * The delegate is used all the time as methods are delegated onto it. |
| * If you call a method on a mock that delegates and it internally calls other methods on this mock, |
| * those calls are <strong>not</strong> remembered for verifications, stubbing does not have effect on them, too. |
| * Mock that delegates is less powerful than the regular spy but it is useful when the regular spy cannot be created. |
| * </li> |
| * </ul> |
| * An example with a final class that we want to delegate to: |
| * <p> |
| * <pre class="code"><code class="java"> |
| * final class DontYouDareToMockMe implements list { ... } |
| * |
| * DontYouDareToMockMe awesomeList = new DontYouDareToMockMe(); |
| * |
| * List mock = mock(List.class, delegatesTo(awesomeList)); |
| * </code></pre> |
| * |
| * <p> |
| * This feature suffers from the same drawback as the spy. |
| * The mock will call the delegate if you use regular when().then() stubbing style. |
| * Since the real implementation is called this might have some side effects. |
| * Therefore you should to use the doReturn|Throw|Answer|CallRealMethod stubbing style. Example: |
| * |
| * <pre class="code"><code class="java"> |
| * List listWithDelegate = mock(List.class, AdditionalAnswers.delegatesTo(awesomeList)); |
| * |
| * //Impossible: real method is called so listWithDelegate.get(0) throws IndexOutOfBoundsException (the list is yet empty) |
| * when(listWithDelegate.get(0)).thenReturn("foo"); |
| * |
| * //You have to use doReturn() for stubbing |
| * doReturn("foo").when(listWithDelegate).get(0); |
| * </code></pre> |
| * |
| * @param delegate The delegate to forward calls to. It does not have to be of the same type as the mock (although it usually is). |
| * The only requirement is that the instance should have compatible method signatures including the return values. |
| * Only the methods that were actually executed on the mock need to be present on the delegate type. |
| * @return the answer |
| * |
| * @since 1.9.5 |
| */ |
| public static <T> Answer<T> delegatesTo(Object delegate) { |
| return (Answer<T>) new ForwardsInvocations(delegate); |
| } |
| |
| /** |
| * Returns elements of the collection. Keeps returning the last element forever. |
| * Might be useful on occasion when you have a collection of elements to return. |
| * <p> |
| * <pre class="code"><code class="java"> |
| * //this: |
| * when(mock.foo()).thenReturn(1, 2, 3); |
| * |
| * //is equivalent to: |
| * when(mock.foo()).thenAnswer(new ReturnsElementsOf(Arrays.asList(1, 2, 3))); |
| * </code></pre> |
| * |
| * @param elements The collection of elements to return. |
| * @return the answer |
| * |
| * @since 1.9.5 |
| */ |
| public static <T> Answer<T> returnsElementsOf(Collection<?> elements) { |
| return (Answer<T>) new ReturnsElementsOf(elements); |
| } |
| |
| /** |
| * Creates an answer from a functional interface - allows for a strongly typed answer to be created |
| * ideally in Java 8 |
| * @param answer interface to the answer - which is expected to return something |
| * @param <T> return type |
| * @param <A> input parameter type 1 |
| * @return the answer object to use |
| * @since 2.1.0 |
| */ |
| @Incubating |
| public static <T, A> Answer<T> answer(Answer1<T, A> answer) { |
| return toAnswer(answer); |
| } |
| |
| /** |
| * Creates an answer from a functional interface - allows for a strongly typed answer to be created |
| * ideally in Java 8 |
| * @param answer interface to the answer - a void method |
| * @param <A> input parameter type 1 |
| * @return the answer object to use |
| * @since 2.1.0 |
| */ |
| @Incubating |
| public static <A> Answer<Void> answerVoid(VoidAnswer1<A> answer) { |
| return toAnswer(answer); |
| } |
| |
| /** |
| * Creates an answer from a functional interface - allows for a strongly typed answer to be created |
| * ideally in Java 8 |
| * @param answer interface to the answer - which is expected to return something |
| * @param <T> return type |
| * @param <A> input parameter type 1 |
| * @param <B> input parameter type 2 |
| * @return the answer object to use |
| * @since 2.1.0 |
| */ |
| @Incubating |
| public static <T, A, B> Answer<T> answer(Answer2<T, A, B> answer) { |
| return toAnswer(answer); |
| } |
| |
| /** |
| * Creates an answer from a functional interface - allows for a strongly typed answer to be created |
| * ideally in Java 8 |
| * @param answer interface to the answer - a void method |
| * @param <A> input parameter type 1 |
| * @param <B> input parameter type 2 |
| * @return the answer object to use |
| * @since 2.1.0 |
| */ |
| @Incubating |
| public static <A, B> Answer<Void> answerVoid(VoidAnswer2<A, B> answer) { |
| return toAnswer(answer); |
| } |
| |
| /** |
| * Creates an answer from a functional interface - allows for a strongly typed answer to be created |
| * ideally in Java 8 |
| * @param answer interface to the answer - which is expected to return something |
| * @param <T> return type |
| * @param <A> input parameter type 1 |
| * @param <B> input parameter type 2 |
| * @param <C> input parameter type 3 |
| * @return the answer object to use |
| * @since 2.1.0 |
| */ |
| @Incubating |
| public static <T, A, B, C> Answer<T> answer(Answer3<T, A, B, C> answer) { |
| return toAnswer(answer); |
| } |
| |
| /** |
| * Creates an answer from a functional interface - allows for a strongly typed answer to be created |
| * ideally in Java 8 |
| * @param answer interface to the answer - a void method |
| * @param <A> input parameter type 1 |
| * @param <B> input parameter type 2 |
| * @param <C> input parameter type 3 |
| * @return the answer object to use |
| * @since 2.1.0 |
| */ |
| @Incubating |
| public static <A, B, C> Answer<Void> answerVoid(VoidAnswer3<A, B, C> answer) { |
| return toAnswer(answer); |
| } |
| |
| /** |
| * Creates an answer from a functional interface - allows for a strongly typed answer to be created |
| * ideally in Java 8 |
| * @param answer interface to the answer - which is expected to return something |
| * @param <T> return type |
| * @param <A> input parameter type 1 |
| * @param <B> input parameter type 2 |
| * @param <C> input parameter type 3 |
| * @param <D> input parameter type 4 |
| * @return the answer object to use |
| * @since 2.1.0 |
| */ |
| @Incubating |
| public static <T, A, B, C, D> Answer<T> answer(Answer4<T, A, B, C, D> answer) { |
| return toAnswer(answer); |
| } |
| |
| /** |
| * Creates an answer from a functional interface - allows for a strongly typed answer to be created |
| * ideally in Java 8 |
| * @param answer interface to the answer - a void method |
| * @param <A> input parameter type 1 |
| * @param <B> input parameter type 2 |
| * @param <C> input parameter type 3 |
| * @param <D> input parameter type 4 |
| * @return the answer object to use |
| * @since 2.1.0 |
| */ |
| @Incubating |
| public static <A, B, C, D> Answer<Void> answerVoid(VoidAnswer4<A, B, C, D> answer) { |
| return toAnswer(answer); |
| } |
| |
| /** |
| * Creates an answer from a functional interface - allows for a strongly typed answer to be created |
| * ideally in Java 8 |
| * @param answer interface to the answer - which is expected to return something |
| * @param <T> return type |
| * @param <A> input parameter type 1 |
| * @param <B> input parameter type 2 |
| * @param <C> input parameter type 3 |
| * @param <D> input parameter type 4 |
| * @param <E> input parameter type 5 |
| * @return the answer object to use |
| * @since 2.1.0 |
| */ |
| @Incubating |
| public static <T, A, B, C, D, E> Answer<T> answer(Answer5<T, A, B, C, D, E> answer) { |
| return toAnswer(answer); |
| } |
| |
| /** |
| * Creates an answer from a functional interface - allows for a strongly typed answer to be created |
| * ideally in Java 8 |
| * |
| * @param answer interface to the answer - a void method |
| * @param <A> input parameter type 1 |
| * @param <B> input parameter type 2 |
| * @param <C> input parameter type 3 |
| * @param <D> input parameter type 4 |
| * @param <E> input parameter type 5 |
| * @return the answer object to use |
| * @since 2.1.0 |
| */ |
| @Incubating |
| public static <A, B, C, D, E> Answer<Void> answerVoid(VoidAnswer5<A, B, C, D, E> answer) { |
| return toAnswer(answer); |
| } |
| } |