Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance. Project price only 1 $
You can buy this project and download/modify it how often you want.
/*
* Copyright (c) 2006-2014 Rogério Liesenfeld
* This file is subject to the terms of the MIT license (see LICENSE.txt).
*/
package mockit;
import java.util.*;
import org.jetbrains.annotations.*;
import mockit.internal.expectations.*;
/**
* Used to record strict expectations on {@linkplain Mocked mocked} types and mocked instances.
* It should be noted that strict expectations are rather stringent, and can lead to brittle tests.
* Users should first consider non-strict expectations instead, which can be recorded with the
* {@link NonStrictExpectations} class.
*
* A recorded expectation is intended to match one or more method or constructor invocations, that we expect will occur
* during the execution of some code under test.
* When a match is detected, the recorded {@linkplain #result result} is returned to the caller.
* Alternatively, a recorded exception/error is thrown, or an arbitrary {@linkplain Delegate delegate} method is
* executed.
* Expectations are recorded simply by invoking the desired method or constructor on the mocked type/instance, during
* the initialization of an {@code Expectations} object.
* Typically, this is done by instantiating an anonymous subclass containing an instance initialization body, or as we
* call it, an expectation block:
*
* // Record one or more expectations on available mocked types/instances.
* new Expectations() {{
* mock1.expectedMethod(anyInt); result = 123; times = 2;
* mock2.anotherExpectedMethod(1, "test"); result = new String[] {"Abc", "xyz"};
* }};
*
* // Exercise tested code, with previously recorded expectations now available for replay.
* codeUnderTest.doSomething();
*
* During replay, invocations matching recorded expectations must occur in the exact same number and order as specified
* in the expectation block.
* Invocations that don't match any recorded expectation, on the other hand, will cause an "unexpected invocation" error
* to be thrown.
* Even more, if an expectation was recorded but no matching invocations occurred, a "missing invocation" error will
* be thrown at the end of the test.
*
* There are several special fields and methods which can be used in the expectation block, to: a) record desired return
* values or exceptions/errors to be thrown ({@link #result}, {@link #returns(Object, Object...)}); b) relax or
* constrain the matching of argument values ({@link #anyInt}, {@link #anyString}, {@link #withNotNull()}, etc.);
* c) relax or constrain the expected and/or allowed number of matching invocations ({@link #times}, {@link #minTimes},
* {@link #maxTimes}).
*
* By default, the exact instance on which instance method invocations will occur is not verified to be the
* same as the instance used when recording the expectation.
* That said, instance-specific matching can be obtained by annotating the mock field/parameter as
* {@linkplain Injectable @Injectable}, or by using the {@link #onInstance(Object)} method.
*
* @see #Expectations()
* @see #Expectations(Object...)
* @see #Expectations(Integer, Object...)
* @see Tutorial
*/
public abstract class Expectations extends Invocations
{
@NotNull private final RecordAndReplayExecution execution;
/**
* A value assigned to this field will be taken as the result for the expectation that is being recorded.
*
* If the value is a {@link Throwable} then it will be thrown when a matching invocation later occurs.
* Otherwise, it's assumed to be a return value for a non-void method, and will be returned
* from a matching invocation.
*
* If no result is recorded for a given expectation, then all matching invocations will return the appropriate
* default value according to the method return type:
*
*
{@code String}: returns {@code null}.
*
Primitive or primitive wrapper: the standard default value is returned (ie {@code false} for
* {@code boolean/Boolean}, {@code '\0'} for {@code char/Character}, {@code 0} for {@code int/Integer}, and so on).
*
*
{@code java.util.Collection} or {@code java.util.List}: returns {@link Collections#EMPTY_LIST}
{@code java.util.SortedMap}: returns an unmodifiable empty sorted map.
*
A reference type, except for the collection types above: returns {@code null}.
*
An array type: returns an array with zero elements (empty) in each dimension.
*
* When an expectation is recorded for a method which actually returns an exception or error (as opposed to
* throwing one), then the {@link #returns(Object, Object...)} method should be used instead, as it only
* applies to return values.
*
* Assigning a value whose type differs from the method return type will cause an {@code IllegalArgumentException} to
* be thrown, unless it can be safely converted to the return type.
* One such conversion is from an array to a collection or iterator.
* Another is from an array of at least two dimensions to a map, with the first dimension providing the keys and the
* second the values.
* Yet another conversion is from a single value to a container type holding that value.
*
* Additionally, if the value assigned to the field is an array or is of a type assignable to {@link Iterable} or
* {@link Iterator}, and the return type is single-valued, then the assigned multi-valued result is taken as a
* sequence of consecutive results for the expectation.
*
* Results that depend on some programming logic can be provided through a {@linkplain mockit.Delegate} object
* assigned to the field.
* This applies to {@code void} and non-void methods, as well as to constructors.
*
* Finally, when recording an expectation on a constructor of a mocked class, an arbitrary instance of said
* class can be assigned to the field.
* In this case, the assigned instance will be used as a "replacement" for all invocations to
* instance methods made on other instances, provided they get created sometime later through a
* matching constructor invocation.
*
* In the
* Tutorial
*
* @see #returns(Object, Object...)
*/
protected Object result;
/**
* Registers a sequence of one or more strict expectations recorded on available mocked types and/or mocked
* instances, as written inside the instance initialization body of an anonymous subclass or the called constructor
* of a named subclass.
*
* @see #Expectations(Object...)
* @see #Expectations(Integer, Object...)
*/
protected Expectations()
{
execution = new RecordAndReplayExecution(this, (Object[]) null);
}
/**
* Same as {@link #Expectations()}, except that one or more classes will be partially mocked according to the
* expectations recorded in the expectation block; this feature is known as dynamic partial mocking, in
* contrast with static partial mocking as specified with the {@link Mocked#value} annotation attribute.
*
* The classes to be partially mocked are those directly specified through their {@code Class} objects as well as
* those to which any given objects belong.
* During replay, any invocations to one of these classes or objects will execute real production code, unless a
* matching expectation was recorded.
*
* For a given {@code Class} object, all constructors and methods will be considered for mocking, from the specified
* class up to but not including {@code java.lang.Object}.
*
* For a given object, all methods will be considered for mocking, from the concrete class of the given
* object up to but not including {@code java.lang.Object}.
* The constructors of those classes will not be considered.
* During replay, invocations to instance methods will only match expectations recorded on the given instance
* (or instances, if more than one was given).
*
* @param classesOrObjectsToBePartiallyMocked one or more classes or objects whose classes are to be considered for
* partial mocking
*
* @throws IllegalArgumentException if given a class literal for an interface, an annotation, an array, a
* primitive/wrapper type, or a {@linkplain java.lang.reflect.Proxy#isProxyClass(Class) proxy class} created for an
* interface, or if given a value/instance of such a type
*
* @see #Expectations(Integer, Object...)
* @see Tutorial
*/
protected Expectations(Object... classesOrObjectsToBePartiallyMocked)
{
execution = new RecordAndReplayExecution(this, classesOrObjectsToBePartiallyMocked);
}
/**
* Same as {@link #Expectations(Object...)}, but considering that the invocations inside the block will occur in a
* given number of iterations.
*
* The effect of specifying a number of iterations larger than 1 (one) is equivalent to duplicating (like in "copy &
* paste") the whole sequence of expectations in the block.
*
* It's also valid to have multiple expectation blocks for the same test, each with an arbitrary number of
* iterations.
*
* @param numberOfIterations the positive number of iterations for the whole set of expectations recorded inside the
* block; when not specified, 1 (one) iteration is assumed
* @param classesOrObjectsToBePartiallyMocked one or more classes or objects whose classes are to be considered for
* partial mocking
*
* @see #Expectations()
* @see Tutorial
*/
protected Expectations(Integer numberOfIterations, Object... classesOrObjectsToBePartiallyMocked)
{
this(classesOrObjectsToBePartiallyMocked);
getCurrentPhase().setNumberOfIterations(numberOfIterations);
}
@Override
@NotNull final RecordPhase getCurrentPhase() { return execution.getRecordPhase(); }
/**
* Specifies that the previously recorded method invocation will return a given sequence of values during replay.
*
* Calling this method is equivalent to assigning the {@link #result} field two or more times in sequence, or
* assigning it a single time with an array or iterable containing the same sequence of values.
*
* Certain data conversions will be applied, depending on the return type of the recorded method:
*
*
If the return type is iterable and can receive a {@link List} value, then the given sequence of values will be
* converted into an {@code ArrayList}; this list will then be returned by matching invocations at replay time.
*
If the return type is {@code SortedSet} or a sub-type, then the given sequence of values will be converted
* into a {@code TreeSet}; otherwise, if it is {@code Set} or a sub-type, then a {@code LinkedHashSet} will be
* created to hold the values; the set will then be returned by matching invocations at replay time.
*
If the return type is {@code Iterator} or a sub-type, then the given sequence of values will be converted into
* a {@code List} and the iterator created from this list will be returned by matching invocations at replay
* time.
*
If the return type is an array, then the given sequence of values will be converted to an array of the same
* type, which will be returned by matching invocations at replay time.
*
* The current expectation will have its upper invocation count automatically set to the total number of values
* specified to be returned.
* This upper limit can be overridden through the {@code maxTimes} field, if necessary.
*
* If this method is used for a constructor or {@code void} method, the given return values will be ignored,
* but matching invocations will be allowed during replay; they will simply do nothing.
*
* @param firstValue the first value to be returned at replay time
* @param remainingValues the remaining values to be returned, in the same order
*
* @see Tutorial
*/
protected final void returns(Object firstValue, Object... remainingValues)
{
getCurrentPhase().addSequenceOfReturnValues(firstValue, remainingValues);
}
}
