public abstract class NonStrictExpectations extends Expectations
@Before
method, or a
@BeforeMethod
in a TestNG test class, since such expectations may be used by some tests only, but not all in
the test class.Modifier and Type | Field and Description |
---|---|
protected CharSequence |
$
An string assigned to this field will be used as a prefix for the error message shown for the current expectation
if it's found to be violated.
|
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 one of these types. |
protected Byte |
anyByte
Matches any
byte or Byte value received by a parameter of one of these types. |
protected Character |
anyChar
Matches any
char or Character value received by a parameter of one of these types. |
protected Double |
anyDouble
Matches any
double or Double value received by a parameter of one of these types. |
protected Float |
anyFloat
Matches any
float or Float value received by a parameter of one of these types. |
protected Integer |
anyInt
Matches any
int or Integer value received by a parameter of one of these types. |
protected Long |
anyLong
Matches any
long or Long value received by a parameter of one of these types. |
protected Short |
anyShort
Matches any
short or Short value received by a parameter of one of these types. |
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.
|
result
Modifier | Constructor and Description |
---|---|
protected |
NonStrictExpectations()
Registers one or more non-strict expectations recorded on available mocked types and/or mocked instances, as
written inside the instance initialization body of an anonymous subclass or the called constructor of a named
subclass.
|
protected |
NonStrictExpectations(Integer numberOfIterations,
Object... classesOrObjectsToBePartiallyMocked)
Same as
NonStrictExpectations(Object...) , but considering that the invocations inside the block will
occur in a given number of iterations. |
protected |
NonStrictExpectations(Object... classesOrObjectsToBePartiallyMocked)
Same as
NonStrictExpectations() , except that one or more classes will be partially mocked according to
the expectations recorded in the expectation block. |
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(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> |
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> |
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> |
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> |
withSuffix(T text)
Same as
withEqual(Object) , but checking that a textual invocation argument in the replay phase ends with
the given text. |
returns
protected CharSequence $
IllegalStateException
is thrown.
Notice there are only two different ways in which an expectation can be violated: either an unexpected
invocation occurs during replay, or a missing invocation is detected.protected final Object 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.
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
Deencapsulation.invoke(Object, String, Object...)
), use withAny(T)
instead.protected final Boolean anyBoolean
boolean
or Boolean
value received by a parameter of one of these types.
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.protected final Byte anyByte
byte
or Byte
value received by a parameter of one of these types.
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.protected final Character anyChar
char
or Character
value received by a parameter of one of these types.
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.protected final Double anyDouble
double
or Double
value received by a parameter of one of these types.
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.protected final Float anyFloat
float
or Float
value received by a parameter of one of these types.
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.protected final Integer anyInt
int
or Integer
value received by a parameter of one of these types.
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.protected final Long anyLong
long
or Long
value received by a parameter of one of these types.
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.protected final Short anyShort
short
or Short
value received by a parameter of one of these types.
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.protected final String anyString
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.protected int maxTimes
minTimes
and maxTimes
can be specified for the same expectation, as long as minTimes
is assigned first.protected int minTimes
minTimes
and maxTimes
can be specified for the same expectation, as long as minTimes
is assigned first.protected NonStrictExpectations()
protected NonStrictExpectations(Integer numberOfIterations, Object... classesOrObjectsToBePartiallyMocked)
NonStrictExpectations(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 multiplying by that number
the lower and upper invocation count limits for each invocation inside the expectation block.
Note that by default the invocation count range for a non-strict expectation is [0, ∞), that is, a lower limit of
0 (zero) and no upper limit, so the number of iterations will only be meaningful if a positive and finite limit is
explicitly specified for the expectation.numberOfIterations
- the positive number of iterations for the whole set of invocations recorded inside the
block; when not specified, 1 (one) iteration is assumedclassesOrObjectsToBePartiallyMocked
- one or more classes or objects whose classes are to be partially mockedNonStrictExpectations()
,
Tutorialprotected NonStrictExpectations(Object... classesOrObjectsToBePartiallyMocked)
NonStrictExpectations()
, except that one or more classes will be partially mocked according to
the expectations recorded in the expectation block.
The classes to be partially mocked are those directly specified through their Class
objects as well as
those to which any given objects belong.
During replay, any invocations to one of these classes or objects will execute real production code, unless a
matching expectation was recorded.
This mechanism, however, does not apply to native
methods, which are not supported for partial mocking.
For a given Class
object, all constructors and methods can be mocked, from the specified class up to but
not including java.lang.Object
.
For a given object, only methods can be mocked, not constructors; also, during replay, invocations to
instance methods will only match expectations recorded on the given instance (or instances, if more than one was
given).classesOrObjectsToBePartiallyMocked
- one or more classes or objects whose classes are to be partially mockedIllegalArgumentException
- 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 typeNonStrictExpectations(Integer, Object...)
,
Tutorialprotected final <T> T onInstance(T mockedInstance)
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.protected final <T> T with(Delegate<? super T> objectWithDelegateMethod)
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.objectWithDelegateMethod
- an instance of a class defining a single non-private
delegate methodT
if it's a primitive wrapper type, or null
otherwisewithArgThat(org.hamcrest.Matcher)
,
Tutorialprotected final <T> T withAny(T arg)
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 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.arg
- an arbitrary value which will match any argument value in the replay phaseprotected final <T> T withArgThat(org.hamcrest.Matcher<? super T> argumentMatcher)
argumentMatcher
- any org.hamcrest.Matcher
objectnull
if there is no such value to be
foundwith(Delegate)
protected final <T> T withCapture(List<T> valueHolderForMultipleInvocations)
valueHolderForMultipleInvocations
- list into which the arguments received by matching invocations will be
addedT
Verifications.withCapture()
,
Verifications.withCapture(Object)
,
Tutorialprotected final double withEqual(double value, double delta)
withEqual(Object)
, but checking that a numeric invocation argument in the replay phase is
sufficiently close to the given value.value
- the center value for range comparisondelta
- the tolerance around the center value, for a range of [value - delta, value + delta]value
protected final float withEqual(float value, double delta)
withEqual(Object)
, but checking that a numeric invocation argument in the replay phase is
sufficiently close to the given value.value
- the center value for range comparisondelta
- the tolerance around the center value, for a range of [value - delta, value + delta]value
protected final <T> T withEqual(T arg)
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.arg
- the expected argument valueprotected final <T> T withInstanceLike(T object)
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
.object
- an instance of the desired classprotected final <T> T withInstanceOf(Class<T> argClass)
withEqual(Object)
, but checking that an invocation argument in the replay phase is an instance of
the given class.argClass
- the desired classnull
; if you need a specific return value, use withInstanceLike(Object)
protected final <T extends CharSequence> T withMatch(T regex)
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).regex
- an arbitrary (non-null) regular expression against which textual argument values will be matchedPattern.compile(String, int)
,
Tutorialprotected final <T> T withNotEqual(T arg)
withEqual(Object)
, but checking that the invocation argument in the replay phase is different
from the given value.arg
- an arbitrary value, but different from the ones expected to occur during replayprotected final <T> T withNotNull()
withEqual(Object)
, but checking that an invocation argument in the replay phase is not
null
.null
protected final <T> T withNull()
withEqual(Object)
, but checking that an invocation argument in the replay phase is null
.null
protected final <T extends CharSequence> T withPrefix(T text)
withEqual(Object)
, but checking that a textual invocation argument in the replay phase starts
with the given text.text
- an arbitrary non-null textual valueprotected final <T> T withSameInstance(T object)
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.object
- the desired instanceprotected final <T extends CharSequence> T withSubstring(T text)
withEqual(Object)
, but checking that a textual invocation argument in the replay phase contains
the given text as a substring.text
- an arbitrary non-null textual valueprotected final <T extends CharSequence> T withSuffix(T text)
withEqual(Object)
, but checking that a textual invocation argument in the replay phase ends with
the given text.text
- an arbitrary non-null textual value