Expectations (JMockit Toolkit API)

java.lang.Object
- mockit.Expectations

Direct Known Subclasses:

NonStrictExpectations
```
public abstract class Expectations
extends Object
```
A set of expected and/or allowed method/constructor invocations on the mocked types/instances that have been made available to the test through mock fields and/or mock parameters.
```
 new Expectations() {
    @NonStrict MockedClass mock2;

    {
       mock1.expectedMethod(anyInt); result = 123; times = 2;
       mock2.allowedMethod(1, "test"); result = new String[] {"Abc", "xyz"};
    }
 };

 // Now exercise the tested code according to the recorded expectations.
 
```
Typically, this class is used by extending it with anonymous inner classes inside test methods, the so called expectation blocks. Inside such blocks, expectations are recorded on mocked types or mocked instances by calling instance methods on mock fields/parameters, static methods on mocked classes, and/or constructors of mocked classes. Arguments passed in such calls are later matched to the actual arguments passed from the code under test.
Any instance field declared in a subclass is considered a local mock field, provided it has a mockable type and is either non-private or annotated with @Mocked or another mocking annotation.
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 (result, returns(Object, Object...)); b) relax or constrain the matching of argument values (anyInt, anyString, withNotNull(), etc.); c) relax or constrain the expected and/or allowed number of matching invocations (times, minTimes, maxTimes).
Individual expectations are defined during the record phase, and later exercised during the replay phase of the test. At the end of the test, the test runner will automatically assert that all expected invocations actually occurred during the replay phase. An expectation block may also record expectations that are merely allowed to occur, and as such are not implicitly verified at the end of the test.
Additional features and details:
- A mock field can be of any non-primitive type, including interfaces, abstract classes, and concrete classes (even final classes). An instance will be automatically created when the subclass gets instantiated, unless the field is final (in which case, the test code itself will have the responsibility of obtaining an appropriate instance). This mocked instance can then be used inside the expectation block for the recording of expectations on instance methods; static methods and constructors belonging to the mocked class or its super-classes are also mocked, and can also have expectations recorded on them.
- Unless specified otherwise, all expectations defined inside an Expectations immediate subclass will be strict, meaning that the recorded invocations are expected to occur in the same order during the replay phase, and that non-recorded invocations are not allowed. This default behavior can be overridden for a given mocked type by applying the NonStrict annotation to the corresponding mock field/parameter.
- There is a set of API methods that allow the instantiation of non-accessible (to the test) classes, the invocation of non-accessible methods, and the setting of non-accessible fields. Most tests shouldn't need these facilities, though.
- By default, the exact instance on which instance method invocations occur during the replay phase is not verified to be the same as the instance used when recording the corresponding expectation, unless the mock field/parameter was declared to be @Injectable. If such verification on non-injectable instances is needed, the onInstance(Object) method should be used.
- There are additional constructors which provide other features: dynamic partial mocking, and iterated invocations.
In the Tutorial
See Also:
Expectations()

Field Summary

Fields
Modifier and Type	Field and Description
`protected static CharSequence`	`$` A value assigned to this field will be used as a prefix for the error message to be reported if and when the current expectation is violated.
`protected static Object`	`any` Matches any `Object` reference passed as value for the parameter.
`protected static Boolean`	`anyBoolean` Matches any `boolean` or `Boolean` value for the relevant parameter.
`protected static Byte`	`anyByte` Matches any `byte` or `Byte` value for the relevant parameter.
`protected static Character`	`anyChar` Matches any `char` or `Character` value for the relevant parameter.
`protected static Double`	`anyDouble` Matches any `double` or `Double` value for the relevant parameter.
`protected static Float`	`anyFloat` Matches any `float` or `Float` value for the relevant parameter.
`protected static Integer`	`anyInt` Matches any `int` or `Integer` value for the relevant parameter.
`protected static Long`	`anyLong` Matches any `long` or `Long` value for the relevant parameter.
`protected static Short`	`anyShort` Matches any `short` or `Short` value for the relevant parameter.
`protected static String`	`anyString` Matches any `String` value for the relevant parameter.
`protected static Object`	`forEachInvocation` An object assigned to this field will be called back for each invocation matching the current expectation, in order to validate invocation arguments.
`protected static int`	`maxTimes` A non-negative value assigned to this field will be taken as the maximum number of times that invocations matching the current expectation should occur during replay.
`protected static int`	`minTimes` A non-negative value assigned to this field will be taken as the minimum number of times that invocations matching the current expectation should occur during replay.
`protected static Object`	`result` A value assigned to this field will be taken as the result for the current expectation.
`protected static int`	`times` A non-negative value assigned to this field will be taken as the exact number of times that invocations matching the current expectation should occur during replay.

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`Expectations()` Initializes this set of expectations, entering the record phase.
`protected`	`Expectations(Integer numberOfIterations, Object... classesOrObjectsToBePartiallyMocked)` Identical to `Expectations(Object...)`, but considering that the invocations inside the block will occur in a given number of iterations.
`protected`	`Expectations(Object... classesOrObjectsToBePartiallyMocked)` Same as `Expectations()`, except that one or more classes will be partially mocked according to the expectations recorded in the expectation block.

Method Summary

Methods
Modifier and Type	Method and Description
`protected <T> T`	`getField(Class<?> fieldOwner, Class<T> fieldType)` Gets the value of a non-accessible static field defined in a given class.
`protected <T> T`	`getField(Class<?> fieldOwner, String fieldName)` Gets the value of a non-accessible static field defined in a given class.
`protected <T> T`	`getField(Object fieldOwner, Class<T> fieldType)` Gets the value of a non-accessible field from a given object, assuming there is only one field declared in the class of the given object whose type can receive values of the specified field type.
`protected <T> T`	`getField(Object fieldOwner, String fieldName)` Gets the value of a non-accessible field from a given object.
`protected <T> T`	`invoke(Class<?> methodOwner, String methodName, Class<?>[] parameterTypes, Object... methodArgs)` Specifies an expectation for a mocked `static` method having the given name and parameter types, with a given list of arguments.
`protected <T> T`	`invoke(Class<?> methodOwner, String methodName, Object... methodArgs)` Specifies an expectation for a mocked `static` method, with a given list of arguments.
`protected <T> T`	`invoke(Object objectWithMethod, String methodName, Class<?>[] parameterTypes, Object... methodArgs)` Specifies an expectation on a mocked instance method having the given name and parameter types, with the given argument values.
`protected <T> T`	`invoke(Object objectWithMethod, String methodName, Object... methodArgs)` Specifies an expectation for a mocked instance method, with a given list of arguments.
`protected <T> T`	`newInnerInstance(String innerClassSimpleName, Object outerClassInstance, Object... nonNullInitArgs)` The same as `newInstance(String, Class[], Object...)`, but for instantiating an inner non-accessible class of some other class, and where all other (if any) initialization arguments are known to be non null.
`protected <T> T`	`newInstance(String className, Class<?>[] parameterTypes, Object... initArgs)` Specifies an expectation for a mocked constructor of a given class.
`protected <T> T`	`newInstance(String className, Object... nonNullInitArgs)` The same as `newInstance(String, Class[], Object...)`, but inferring parameter types from non-null argument values.
`protected void`	`notStrict()` Deprecated. This method will be removed in a future release. Instead of using it, convert strict mocked types to non-strict ones by using the `NonStrict` annotation or the `NonStrictExpectations` subclass; on previous strict recorded expectations, apply the `times`/`minTimes`/`maxTimes` fields as needed, or re-write them in suitable verification blocks.
`protected <T> T`	`onInstance(T mockedInstance)` Specify that the next invocation on the given mocked instance must match a corresponding invocation on the same instance in the replay phase.
`protected void`	`returns(Object value)` Specifies that the previously recorded method invocation will return a given value during replay.
`protected void`	`returns(Object firstValue, Object... remainingValues)` Specifies that the previously recorded method invocation will return a given sequence of values during replay.
`protected void`	`setField(Class<?> fieldOwner, Object fieldValue)` Same as `setField(Class, String, Object)`, except that the field is looked up by the type of the given field value instead of by name.
`protected void`	`setField(Class<?> fieldOwner, String fieldName, Object fieldValue)` Sets the value of a non-accessible static field on a given class.
`protected void`	`setField(Object fieldOwner, Object fieldValue)` Same as `setField(Object, String, Object)`, except that the field is looked up by the type of the given field value instead of by name.
`protected void`	`setField(Object fieldOwner, String fieldName, Object fieldValue)` Sets the value of a non-accessible field on a given object.
`protected <T> T`	`with(Delegate<T> delegateObjectWithInvocationHandlerMethod)` Adds a custom argument matcher for a parameter in the current expectation.
`protected <T> T`	`with(Object argumentMatcher)` Adds a custom argument matcher for a parameter in the current expectation.
`protected <T> T`	`with(T argValue, Object argumentMatcher)` Adds a custom argument matcher for a parameter in the current expectation.
`protected <T> T`	`withAny(T arg)` Same as `withEqual(Object)`, but matching any argument value of the appropriate type.
`protected <T> T`	`withCapture(List<T> valueHolderForMultipleInvocations)` Captures the argument value passed into the associated expectation parameter, for each invocation that matches the expectation when the tested code is exercised.
`protected double`	`withEqual(double value, double delta)` Same as `withEqual(Object)`, but checking that a numeric invocation argument in the replay phase is sufficiently close to the given value.
`protected float`	`withEqual(float value, double delta)` Same as `withEqual(Object)`, but checking that a numeric invocation argument in the replay phase is sufficiently close to the given value.
`protected <T> T`	`withEqual(T arg)` When passed as argument for an expectation, creates a new matcher that will check if the given value is `equal` to the corresponding argument received by a matching invocation.
`protected <T> T`	`withInstanceLike(T object)` Same as `withEqual(Object)`, but checking that an invocation argument in the replay phase is an instance of the same class as the given object.
`protected <T> T`	`withInstanceOf(Class<T> argClass)` Same as `withEqual(Object)`, but checking that an invocation argument in the replay phase is an instance of the given class.
`protected <T extends CharSequence> T`	`withMatch(T regex)` Same as `withEqual(Object)`, but checking that a textual invocation argument in the replay phase matches the given `regular expression`.
`protected <T> T`	`withNotEqual(T arg)` Same as `withEqual(Object)`, but checking that the invocation argument in the replay phase is different from the given value.
`protected <T> T`	`withNotNull()` Same as `withEqual(Object)`, but checking that an invocation argument in the replay phase is not `null`.
`protected <T> T`	`withNull()` Same as `withEqual(Object)`, but checking that an invocation argument in the replay phase is `null`.
`protected <T extends CharSequence> T`	`withPrefix(T text)` Same as `withEqual(Object)`, but checking that a textual invocation argument in the replay phase starts with the given text.
`protected <T> T`	`withSameInstance(T object)` Same as `withEqual(Object)`, but checking that an invocation argument in the replay phase is the exact same instance as the one in the recorded/verified invocation.
`protected <T extends CharSequence> T`	`withSubstring(T text)` Same as `withEqual(Object)`, but checking that a textual invocation argument in the replay phase contains the given text as a substring.
`protected <T extends CharSequence> T`	`withSuffix(T text)` Same as `withEqual(Object)`, but checking that a textual invocation argument in the replay phase ends with the given text.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - result
```
protected static Object result
```
    A value assigned to this field will be taken as the result for the current expectation.
    If the value is a 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 the recorded expectation is for a method which actually returns an exception or error (as opposed to throwing one), then the returns(Object) method should be used instead, as it only applies to return values.
    Attempting to return a value whose type differs from the method return type will cause a ClassCastException to be thrown at replay time, 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 Iterable or 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. Another way to specify consecutive results is to simply write multiple consecutive assignments to the field, for the same expectation.
    Custom results can be provided through a Delegate object assigned to the field. This applies to void and non-void methods, as well as for 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 Also:
    returns(Object), returns(Object, Object...)
  - any
```
protected static final Object any
```
    Matches any Object reference passed as value for the parameter.
    The use of this field will usually require a cast to the specific parameter type. However, if there is any other parameter for which an argument matching constraint is specified, passing the null reference instead will have the same effect.
    When the parameter to be matched is a varargs parameter of element type V, the use of any should be cast to V[].
    In invocations to non-accessible methods or constructors (for example, with invoke(Object, String, Object...)), use withAny(T) instead.
    
    See Also:
    anyInt
  - anyString
```
protected static final String anyString
```
    Matches any String value for the relevant parameter.
    
    See Also:
    anyInt
  - anyLong
```
protected static final Long anyLong
```
    Matches any long or Long value for the relevant parameter.
    
    See Also:
    anyInt
  - anyInt
```
protected static final Integer anyInt
```
    Matches any int or Integer value for the relevant parameter.
    When used as argument for a method/constructor invocation in the recording or verification phase of a test, specifies the matching of any value passed as argument to corresponding invocations in the replay phase.
    In the Tutorial
  - anyShort
```
protected static final Short anyShort
```
    Matches any short or Short value for the relevant parameter.
    
    See Also:
    anyInt
  - anyByte
```
protected static final Byte anyByte
```
    Matches any byte or Byte value for the relevant parameter.
    
    See Also:
    anyInt
  - anyBoolean
```
protected static final Boolean anyBoolean
```
    Matches any boolean or Boolean value for the relevant parameter.
    
    See Also:
    anyInt
  - anyChar
```
protected static final Character anyChar
```
    Matches any char or Character value for the relevant parameter.
    
    See Also:
    anyInt
  - anyDouble
```
protected static final Double anyDouble
```
    Matches any double or Double value for the relevant parameter.
    
    See Also:
    anyInt
  - anyFloat
```
protected static final Float anyFloat
```
    Matches any float or Float value for the relevant parameter.
    
    See Also:
    anyInt
  - forEachInvocation
```
protected static Object forEachInvocation
```
    An object assigned to this field will be called back for each invocation matching the current expectation, in order to validate invocation arguments.
    Said object can be of any type, provided its class has a single non-private method (additional methods are allowed and ignored, as long as they are private). This validation method can have any name, and should either have no parameters or a list of parameters that match the ones defined in the mocked method/constructor associated with the expectation. Corresponding parameters don't need to have the exact same declared type, though, as long as each possible invocation argument can be passed to the corresponding parameter in the validation method.
    The return type of the validation method should be either boolean or void. In the first case, a return value of true means the invocation is valid, while false causes the test to fail with an appropriate error message. In the second case, invocation arguments should be validated through regular JUnit/TestNG assertion methods.
    The validation method can optionally declare its first parameter as being of type Invocation.
    In the Tutorial
  - times
```
protected static int times
```
    A non-negative value assigned to this field will be taken as the exact number of times that invocations matching the current expectation should occur during replay.
    In the Tutorial
    
    See Also:
    minTimes, maxTimes
  - minTimes
```
protected static int minTimes
```
    A non-negative value assigned to this field will be taken as the minimum number of times that invocations matching the current expectation should occur during replay. Zero or a negative value implies there is no lower limit. The maximum number of times is automatically adjusted to allow any number of invocations.
    Both minTimes and maxTimes can be specified for the same expectation, as long as minTimes is assigned first.
    
    See Also:
    times, maxTimes
  - maxTimes
