mockit.Verifications Maven / Gradle / Ivy

Go to download
/*
 * Copyright (c) 2006-2013 Rogério Liesenfeld
 * This file is subject to the terms of the MIT license (see LICENSE.txt).
 */
package mockit;

import java.lang.reflect.*;
import java.util.*;

import org.jetbrains.annotations.*;

import mockit.internal.expectations.argumentMatching.*;
import mockit.internal.state.*;
import mockit.internal.expectations.*;
import mockit.internal.util.*;

/**
 * A set of expectations on mocked types and/or instances to be verified against the invocations which actually occurred
 * during the test.
 * As such, these so called verification blocks can only appear after having exercised the code under
 * test.
 *  *
 * // Exercise tested code, then verify that expected invocations occurred in any order:
 * new Verifications() {{
 *    mock1.expectedMethod(anyInt);
 *    mock2.anotherExpectedMethod(1, "test"); times = 2;
 * }};
 * The relative order of invocations is not relevant here; for that, use {@link VerificationsInOrder} instead.
 * Any subset of actual invocations can be verified; to make sure that all have been, if needed, use
 * {@link FullVerifications} instead.
 * 
 * For an expectation inside a verification block to succeed (ie, pass verification), a matching invocation must have
 * occurred during the replay (exercise) phase of the test, at least once.
 * This is only the default verification behavior, though. Just like with recorded expectations, it's possible
 * to specify different invocation count constraints through the {@link #times}, {@link #minTimes}, and
 * {@link #maxTimes} fields.
 * 

 * Besides the mock fields and mock parameters available to the test, a verification block can also import
 * local mock fields declared inside expectation blocks, by declaring a local field of the desired mocked type.
 * 

 * In the
 * Tutorial
 *
 * @see #Verifications()
 * @see #Verifications(int)
 * @see #withCapture()
 */
public abstract class Verifications extends Invocations
{
   @NotNull final BaseVerificationPhase verificationPhase;

   /**
    * Begins a block unordered verifications on the mocked types/instances invoked during the replay phase of the test.
    *
    * @see #Verifications(int)
    */
   protected Verifications() { this(false); }

   /**
    * Begins a block of unordered verifications on the mocked types/instances invoked during the replay phase of the
    * test, 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 inside the block.
    * 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.
    * 

    * In the Tutorial
    *
    * @param numberOfIterations the positive number of iterations for the whole set of invocations verified inside the
    * block
    *
    * @see #Verifications()
    * @see #times
    * @see #minTimes
    * @see #maxTimes
    */
   protected Verifications(int numberOfIterations)
   {
      this(false);
      verificationPhase.setNumberOfIterations(numberOfIterations);
   }

   Verifications(boolean inOrder)
   {
      RecordAndReplayExecution instance = TestRun.getExecutingTest().getRecordAndReplayForVerifications();

      Map availableLocalMocks = instance.getLocalMocks();

      if (!availableLocalMocks.isEmpty()) {
         importMocksIntoLocalFields(getClass(), availableLocalMocks);
      }

      verificationPhase = instance.startVerifications(inOrder);
   }

   private void importMocksIntoLocalFields(Class ownerClass, Map localMocks)
   {
      Field[] fields = ownerClass.getDeclaredFields();

      for (Field fieldToImport : fields) {
         if (!Modifier.isFinal(fieldToImport.getModifiers())) {
            importMockIntoLocalField(localMocks, fieldToImport);
         }
      }

      Class superClass = ownerClass.getSuperclass();

      if (
         superClass != Verifications.class && superClass != VerificationsInOrder.class &&
         superClass != FullVerifications.class && superClass != FullVerificationsInOrder.class
      ) {
         importMocksIntoLocalFields(superClass, localMocks);
      }
   }

   private void importMockIntoLocalField(Map localMocks, Field field)
   {
      Type mockedType = field.getGenericType();
      Object owner = localMocks.get(mockedType);

      if (owner != null) {
         Object mock = FieldReflection.getField(owner.getClass(), mockedType, owner);
         FieldReflection.setFieldValue(field, this, mock);
      }
   }

   @Override
   @NotNull 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:
    * 
    *    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 is considered.
    *
    * @return the captured argument value
    *
    * @see #withCapture(java.util.List)
    */
   @Nullable protected final  T withCapture()
   {
      verificationPhase.addArgMatcher(AlwaysTrueMatcher.INSTANCE);
      return null;
   }
}