/* * 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. * *
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}). * *
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. * *
* This additional answer could be used at stub time using the
* then|do|will{@link org.mockito.stubbing.Answer}
methods. For example :
*
*
* given(carKeyFob.authenticate(carKey)).will(returnsFirstArg());
* doAnswer(returnsFirstArg()).when(carKeyFob).authenticate(carKey);
*
*
*
* * This methods works with varargs as well, mockito will expand the vararg to return the argument * at the given position. Suppose the following signature : * *
* interface Person {
* Dream remember(Dream... dreams);
* }
*
* // returns dream1
* given(person.remember(dream1, dream2, dream3, dream4)).will(returnsFirstArg());
*
*
* 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.
*
*
* interface Person {
* Dream[] remember(Dream... otherDreams);
* }
*
* // returns otherDreams (happens to be a 4 elements array)
* given(person.remember(dream1, dream2, dream3, dream4)).will(returnsFirstArg());
*
*
*
* @param
* This additional answer could be used at stub time using the
* then|do|will{@link org.mockito.stubbing.Answer}
methods. For example :
*
*
* given(trader.apply(leesFormula, onCreditDefaultSwap)).will(returnsSecondArg());
* doAnswer(returnsSecondArg()).when(trader).apply(leesFormula, onCreditDefaultSwap);
*
*
*
* * This methods works with varargs as well, mockito will expand the vararg to return the argument * at the given position. Suppose the following signature : * *
* interface Person {
* Dream remember(Dream dream, Dream... otherDreams);
* }
*
* // returns dream2
* given(person.remember(dream1, dream2, dream3, dream4)).will(returnsSecondArg());
*
*
* 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.
*
*
* 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());
*
*
*
* @param
* This additional answer could be used at stub time using the
* then|do|will{@link org.mockito.stubbing.Answer}
methods. For example :
*
*
* given(person.remember(dream1, dream2, dream3, dream4)).will(returnsLastArg());
* doAnswer(returnsLastArg()).when(person).remember(dream1, dream2, dream3, dream4);
*
*
*
* * This methods works with varargs as well, mockito will expand the vararg to return the argument * at the given position. Suppose the following signature : * *
* interface Person {
* Dream remember(Dream dream, Dream... otherDreams);
* }
*
* // returns dream4
* given(person.remember(dream1, dream2, dream3, dream4)).will(returnsLastArg());
*
*
* 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.
*
*
* 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());
*
*
*
* @param
* This additional answer could be used at stub time using the
* then|do|will{@link org.mockito.stubbing.Answer}
methods. For example :
*
*
* given(person.remember(dream1, dream2, dream3, dream4)).will(returnsArgAt(3));
* doAnswer(returnsArgAt(3)).when(person).remember(dream1, dream2, dream3, dream4);
*
*
*
* * This methods works with varargs as well, mockito will expand the vararg to return the argument * at the given position. Suppose the following signature : * *
* interface Person {
* Dream remember(Dream dream, Dream... otherDreams);
* }
*
* // returns dream 3
* given(person.remember(dream1, dream2, dream3, dream4)).will(returnsArgAt(2));
*
*
* 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.
*
*
* 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));
*
*
*
* @param * Useful for spies or partial mocks of objects that are difficult to mock * or spy using the usual spy API. Possible use cases: *
* The difference with the regular spy: *
*
* final class DontYouDareToMockMe implements list { ... }
*
* DontYouDareToMockMe awesomeList = new DontYouDareToMockMe();
*
* List mock = mock(List.class, delegatesTo(awesomeList));
*
*
* * 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: * *
* 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);
*
*
* @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 *
* //this:
* when(mock.foo()).thenReturn(1, 2, 3);
*
* //is equivalent to:
* when(mock.foo()).thenAnswer(new ReturnsElementsOf(Arrays.asList(1, 2, 3)));
*
*
* @param elements The collection of elements to return.
* @return the answer
*
* @since 1.9.5
*/
public static