```
protected static int maxTimes
```
    A non-negative value assigned to this field will be taken as the maximum number of times that invocations matching the current expectation should occur during replay. A negative value implies there is no upper limit.
    Both minTimes and maxTimes can be specified for the same expectation, as long as minTimes is assigned first.
    
    See Also:
    times, minTimes
  - $
```
protected static CharSequence $
```
    A value assigned to this field will be used as a prefix for the error message to be reported if and when the current expectation is violated.
    Inside an expectation/verification block, the assignment must follow the invocation which records/verifies the expectation; if there is no current expectation at the point the assignment appears, an IllegalStateException is thrown.
    Notice there are only two different ways in which an expectation can be violated: either an unexpected invocation occurs, or a missing invocation is detected.
- Constructor Detail
  - Expectations
```
protected Expectations()
```
    Initializes this set of expectations, entering the record phase.
    For each associated mocked type, the following tasks are performed:
    1. Redefines the target class for mocking derived from the mocked type.
    2. If the declared type to be mocked is an abstract class, then generates a concrete subclass with empty implementations for all inherited abstract methods.
    3. If the mocked type is the declared type of a non-final instance field, then creates and assigns a new (mocked) instance to that field.
    After this, test code can start recording invocations on the mocked types and/or mocked instances. Each and every such call made from inside the expectation block is recorded.
    See Also:
    Expectations(Object...), Expectations(Integer, Object...)
  - Expectations
```
protected Expectations(Object... classesOrObjectsToBePartiallyMocked)
```
    Same as Expectations(), except that one or more classes will be partially mocked according to the expectations recorded in the expectation block. Such classes are those directly specified as well as those to which any given instances belong.
    During the replay phase, any invocations to one of these classes or instances will execute real production code, unless a matching invocation was recorded as an expectation inside the block.
    For a given Class object, all constructors and methods will be considered for mocking, from the specified class up to but not including 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 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).
    In the Tutorial
    
    Parameters:
    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 proxy class created for an interface, or if given a value/instance of such a type
    See Also:
    Expectations(), Expectations(Integer, Object...)
  - Expectations
```
protected Expectations(Integer numberOfIterations,
            Object... classesOrObjectsToBePartiallyMocked)
```
    Identical to 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 strict invocations in the block. For any non-strict invocation inside the same block, the effect will be equivalent to multiplying the minimum and maximum invocation count by the specified number of iterations.
    It's also valid to have multiple expectation blocks for the same test, each with an arbitrary number of iterations, and containing any mix of strict and non-strict expectations.
    In the Tutorial
    
    Parameters:
    numberOfIterations - the positive number of iterations for the whole set of invocations recorded inside the block; when not specified, 1 (one) iteration is assumed
    See Also:
    Expectations(), Expectations(Object...)
- Method Detail
  - returns
```
protected final void returns(Object value)
```
    Specifies that the previously recorded method invocation will return a given value during replay.
    More than one return value can be specified for the same invocation by simply calling this method multiple times, with the desired consecutive values to be later returned. For an strict expectation, the maximum number of expected invocations is automatically adjusted so that one invocation for each return value is allowed; if a larger number of invocations is explicitly allowed then the last recorded return value is used for all remaining invocations during the replay phase.
    It's also possible to specify a sequence of values to be returned by consecutive invocations, by simply passing an array, a collection, an iterable, or an iterator. The return type of the recorded method, however, must not be of one of these non-singular types. If it is, the multi-valued argument will be returned by a single invocation at replay time.
    If this method is used for a constructor or void method, the given return value will be ignored, but a matching invocation will be allowed during replay; it will simply do nothing.
    For a non-void method, if no return value is recorded then all invocations to it will return the appropriate default value according to the method return type:
    - Primitive: the standard default value is returned (ie false for boolean, '\0' for char, 0 for int, and so on).
    - java.util.Collection or java.util.List: returns Collections.EMPTY_LIST
    - java.util.Set: returns Collections.EMPTY_SET.
    - java.util.SortedSet: returns an unmodifiable empty sorted set.
    - java.util.Map: returns Collections.EMPTY_MAP.
    - java.util.SortedMap: returns an unmodifiable empty sorted map.
    - A reference type (including String and wrapper types for primitives, and excluding the exact collection types above): returns null.
    - An array type: an array with zero elements (empty) in each dimension is returned.
    Finally, value(s) to be returned can also be determined at replay time through a Delegate instance passed as argument to this method (typically created as an anonymous class).
    Parameters:
    value - the value to be returned when the method is replayed; must be compatible with the method's return type
    
    Throws:
    
    IllegalStateException - if not currently recording an invocation
    See Also:
    result, returns(Object, Object...)
  - returns
