mockit.Verifications Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of jmockit Show documentation
Show all versions of jmockit Show documentation
JMockit is a Java toolkit for automated developer testing.
It contains mocking/faking APIs and a code coverage tool, supporting both JUnit and TestNG.
The mocking APIs allow all kinds of Java code, without testability restrictions, to be tested
in isolation from selected dependencies.
/*
* Copyright (c) 2006 Rogério Liesenfeld
* This file is subject to the terms of the MIT license (see LICENSE.txt).
*/
package mockit;
import java.util.*;
import javax.annotation.*;
import mockit.internal.expectations.*;
import mockit.internal.expectations.argumentMatching.*;
import mockit.internal.state.*;
/**
* Used to verify a set of expectations on available {@linkplain Mocked 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 {@code 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 {@link 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
* {@link FullVerifications} class instead.
*
* @see #Verifications()
* @see #Verifications(int)
* @see #withCapture()
* @see Expectations
* @see Tutorial
*/
public abstract class Verifications extends Invocations
{
@Nonnull final BaseVerificationPhase verificationPhase;
/**
* 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 #Verifications(int)
*/
protected Verifications() { this(false); }
/**
* Same as {@link #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.
*
* @param numberOfIterations the positive number of iterations for the whole set of verified expectations
*
* @see #times
* @see #minTimes
* @see #maxTimes
*/
protected Verifications(int numberOfIterations)
{
this(false);
verificationPhase.setNumberOfIterations(numberOfIterations);
}
Verifications(boolean inOrder)
{
RecordAndReplayExecution instance = TestRun.getRecordAndReplayForVerifications();
verificationPhase = instance.startVerifications(inOrder);
}
@Nonnull @Override
final BaseVerificationPhase getCurrentPhase() { return verificationPhase; }
/**
* 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 {@link #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
* {@link #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.
*
* @return the captured argument value
*
* @see #withCapture(List)
* @see #withCapture(Object)
* @see Tutorial
*/
protected final T withCapture()
{
verificationPhase.addArgMatcher(AlwaysTrueMatcher.ANY_VALUE);
//noinspection ConstantConditions
return null;
}
/**
* Captures new instances of type {@code 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.
*
* @param constructorVerification a new instance of the desired mocked class, created through a regular constructor
* verification
*
* @return a list with the (zero, one, or more) captured new instances that match the verified constructor invocation
*
* @see #withCapture()
* @see #withCapture(List)
* @see Tutorial
*/
protected final List withCapture(@SuppressWarnings("unused") T constructorVerification)
{
return verificationPhase.getNewInstancesMatchingVerifiedConstructorInvocation();
}
}