mockit

Class Verifications

java.lang.Object

mockit.Verifications

Direct Known Subclasses:

FullVerifications, FullVerificationsInOrder, VerificationsInOrder

public abstract class Verifications
extends Object

Used to verify a set of expectations on available mocked types and/or instances, against the invocations which actually occurred during the test. As such, these verifications can only appear after having exercised the code under test.

An expectation verification attempts to match a number of method or constructor invocations, that we expect have occurred during the execution of code under test. By default, at least one matching invocation must be found for the verification to be successful; if no matching invocations are found, an assertion error is thrown.

Expectations are verified simply by invoking the desired method or constructor on a mocked type/instance, during the initialization of a Verifications object. Typically, this is done by instantiating an anonymous subclass containing an instance initialization body, or as we call it, a verification block:

 // Exercise tested code.
 codeUnderTest.doSomething();

 // Now verify that the expected invocations actually occurred (in any order).
 new Verifications() {{
    mock1.expectedMethod(anyInt);
    mock2.anotherExpectedMethod(1, "test"); times = 2;
 }};
 

The relative order between the invocations that match two or more verifications is not taken into consideration; when that is desired, the VerificationsInOrder class should be used instead.

Naturally, not all invocations that occurred during the execution of code under test need to be explicitly verified in a verification block. If desired, however, we can make sure that all such invocations are verified, by using the FullVerifications class instead.

See Also:

Verifications(), Verifications(int), withCapture(), Expectations, Tutorial

Field Summary

Fields

Modifier and Type	Field and Description
protected Object	any Matches any Object reference received by a parameter of a reference type.
protected Boolean	anyBoolean Matches any boolean or Boolean value received by a parameter of that type.
protected Byte	anyByte Matches any byte or Byte value received by a parameter of that type.
protected Character	anyChar Matches any char or Character value received by a parameter of that type.
protected Double	anyDouble Matches any double or Double value received by a parameter of that type.
protected Float	anyFloat Matches any float or Float value received by a parameter of that type.
protected Integer	anyInt Matches any int or Integer value received by a parameter of that type.
protected Long	anyLong Matches any long or Long value received by a parameter of that type.
protected Short	anyShort Matches any short or Short value received by a parameter of that type.
protected String	anyString Matches any String value received by a parameter of this type.
protected 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 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 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	Verifications() Begins a set of unordered expectation verifications, on the available mocked types and/or mocked instances.
protected	Verifications(int numberOfIterations) Same as Verifications(), but considering that such invocations occurred in a given number of iterations.

Method Summary

Modifier and Type	Method and Description
protected <T> T	onInstance(T mockedInstance) Calling this method causes the expectation recorded/verified on the given mocked instance to match only those invocations that occur on the same instance, at replay time.
protected <T> T	with(Delegate<? super T> objectWithDelegateMethod) Applies 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	withArgThat(org.hamcrest.Matcher<? super T> argumentMatcher) Applies a Hamcrest argument matcher for a parameter in the current expectation.
protected <T> T	withCapture() Captures the argument value passed into the associated expectation parameter, for a matching invocation that occurred when the tested code was exercised.
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 <T> List<T>	withCapture(T constructorVerification) Captures new instances of type T that were created by the code under test.
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

any

protected final Object any

Matches any Object reference received by a parameter of a reference type.

This field can only be used as the argument value at the proper parameter position in a method/constructor invocation, when recording or verifying an expectation; it cannot be used anywhere else.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

Notice 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.

To match an entire varargs parameter of element type V (ie, all arguments in the array), cast it to the parameter type: "(V[]) any".

See Also:

anyBoolean, anyByte, anyChar, anyDouble, anyFloat, anyInt, anyLong, anyShort, anyString, Tutorial

anyBoolean

protected final Boolean anyBoolean

Matches any boolean or Boolean value received by a parameter of that type.

This field can only be used as the argument value at the proper parameter position in a method/constructor invocation, when recording or verifying an expectation; it cannot be used anywhere else.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

See Also:

anyByte, anyChar, anyDouble, anyFloat, anyInt, anyLong, anyShort, anyString, any, Tutorial

anyByte

protected final Byte anyByte

Matches any byte or Byte value received by a parameter of that type.

This field can only be used as the argument value at the proper parameter position in a method/constructor invocation, when recording or verifying an expectation; it cannot be used anywhere else.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

See Also:

anyBoolean, anyChar, anyDouble, anyFloat, anyInt, anyLong, anyShort, anyString, any, Tutorial

anyChar

protected final Character anyChar

Matches any char or Character value received by a parameter of that type.

This field can only be used as the argument value at the proper parameter position in a method/constructor invocation, when recording or verifying an expectation; it cannot be used anywhere else.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

See Also:

anyBoolean, anyByte, anyDouble, anyFloat, anyInt, anyLong, anyShort, anyString, any, Tutorial

anyDouble

protected final Double anyDouble

Matches any double or Double value received by a parameter of that type.

This field can only be used as the argument value at the proper parameter position in a method/constructor invocation, when recording or verifying an expectation; it cannot be used anywhere else.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

See Also:

anyBoolean, anyByte, anyChar, anyFloat, anyInt, anyLong, anyShort, anyString, any, Tutorial

anyFloat

protected final Float anyFloat

Matches any float or Float value received by a parameter of that type.

This field can only be used as the argument value at the proper parameter position in a method/constructor invocation, when recording or verifying an expectation; it cannot be used anywhere else.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

See Also:

anyBoolean, anyByte, anyChar, anyDouble, anyInt, anyLong, anyString, anyShort, any, Tutorial

anyInt

protected final Integer anyInt

Matches any int or Integer value received by a parameter of that type.

This field can only be used as the argument value at the proper parameter position in a method/constructor invocation, when recording or verifying an expectation; it cannot be used anywhere else.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

See Also:

anyBoolean, anyByte, anyChar, anyDouble, anyFloat, anyLong, anyShort, anyString, any, Tutorial

anyLong

protected final Long anyLong

Matches any long or Long value received by a parameter of that type.

This field can only be used as the argument value at the proper parameter position in a method/constructor invocation, when recording or verifying an expectation; it cannot be used anywhere else.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

See Also:

anyBoolean, anyByte, anyChar, anyDouble, anyFloat, anyInt, anyShort, anyString, any, Tutorial

anyShort

protected final Short anyShort

Matches any short or Short value received by a parameter of that type.

This field can only be used as the argument value at the proper parameter position in a method/constructor invocation, when recording or verifying an expectation; it cannot be used anywhere else.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

See Also:

anyBoolean, anyByte, anyChar, anyDouble, anyFloat, anyInt, anyLong, anyString, any, Tutorial

anyString

protected final String anyString

Matches any String value received by a parameter of this type.

This field can only be used as the argument value at the proper parameter position in a method/constructor invocation, when recording or verifying an expectation; it cannot be used anywhere else.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

See Also:

anyBoolean, anyByte, anyChar, anyDouble, anyFloat, anyInt, anyLong, anyShort, any, Tutorial

maxTimes

protected 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, Tutorial

minTimes

protected 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, Tutorial

times

protected 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.

See Also:

minTimes, maxTimes, Tutorial

Constructor Detail

Verifications

protected Verifications()

Begins a set of unordered expectation verifications, on the available mocked types and/or mocked instances. Such verifications are meant to be executed after the call to code under test has been made.

See Also:

Verifications(int)

Verifications

protected Verifications(int numberOfIterations)

Same as Verifications(), but considering that such invocations occurred in a given number of iterations.

The effect of specifying a (positive) number of iterations is equivalent to setting to that number the lower and upper invocation count limits for each expectation verified. If, however, the lower/upper limit is explicitly specified for an expectation, the given number of iterations becomes a multiplier. When not specified, at least one matching invocation will be required to have occurred; therefore, specifying 1 (one) iteration is different from not specifying the number of iterations at all.

Parameters:

numberOfIterations - the positive number of iterations for the whole set of verified expectations

See Also:

times, minTimes, maxTimes, Tutorial

Method Detail

withCapture

protected final <T> T withCapture()

Captures the argument value passed into the associated expectation parameter, for a matching invocation that occurred when the tested code was exercised. This method should be used in a local variable assignment expression inside a verification block. For example:

 codeUnderTest.doSomething();

 new Verifications() {{
    String name;
    int age;
    personDAOMock.create(age = withCapture(), name = withCapture());
    assertFalse(name.isEmpty());
    assertTrue(age >= 18);
 }};
 

If there is more than one matching invocation, then only the last one to have occurred is considered. Apart from capturing received argument values, this method has the same effect as the any argument matcher.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

Returns:

the captured argument value

See Also:

withCapture(List), withCapture(Object), Tutorial

withCapture

protected final <T> List<T> withCapture(T constructorVerification)

Captures new instances of type T that were created by the code under test. Said instances are only those which were created through constructor invocations matching the constructor verification that was passed as argument in a call to this method. For example:

 codeUnderTest.doSomething();

 new Verifications() {{
    List<Person> newPersons = withCapture(new Person());
    Person newPerson = newPersons.get(0);

    Person personCreated;
    personDAOMock.create(personCreated = withCapture());

    assertSame(newPerson, personCreated);
 }};
 

Note this is not meant be used as an argument matcher.

Parameters:

constructorVerification - a new instance of the desired mocked class, created through a regular constructor verification

Returns:

a list with the (zero, one, or more) captured new instances that match the verified constructor invocation

See Also:

withCapture(), withCapture(List), Tutorial

onInstance

protected final <T> T onInstance(T mockedInstance)

Calling this method causes the expectation recorded/verified on the given mocked instance to match only those invocations that occur on the same instance, at replay time.

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 mock 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.

Returns:

the given mocked instance, allowing the invocation being recorded/verified to immediately follow the call to this method

See Also:

Tutorial

with

protected final <T> T with(Delegate<? super T> objectWithDelegateMethod)

Applies a custom argument matcher for a parameter in the current expectation.

The class of the given delegate object should define a single non-private delegate method (plus any number of helper private methods). The name of the delegate method doesn't matter, but it must have a single parameter capable of receiving the relevant argument values.

The return type of the delegate method 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 actual invocation argument should be validated through a suitable JUnit/TestNG assertion.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

Parameters:

objectWithDelegateMethod - an instance of a class defining a single non-private delegate method

Returns:

the default primitive value corresponding to T if it's a primitive wrapper type, or null otherwise

See Also:

withArgThat(org.hamcrest.Matcher), Tutorial

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.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

Note: when using Deencapsulation.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

See Also:

Tutorial

withArgThat

protected final <T> T withArgThat(org.hamcrest.Matcher<? super T> argumentMatcher)

Applies a Hamcrest argument matcher for a parameter in the current expectation.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

Parameters:

argumentMatcher - any org.hamcrest.Matcher object

Returns:

the value recorded inside the given Hamcrest matcher, or null if there is no such value to be found

See Also:

with(Delegate)

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. Apart from capturing received argument values, this method has the same effect as the any argument matcher.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

Parameters:

valueHolderForMultipleInvocations - list into which the arguments received by matching invocations will be added

Returns:

the default value for type T

See Also:

withCapture(), withCapture(Object), Tutorial

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.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

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

See Also:

Tutorial

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.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

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

See Also:

Tutorial

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.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(value) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

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.

Parameters:

arg - the expected argument value

Returns:

the given argument

See Also:

Tutorial

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.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

Parameters:

object - an instance of the desired class

Returns:

the given instance

See Also:

Tutorial

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.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

Parameters:

argClass - the desired class

Returns:

always null; if you need a specific return value, use withInstanceLike(Object)

See Also:

Tutorial

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).

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

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), Tutorial

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.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

Parameters:

arg - an arbitrary value, but different from the ones expected to occur during replay

Returns:

the given argument value

See Also:

Tutorial

withNotNull

protected final <T> T withNotNull()

Same as withEqual(Object), but checking that an invocation argument in the replay phase is not null.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

Returns:

always null

See Also:

Tutorial

withNull

protected final <T> T withNull()

Same as withEqual(Object), but checking that an invocation argument in the replay phase is null.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

Returns:

always null

See Also:

Tutorial

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.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

Parameters:

text - an arbitrary non-null textual value

Returns:

the given text

See Also:

Tutorial

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.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

Parameters:

object - the desired instance

Returns:

the given object

See Also:

Tutorial

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.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

Parameters:

text - an arbitrary non-null textual value

Returns:

the given text

See Also:

Tutorial

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.

When an argument matcher is used for a regular (ie, non-varargs) parameter in a call to a mocked method/constructor, it's not necessary to also use matchers for the other parameters. So, it's valid to mix the use of matchers with given values. Any arguments given as literals, local variables, or fields, will be implicitly matched as if withEqual(Object) had been used. In the special case of a varargs method, however, this flexibility is not available: if a matcher is used for any regular parameter, or for any element in the varargs array, then a matcher must be used for every other parameter and varargs element.

Parameters:

text - an arbitrary non-null textual value

Returns:

the given text

See Also:

Tutorial