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 JMockit developers
* 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
* Verifications object.
* 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.
*
* Not all invocations that occurred during the execution of code under test need to be explicitly verified in a verification block.
* If that is desired, we can make sure that all such invocations are verified, by using the {@link FullVerifications} class.
*
* @see #Verifications()
* @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.
*/
protected Verifications() { this(false); }
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.
* 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
*/
@Nullable
protected final T withCapture() {
verificationPhase.addArgMatcher(AlwaysTrueMatcher.ANY_VALUE);
return null;
}
/**
* 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.
*
* @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
*/
@Nonnull
protected final List withCapture(@Nonnull T constructorVerification) {
return verificationPhase.getNewInstancesMatchingVerifiedConstructorInvocation();
}
}