Package mockit

Class Expectations

java.lang.Object
mockit.Expectations
public class Expectations extends Object
Used to record expectations on mocked types and their instances.

Each recorded expectation is intended to match one or more method or constructor invocations, that we expect will occur during the execution of code under test, and which need to exhibit some specific behavior for the purposes of the test. When a match is detected, the recorded result (if any) is returned to the caller. Alternatively, a recorded exception/error is thrown, or an arbitrary delegate method is executed.

Expectations are recorded simply by invoking the desired method or constructor on the mocked type/instance, during the initialization of an Expectations object. This is done by instantiating an anonymous subclass containing an instance initialization body, or as we call it, an expectation block: 


 // <em>Record</em> one or more expectations on available mocked types/instances.
 new Expectations() {{
    <strong>mock1</strong>.expectedMethod(anyInt); result = 123; times = 2;
    <strong>mock2</strong>.anotherExpectedMethod(1, "test"); result = "Abc";
 }};

 // Exercise tested code, with previously recorded expectations now available for <em>replay</em>.
 codeUnderTest.doSomething();
During replay, invocations matching a recorded expectation must occur at least once (unless specified otherwise); if, by the end of the test, no matching invocation occurred for a given recorded expectation, the test will fail with a MissingInvocation error.

When multiple expectations are recorded, matching invocations are allowed to occur in a different order. So, the order in which expectations are recorded is not significant.

Besides the special result field already mentioned, there are several other fields and methods which can be used inside the expectation block: a) returns(Object, Object, Object...), a convenience method for returning a sequence of values; b) argument matchers such as anyInt, anyString, withNotNull(), etc., which relax or constrain the matching of argument values; c) the times, minTimes, and maxTimes fields, which relax or constrain the expected and/or allowed number of matching invocations.

By default, the exact instance on which instance method invocations will occur during replay is not verified to be the same as the instance used when recording the expectation. That said, instance-specific matching can be obtained by declaring the mocked type as @Injectable, or by declaring multiple mock fields and/or mock parameters of the same mocked type (so that separate expectations can be recorded for each mock instance).

