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
JMockit is a Java toolkit for automated developer testing. It contains APIs for the creation of the objects to be tested, for mocking dependencies, and for faking external APIs; JUnit (4 & 5) and TestNG test runners are supported. It also contains an advanced code coverage tool.
There is a newer version: 1.49
Show newest version
/*
 * 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
    * @see Tutorial
    */
   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.
    *
    * @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);
    * }};
    * 
    *
    * @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();
   }
}