```
protected final void returns(Object firstValue,
           Object... remainingValues)
```
    Specifies that the previously recorded method invocation will return a given sequence of values during replay.
    Using this method is equivalent to calling returns(Object) two or more times in sequence, except when the recorded method can return an iterable (including any Collection subtype), an iterator, or an array:
    1. If the return type is iterable and can receive a List value, then the given sequence of values will be converted into an ArrayList; this list will then be returned by matching invocations at replay time.
    2. If the return type is SortedSet or a sub-type, then the given sequence of values will be converted into a TreeSet; otherwise, if it is Set or a sub-type, then a LinkedHashSet will be created to hold the values; the set will then be returned by matching invocations at replay time.
    3. If the return type is Iterator or a sub-type, then the given sequence of values will be converted into a List and the iterator created from this list will be returned by matching invocations at replay time.
    4. 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 maxTimes field, if necessary.
    If this method is used for a constructor or void method, the given return values will be ignored, but matching invocations will be allowed during replay; they will simply do nothing.
    Parameters:
    firstValue - the first value to be returned in the replay phase
    remainingValues - the remaining values to be returned, in the same order
    
    Throws:
    
    IllegalStateException - if not currently recording an invocation
  - notStrict
```
@Deprecated
protected final void notStrict()
```
    Deprecated. This method will be removed in a future release. Instead of using it, convert strict mocked types to non-strict ones by using the NonStrict annotation or the NonStrictExpectations subclass; on previous strict recorded expectations, apply the times/minTimes/maxTimes fields as needed, or re-write them in suitable verification blocks.
    
    Marks the preceding invocation as belonging to a non-strict expectation. Note that all invocations on NonStrict mocked types/instances will be automatically considered non-strict. The same is true for all invocations inside a NonStrictExpectations block.
    For a non-strict expectation, any number (including zero) of invocations with matching arguments can occur while in the replay phase, in any order, and they will all produce the same result (usually, the specified return value). Two or more non-strict expectations can be recorded for the same method or constructor, as long as the arguments differ. Argument matchers can be used as well.
    Expected invocation counts can also be specified for a non-strict expectation (with one of the "times" fields).
  - onInstance
```
protected final <T> T onInstance(T mockedInstance)
```
    Specify that the next invocation on the given mocked instance must match a corresponding invocation on the same instance in the replay phase.
    By default, such instances can be different between the replay phase and the record or verify phase, even though the method or constructor invoked is the same, and the invocation arguments all match. The use of this method allows invocations to also be matched on the instance invoked.
    Typically, tests that need to match instance invocations on the mocked instances invoked will declare two or more mock fields and/or parameters of the exact same mocked type. These instances will then be passed to the code under test, which will invoke them during the replay phase. To avoid the need to explicitly call onInstance(Object) on each of these different instances of the same type, instance matching is implied (and automatically applied to all relevant invocations) whenever two or more mocked instances of the same type are in scope for a given test method. This property of the API makes the use of onInstance much less frequent than it might otherwise be.
    In most cases, an invocation to the given mocked instance will be made on the value returned by this method (ie, a chained invocation). However, in the situation where the tested method calls an instance method defined in a mocked super-class (possibly an overridden method called through the super keyword), it will be necessary to match on a different instance than the one used for recording invocations. To do so, this method should be given the desired instance to match, while the invocation to be recorded should be done on the available mocked instance, which must be a different one (otherwise a non-mocked method would get executed). This is valid only if the instance to be matched is assignable to the mocked type, and typically occurs when partially mocking a class hierarchy.
    In the Tutorial
    
    Returns:
    the given mocked instance, allowing the invocation to be recorded/verified to immediately follow the call to this method
  - with
```
protected final <T> T with(T argValue,
         Object argumentMatcher)
```
    Adds a custom argument matcher for a parameter in the current expectation.
    The given matcher can be any existing Hamcrest matcher or a user provided one.
    Alternatively, it can be an instance of an invocation handler class, similar to those used with the forEachInvocation field. In this case, the non-private handler method must have a single parameter of a type capable of receiving the relevant argument values. The name of this handler method does not matter. Its return type, on the other hand, should either be boolean or void. In the first case, a return value of true will indicate a successful match for the actual invocation argument at replay time, while a return of false will cause the test to fail. In the case of a void return type, instead of returning a value the handler method should validate the actual invocation argument through a JUnit/TestNG assertion.
    For additional details, refer to withEqual(Object).
    
    Parameters:
    argValue - an arbitrary value of the proper type, necessary to provide a valid argument to the invocation parameter
    argumentMatcher - an instance of a class implementing the org.hamcrest.Matcher interface, or an instance of an invocation handler class containing an appropriate invocation handler method
    
    Returns:
    the given argValue
    See Also:
    with(Object), with(Delegate)
  - with
```
protected final <T> T with(Object argumentMatcher)
```
    Adds a custom argument matcher for a parameter in the current expectation. This works just like with(Object, Object), but attempting to discover the argument type from the supplied Hamcrest argument matcher, when applicable.
    
    Parameters:
    argumentMatcher - an instance of a class implementing the org.hamcrest.Matcher interface, or an instance of an invocation handler class containing an appropriate invocation handler method
    
    Returns:
    the value recorded inside the given Hamcrest argument matcher, or null if there is no such value to be found
    See Also:
    with(Object, Object), with(Delegate)
  - with
```
protected final <T> T with(Delegate<T> delegateObjectWithInvocationHandlerMethod)
```
    Adds a custom argument matcher for a parameter in the current expectation.
    The given delegate object is assumed to be an instance of an invocation handler class, similar to those used with the forEachInvocation field. The non-private handler method must have a single parameter capable of receiving the relevant argument values. The name of this handler method does not matter.
    The handler's return type, on the other hand, should be boolean or void. In the first case, a return value of true will indicate a successful match for the actual invocation argument at replay time, while a return of false will fail to match the invocation. In the case of a void return type, the handler method should validate the actual invocation argument through a JUnit/TestNG assertion.
    
    Parameters:
    delegateObjectWithInvocationHandlerMethod - an instance of a class with an appropriate invocation handler method
    
    Returns:
    the default primitive value corresponding to T if it's a primitive wrapper type, or null otherwise
    See Also:
    with(Object), with(Object, Object)
  - withAny
```
protected final <T> T withAny(T arg)
```
    Same as withEqual(Object), but matching any argument value of the appropriate type.
    Consider using instead the "anyXyz" field appropriate to the parameter type: anyBoolean, anyByte, anyChar, anyDouble, anyFloat, anyInt, anyLong, anyShort, anyString, or any for other reference types.
    Note: when using invoke(Object, String, Object...), etc., it's valid to pass withAny(ParameterType.class) if an actual instance of the parameter type cannot be created.
    
    Parameters:
    arg - an arbitrary value which will match any argument value in the replay phase
    
    Returns:
    the input argument
  - withCapture
```
protected final <T> T withCapture(List<T> valueHolderForMultipleInvocations)
```
    Captures the argument value passed into the associated expectation parameter, for each invocation that matches the expectation when the tested code is exercised. As each such value is captured, it gets added to the given list so that it can be inspected later.
    
    Parameters:
    valueHolderForMultipleInvocations - list into which the arguments received by matching invocations will be added
    
    Returns:
    the default value for type T
    See Also:
    Verifications.withCapture()
  - withEqual
```
protected final <T> T withEqual(T arg)
```
    When passed as argument for an expectation, creates a new matcher that will check if the given value is equal to the corresponding argument received by a matching invocation.
    The matcher is added to the end of the list of argument matchers for the invocation being recorded/verified. It cannot be reused for a different parameter.
    Usually, this particular method should not be used. Instead, simply pass the desired argument value directly, without any matcher. Only when specifying values for a varargs method it's useful, and even then only when some other argument matcher is also used.
    In the Tutorial
    
    Parameters:
    arg - the expected argument value
    
    Returns:
    the given argument
  - withEqual
```
protected final double withEqual(double value,
               double delta)
```
    Same as withEqual(Object), but checking that a numeric invocation argument in the replay phase is sufficiently close to the given value.
    
    Parameters:
    value - the center value for range comparison
    delta - the tolerance around the center value, for a range of [value - delta, value + delta]
    
    Returns:
    the given value
  - withEqual
```
protected final float withEqual(float value,
              double delta)
```
    Same as withEqual(Object), but checking that a numeric invocation argument in the replay phase is sufficiently close to the given value.
    
    Parameters:
    value - the center value for range comparison
    delta - the tolerance around the center value, for a range of [value - delta, value + delta]
    
    Returns:
    the given value
  - withInstanceLike
```
protected final <T> T withInstanceLike(T object)
```
    Same as withEqual(Object), but checking that an invocation argument in the replay phase is an instance of the same class as the given object.
    Equivalent to a withInstanceOf(object.getClass()) call, except that it returns object instead of null.
    
    Parameters:
    object - an instance of the desired class
    
    Returns:
    the given instance
  - withInstanceOf
```
protected final <T> T withInstanceOf(Class<T> argClass)
```
    Same as withEqual(Object), but checking that an invocation argument in the replay phase is an instance of the given class.
    
    Parameters:
    argClass - the desired class
    
    Returns:
    always null; if you need a specific return value, use withInstanceLike(Object)
  - withNotEqual
```
protected final <T> T withNotEqual(T arg)
```
    Same as withEqual(Object), but checking that the invocation argument in the replay phase is different from the given value.
    
    Parameters:
    arg - an arbitrary value, but different from the ones expected to occur during replay
    
    Returns:
    the given argument value
  - withNull
```
protected final <T> T withNull()
```
    Same as withEqual(Object), but checking that an invocation argument in the replay phase is null.
    
    Returns:
    always null
  - withNotNull
```
protected final <T> T withNotNull()
```
    Same as withEqual(Object), but checking that an invocation argument in the replay phase is not null.
    
    Returns:
    always null
  - withSameInstance
```
protected final <T> T withSameInstance(T object)
```
    Same as withEqual(Object), but checking that an invocation argument in the replay phase is the exact same instance as the one in the recorded/verified invocation.
    
    Parameters:
    object - the desired instance
    
    Returns:
    the given object
  - withSubstring
```
protected final <T extends CharSequence> T withSubstring(T text)
```
    Same as withEqual(Object), but checking that a textual invocation argument in the replay phase contains the given text as a substring.
    
    Parameters:
    text - an arbitrary non-null textual value
    
    Returns:
    the given text
  - withPrefix