Invocations occurring during replay, whether they matched recorded expectations or not, can be explicitly verified after exercising the code under test. To that end, we use a set of complementary base classes: Verifications, VerificationsInOrder, and FullVerifications. Similar to expectation blocks, these classes allow us to create verification blocks.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final Object
    any
    Matches any Object reference received by a parameter of a reference type.
    protected final Boolean
    anyBoolean
    Matches any boolean or Boolean value received by a parameter of that type.
    protected final Byte
    anyByte
    Matches any byte or Byte value received by a parameter of that type.
    protected final Character
    anyChar
    Matches any char or Character value received by a parameter of that type.
    protected final Double
    anyDouble
    Matches any double or Double value received by a parameter of that type.
    protected final Float
    anyFloat
    Matches any float or Float value received by a parameter of that type.
    protected final Integer
    anyInt
    Matches any int or Integer value received by a parameter of that type.
    protected final Long
    anyLong
    Matches any long or Long value received by a parameter of that type.
    protected final Short
    anyShort
    Matches any short or Short value received by a parameter of that type.
    protected final 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 positive 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 Object
    result
    A value assigned to this field will be taken as the result for the expectation that is being recorded.
    protected @org.checkerframework.checker.index.qual.NonNegative 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
    Description
    protected
    Expectations()
    Registers one or more expectations recorded on available mocked types and/or mocked instances, as written inside the instance initialization body of an anonymous subclass.
    protected
    Expectations(Object... objectsToBePartiallyMocked)
    Same as Expectations(), except that one or more objects will be partially mocked according to the expectations recorded in the expectation block.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected final void
    returns(Object firstValue, Object secondValue, Object... remainingValues)
    Specifies that the previously recorded method invocation will return a given sequence of values during replay.
    protected final <T> T
    with(Delegate<? super T> objectWithDelegateMethod)
    Applies a custom argument matcher for a parameter in the current expectation.
    protected final <T> T
    withAny(T arg)
    Same as withEqual(Object), but matching any argument value of the appropriate type (null included).
    protected final <T> T
    withArgThat(org.hamcrest.Matcher<? super T> argumentMatcher)
    Applies a Hamcrest argument matcher for a parameter in the current expectation.
    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.
    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.
    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.
    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.
    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.
    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.
    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.
    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.
    protected final <T> T
    withNotNull()
    Same as withEqual(Object), but checking that an invocation argument in the replay phase is not null.
    protected final <T> T
    withNull()
    Same as withEqual(Object), but checking that an invocation argument in the replay phase is null.
    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.
    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.
    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.
    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.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • result

      @Nullable protected Object result
      A value assigned to this field will be taken as the result for the expectation that is being recorded.

      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 no result is recorded for a given expectation, then all matching invocations will return the appropriate default value according to the method return type:

      • Most java.lang types (String, Object, etc.): returns null.
      • java.math types (BigDecimal, etc.): returns null.
      • Primitive/wrapper types: returns the standard default value (false for boolean/Boolean, 0 for int/Integer, and so on).
      • java.util.List, java.util.Collection, or java.lang.Iterable: returns Collections.EMPTY_LIST.
      • java.util.Iterator or java.util.ListIterator: returns an empty iterator.
      • 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.
      • java.util.Optional: returns Optional.empty().
      • Other reference types: returns a mocked instance through cascading.
      • Array types: returns an array with zero elements (empty) in each dimension.
      When an expectation is recorded for a method which actually returns an exception or error (as opposed to throwing one), then the returns(Object, Object, Object...) method should be used instead, as it only applies to return values.

      Assigning a value whose type differs from the method return type will cause an IllegalArgumentException to be thrown, unless it can be safely converted to the return type. One such conversion is from an array to a collection or iterator. Another is from an array of at least two dimensions to a map, with the first dimension providing the keys and the second the values. Yet another conversion is from a single value to a container type holding that value.

      A sequence of consecutive results can be recorded simply by assigning the field multiple times for the same expectation. Alternatively, the desired sequence of results for a single-valued return type can be recorded by assigning an array, an Iterable, or an Iterator containing the individual results in order.

      Results that depend on some programming logic can be provided through a Delegate object assigned to the field. This applies to void and non-void methods, as well as to constructors.

      See Also:

    • any

      @Nullable 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:

    • anyString

      @NonNull 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:

    • anyLong

      @NonNull 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:

    • anyInt

      @NonNull 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:

    • anyShort

      @NonNull 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:

    • anyByte

      @NonNull 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

      @NonNull 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:

    • anyChar

      @NonNull 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:

    • anyDouble

      @NonNull 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:

    • anyFloat

      @NonNull 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:

    • times

      protected @org.checkerframework.checker.index.qual.NonNegative 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

      protected int minTimes
      A positive 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 means there is no lower limit.

      If not specified, the default value of 1 (one) is used.

      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, provided minTimes is assigned first.

      See Also:

    • 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 (the default).

      Both minTimes and maxTimes can be specified for the same expectation, provided minTimes is assigned first.

      See Also:

  • Constructor Details

    • Expectations

      protected Expectations()
      Registers one or more expectations recorded on available mocked types and/or mocked instances, as written inside the instance initialization body of an anonymous subclass.
      See Also:

    • Expectations

      protected Expectations(@NonNull Object... objectsToBePartiallyMocked)
      Same as Expectations(), except that one or more objects will be partially mocked according to the expectations recorded in the expectation block.

      During replay, any invocations to instance methods on these objects will execute real production code, unless a matching expectation was recorded.

      Parameters:
      objectsToBePartiallyMocked - one or more objects to be partially mocked
      Throws:
      IllegalArgumentException - if given a Class object, or if given a value/instance of an interface, an annotation, an array, a primitive/wrapper type, a synthetic class, or a proxy class
      See Also:

  • Method Details

    • returns

      protected final void returns(@Nullable Object firstValue, @Nullable Object secondValue, @NonNull Object... remainingValues)
      Specifies that the previously recorded method invocation will return a given sequence of values during replay.

      Calling this method is equivalent to assigning the result field two or more times in sequence, or assigning it a single time with an array or iterable containing the same sequence of values.

      Certain data conversions will be applied, depending on the return type of the recorded method:

      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.
      Parameters:
      firstValue - the first value to be returned at replay time
      secondValue - the second value to be returned at replay time
      remainingValues - any remaining values to be returned, in the same order
      See Also:

    • withArgThat

      @Nullable protected final <T> T withArgThat(@NonNull 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.

      Type Parameters:
      T - the generic type
      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

      @Nullable protected final <T> T with(@NonNull 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.

      Type Parameters:
      T - the generic type
      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:

    • withAny

      @NonNull protected final <T> T withAny(@NonNull T arg)
      Same as withEqual(Object), but matching any argument value of the appropriate type (null included).

      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.

      Type Parameters:
      T - the generic type
      Parameters:
      arg - an arbitrary value which will match any argument value in the replay phase
      Returns:
      the input argument
      See Also:

    • withCapture

      @Nullable protected final <T> T withCapture(@NonNull 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.

      Type Parameters:
      T - the generic type
      Parameters:
      valueHolderForMultipleInvocations - list into which the arguments received by matching invocations will be added
      Returns:
      the default value for type T
      See Also:

    • withEqual

      @NonNull protected final <T> T withEqual(@NonNull 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.

      Type Parameters:
      T - the generic type
      Parameters:
      arg - the expected argument value
      Returns:
      the given argument
      See Also:

    • 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:

    • 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:

    • withInstanceLike

      @NonNull protected final <T> T withInstanceLike(@NonNull 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.

      Type Parameters:
      T - the generic type
      Parameters:
      object - an instance of the desired class
      Returns:
      the given instance
      See Also:

    • withInstanceOf

      @Nullable protected final <T> T withInstanceOf(@NonNull 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.

      Type Parameters:
      T - the generic type
      Parameters:
      argClass - the desired class
      Returns:
      always null; if you need a specific return value, use withInstanceLike(Object)
      See Also:

    • withNotEqual

      @NonNull protected final <T> T withNotEqual(@NonNull 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.

      Type Parameters:
      T - the generic type
      Parameters:
      arg - an arbitrary value, but different from the ones expected to occur during replay
      Returns:
      the given argument value
      See Also:

    • withNull

      @Nullable 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.

      Type Parameters:
      T - the generic type
      Returns:
      always null
      See Also:

    • withNotNull

      @Nullable 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.

      Type Parameters:
      T - the generic type
      Returns:
      always null
      See Also:

    • withSameInstance

      @NonNull protected final <T> T withSameInstance(@NonNull 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.

      Type Parameters:
      T - the generic type
      Parameters:
      object - the desired instance
      Returns:
      the given object
      See Also:

    • withSubstring

      @NonNull protected final <T extends CharSequence> T withSubstring(@NonNull 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.

      Type Parameters:
      T - the generic type
      Parameters:
      text - an arbitrary non-null textual value
      Returns:
      the given text
      See Also:

    • withPrefix

      @NonNull protected final <T extends CharSequence> T withPrefix(@NonNull 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.

      Type Parameters:
      T - the generic type
      Parameters:
      text - an arbitrary non-null textual value
      Returns:
      the given text
      See Also:

    • withSuffix

      @NonNull protected final <T extends CharSequence> T withSuffix(@NonNull 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.

      Type Parameters:
      T - the generic type
      Parameters:
      text - an arbitrary non-null textual value
      Returns:
      the given text
      See Also:

    • withMatch

      @NonNull protected final <T extends CharSequence> T withMatch(@NonNull 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.

      Type Parameters:
      T - the generic type
      Parameters:
      regex - an arbitrary (non-null) regular expression against which textual argument values will be matched
      Returns:
      the given regex
      See Also: