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 developer (unit/integration) testing. It contains mocking APIs and other tools, 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.
There is a newer version: 1.7
Show newest version
/*
 * 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 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
{
   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
   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)
    */
   protected final  T withCapture()
   {
      verificationPhase.addArgMatcher(AlwaysTrueMatcher.INSTANCE);
      return null;
   }
}