```
protected final <T extends CharSequence> T withPrefix(T text)
```
    Same as withEqual(Object), but checking that a textual invocation argument in the replay phase starts with the given text.
    
    Parameters:
    text - an arbitrary non-null textual value
    
    Returns:
    the given text
  - withSuffix
```
protected final <T extends CharSequence> T withSuffix(T text)
```
    Same as withEqual(Object), but checking that a textual invocation argument in the replay phase ends with the given text.
    
    Parameters:
    text - an arbitrary non-null textual value
    
    Returns:
    the given text
  - withMatch
```
protected final <T extends CharSequence> T withMatch(T regex)
```
    Same as withEqual(Object), but checking that a textual invocation argument in the replay phase matches the given regular expression.
    Note that this can be used for any string comparison, including case insensitive ones (with "(?i)" in the regex).
    
    Parameters:
    regex - an arbitrary (non-null) regular expression against which textual argument values will be matched
    
    Returns:
    the given regex
    See Also:
    Pattern.compile(String, int)
  - newInstance
```
protected final <T> T newInstance(String className,
                Class<?>[] parameterTypes,
                Object... initArgs)
```
    Specifies an expectation for a mocked constructor of a given class.
    This is only meant for constructors that are not accessible from the test (private constructors, usually), and therefore cannot be invoked normally.
    Note that, in general, it's not recommended to mock and/or invoke private constructors from a test, since such constructors are merely implementation details of the tested code, and as such should not appear in test code.
    In the Tutorial
    
    Type Parameters:
    T - interface or super-class type to which the returned instance should be assignable
    Parameters:
    className - the fully qualified name of the desired class
    parameterTypes - the formal parameter types for the desired constructor
    initArgs - the invocation arguments for the constructor, which must be consistent with the specified parameter types
    
    Returns:
    a newly created instance of the specified class, initialized with the specified constructor and arguments
    See Also:
    newInstance(String, Object...), newInnerInstance(String, Object, Object...)
  - newInstance
```
protected final <T> T newInstance(String className,
                Object... nonNullInitArgs)
```
    The same as newInstance(String, Class[], Object...), but inferring parameter types from non-null argument values. If a given parameter needs to match null during replay, then the corresponding Class literal must be passed instead of null.
    
    Parameters:
    nonNullInitArgs - zero or more non-null expected parameter values for the expectation; if a null value needs to be passed, the Class object for the parameter type must be passed instead
    
    Throws:
    
    IllegalArgumentException - if one of the given arguments is null
    See Also:
    newInnerInstance(String, Object, Object...)
  - newInnerInstance
```
protected final <T> T newInnerInstance(String innerClassSimpleName,
                     Object outerClassInstance,
                     Object... nonNullInitArgs)
```
    The same as newInstance(String, Class[], Object...), but for instantiating an inner non-accessible class of some other class, and where all other (if any) initialization arguments are known to be non null.
    
    Parameters:
    innerClassSimpleName - simple name of the inner class, that is, the part after the "$" character in its full name
    outerClassInstance - the outer class instance to which the inner class instance will belong
    nonNullInitArgs - zero or more non-null expected parameter values for the expectation; if a null value needs to be passed, the Class object for the parameter type must be passed instead
  - invoke
```
protected final <T> T invoke(Object objectWithMethod,
           String methodName,
           Class<?>[] parameterTypes,
           Object... methodArgs)
```
    Specifies an expectation on a mocked instance method having the given name and parameter types, with the given argument values.
    This is only meant for methods that are not accessible from the test (private methods, usually), and therefore cannot be called normally.
    Note that, in general, it's not recommended to mock and/or call private methods from a test, since such methods are merely implementation details of the tested code, and as such should not appear in test code.
    In the Tutorial
    
    Parameters:
    objectWithMethod - the instance on which the invocation is to be done; must not be null
    methodName - the name of the expected method
    parameterTypes - the formal parameter types for the desired method
    methodArgs - zero or more expected parameter values for the expectation
    
    Returns:
    the return value from the invoked method, wrapped if primitive
    See Also:
    invoke(Object, String, Object...), invoke(Class, String, Class[], Object...)
  - invoke
```
protected final <T> T invoke(Object objectWithMethod,
           String methodName,
           Object... methodArgs)
```
    Specifies an expectation for a mocked instance method, with a given list of arguments.
    This is only meant for methods that are not accessible from the test (private methods, usually), and therefore cannot be called normally.
    Note that, in general, it's not recommended to mock and/or call private methods from a test, since such methods are merely implementation details of the tested code, and as such should not appear in test code.
    In the Tutorial
    
    Parameters:
    objectWithMethod - the instance on which the invocation is to be done; must not be null
    methodName - the name of the expected method
    methodArgs - zero or more non-null expected parameter values for the expectation; if a null value needs to be passed, the Class object for the parameter type must be passed instead
    
    Returns:
    the return value from the invoked method, wrapped if primitive
    
    Throws:
    
    IllegalArgumentException - if a null reference was provided for a parameter
    See Also:
    invoke(Class, String, Object...), invoke(Object, String, Class[], Object...)
  - invoke
```
protected final <T> T invoke(Class<?> methodOwner,
           String methodName,
           Class<?>[] parameterTypes,
           Object... methodArgs)
```
    Specifies an expectation for a mocked static method having the given name and parameter types, with a given list of arguments.
    This is only meant for methods that are not accessible from the test (private methods, usually), and therefore cannot be called normally.
    Note that, in general, it's not recommended to mock and/or call private methods from a test, since such methods are merely implementation details of the tested code, and as such should not appear in test code.
    
    Parameters:
    methodOwner - the class on which the invocation is to be done; must not be null
    methodName - the name of the expected static method
    parameterTypes - the formal parameter types for the desired method
    methodArgs - zero or more expected parameter values for the expectation
    
    Returns:
    the return value from the invoked method, wrapped if primitive
    See Also:
    invoke(Class, String, Object...), invoke(Object, String, Class[], Object...)
  - invoke
```
protected final <T> T invoke(Class<?> methodOwner,
           String methodName,
           Object... methodArgs)
```
    Specifies an expectation for a mocked static method, with a given list of arguments.
    This is only meant for methods that are not accessible from the test (private methods, usually), and therefore cannot be called normally.
    Note that, in general, it's not recommended to mock and/or call private methods from a test, since such methods are merely implementation details of the tested code, and as such should not appear in test code.
    
    Parameters:
    methodOwner - the class on which the invocation is to be done; must not be null
    methodName - the name of the expected static method
    methodArgs - zero or more non-null expected parameter values for the expectation; if a null value needs to be passed, the Class object for the parameter type must be passed instead
    
    Returns:
    the return value from the invoked method, wrapped if primitive
    
    Throws:
    
    IllegalArgumentException - if a null reference was provided for a parameter
    See Also:
    invoke(Class, String, Class[], Object...), invoke(Object, String, Object...)
  - getField
```
protected final <T> T getField(Object fieldOwner,
             String fieldName)
```
    Gets the value of a non-accessible field from a given object.
    In the Tutorial
    
    Parameters:
    fieldOwner - the instance from which to get the field value
    fieldName - the name of the field to get
    See Also:
    setField(Object, String, Object)
  - getField
```
protected final <T> T getField(Object fieldOwner,
             Class<T> fieldType)
```
    Gets the value of a non-accessible field from a given object, assuming there is only one field declared in the class of the given object whose type can receive values of the specified field type.
    
    Parameters:
    fieldOwner - the instance from which to get the field value
    fieldType - the declared type of the field, or a sub-type of the declared field type
    
    Throws:
    
    IllegalArgumentException - if either the desired field is not found, or more than one is
    See Also:
    getField(Object, String)
  - getField
```
protected final <T> T getField(Class<?> fieldOwner,
             String fieldName)
```
    Gets the value of a non-accessible static field defined in a given class.
    
    Parameters:
    fieldOwner - the class from which to get the field value
    fieldName - the name of the static field to get
    See Also:
    setField(Class, String, Object)
  - getField
```
protected final <T> T getField(Class<?> fieldOwner,
             Class<T> fieldType)
```
    Gets the value of a non-accessible static field defined in a given class.
    
    Parameters:
    fieldOwner - the class from which to get the field value
    fieldType - the declared type of the field, or a sub-type of the declared field type
    See Also:
    setField(Class, String, Object)
  - setField
```
protected final void setField(Object fieldOwner,
            String fieldName,
            Object fieldValue)
```
    Sets the value of a non-accessible field on a given object.
    In the Tutorial
    
    Parameters:
    fieldOwner - the instance on which to set the field value
    fieldName - the name of the field to set
    fieldValue - the value to set the field to
    See Also:
    setField(Class, String, Object)
  - setField
```
protected final void setField(Object fieldOwner,
            Object fieldValue)
```
    Same as setField(Object, String, Object), except that the field is looked up by the type of the given field value instead of by name.
    
    Throws:
    
    IllegalArgumentException - if no field or more than one is found in the target class to which the given value can be assigned
  - setField
```
protected final void setField(Class<?> fieldOwner,
            String fieldName,
            Object fieldValue)
```
    Sets the value of a non-accessible static field on a given class.
    
    Parameters:
    fieldOwner - the class on which the static field is defined
    fieldName - the name of the field to set
    fieldValue - the value to set the field to
  - setField
```
protected final void setField(Class<?> fieldOwner,
            Object fieldValue)
```
    Same as setField(Class, String, Object), except that the field is looked up by the type of the given field value instead of by name.
    
    Parameters:
    fieldOwner - the class on which the static field is defined
    fieldValue - the value to set the field to

Class Expectations

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

result

any

anyString

anyLong

anyInt

anyShort

anyByte

anyBoolean

anyChar

anyDouble

anyFloat

forEachInvocation

times

minTimes

maxTimes

$

Constructor Detail

Expectations

Expectations

Expectations

Method Detail

returns

returns

notStrict

onInstance

with

with

with

withAny

withCapture

withEqual

withEqual

withEqual

withInstanceLike

withInstanceOf

withNotEqual

withNull

withNotNull

withSameInstance

withSubstring

withPrefix

withSuffix

withMatch

newInstance

newInstance

newInnerInstance

invoke

invoke

invoke

invoke

getField

getField

getField

getField

setField

setField

setField

setField