mockit.NonStrictExpectations 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.
The newest version!
/*
 * Copyright (c) 2006-2014 Rogério Liesenfeld
 * This file is subject to the terms of the MIT license (see LICENSE.txt).
 */
package mockit;

/**
 * Used to record non-strict expectations on {@linkplain Mocked mocked} types and mocked instances.
 * 
 * A recorded expectation is intended to match a number of method or constructor invocations, that we expect will occur
 * during the execution of some code under test.
 * When a match is detected, the recorded {@linkplain #result result} is returned to the caller.
 * Alternatively, a recorded exception/error is thrown, or an arbitrary {@linkplain Delegate delegate} method is
 * executed.
 * Expectations are recorded simply by invoking the desired method or constructor on the mocked type/instance, during
 * the initialization of a {@code NonStrictExpectations} object.
 * Typically, this is done by instantiating an anonymous subclass containing an instance initialization body, or as we
 * call it, an expectation block:
 * 
 * // Record one or more expectations on available mocked types/instances:
 * new NonStrictExpectations() {{
 *    mock1.expectedMethod(anyInt); result = 123; times = 1;
 *    MockedClass.allowedMethod(); result = new IOException();
 *    mock2.anotherAllowedMethod(1, "test"); returns("Abc", "xyz");
 * }};
 *
 * // Exercise tested code, with previously recorded expectations now available for replay.
 * codeUnderTest.doSomething();
 * 
 * During replay, invocations matching recorded expectations can occur in any number and in any order.
 * The result the caller gets will be as recorded in the non-strict expectation block.
 * Invocations that don't match any recorded expectation, on the other hand, will simply result in a default value being
 * returned to the caller, or in nothing at all in the case of a {@code void} method.
 * 
 * Multiple expectations on the same method or constructor can be recorded, provided different arguments are used.
 * For flexible matching of parameter values, we can use a variety of argument matching {@linkplain #anyString fields}
 * and {@linkplain #withAny(Object) methods}.
 * Also, multiple separate expectation blocks can be created in the same test method or test setup method.
 * 

 * A lower/upper limit or an exact number of expected invocations can be specified for each recorded expectation,
 * by assigning the {@link #minTimes}, {@link #maxTimes}, or {@link #times} field, as appropriate, when recording the
 * expectation.
 * 

 * Rather than creating anonymous subclasses, we can also create named subclasses to be reused in multiple tests.
 * Some examples:
 * 
 * public final class MyReusableExpectations extends NonStrictExpectations {
 *    public MyReusableExpectations(...any parameters...) {
 *       // expectations recorded here
 *    }
 * }
 *
 * public class ReusableBaseExpectations extends NonStrictExpectations {
 *     protected ReusableBaseExpectations(...) {
 *        // expectations here
 *     }
 * }
 *
 * @Test
 * public void someTest(@Mocked final SomeType aMock, etc.) {
 *     // Record reusable expectations by instantiating a final "...Expectations" class.
 *     new MyReusableExpectations(123, "test", etc.);
 *
 *     // Record and extend reusable expectations by instantiating a non-final base class.
 *     new ReusableBaseExpectations() {{
 *        // additional expectations
 *     }};
 * }
 * 
 * Finally, non-strict expectations, either recorded or not, can be explicitly verified after exercising the
 * code under test, by using a set of complementary base classes: {@link Verifications},
 * {@link mockit.VerificationsInOrder}, etc.
 *
 * @see #NonStrictExpectations()
 * @see #NonStrictExpectations(Object...)
 * @see #NonStrictExpectations(Integer, Object...)
 * @see Tutorial
 */
public abstract class NonStrictExpectations extends Expectations
{
   /**
    * Registers one or more non-strict expectations recorded on available mocked types and/or mocked instances, as
    * written inside the instance initialization body of an anonymous subclass or the called constructor of a named
    * subclass.
    *
    * @see #NonStrictExpectations(Object...)
    * @see #NonStrictExpectations(Integer, Object...)
    */
   protected NonStrictExpectations() {}

   /**
    * Same as {@link #NonStrictExpectations()}, except that one or more classes will be partially mocked according to
    * the expectations recorded in the expectation block; this feature is known as dynamic partial mocking, in
    * contrast with static partial mocking as specified with the {@link Mocked#value} annotation attribute.
    * 
    * The classes to be partially mocked are those directly specified through their {@code Class} objects as well as
    * those to which any given objects belong.
    * During replay, any invocations to one of these classes or objects will execute real production code, unless a
    * matching expectation was recorded.
    * 

    * For a given {@code Class} object, all constructors and methods will be considered for mocking, from the specified
    * class up to but not including {@code java.lang.Object}.
    * 

    * For a given object, all methods will be considered for mocking, from the concrete class of the given
    * object up to but not including {@code java.lang.Object}.
    * The constructors of those classes will not be considered.
    * During replay, invocations to instance methods will only match expectations recorded on the given instance
    * (or instances, if more than one was given).
    * 

    * In the
    * Tutorial
    *
    * @param classesOrObjectsToBePartiallyMocked one or more classes or objects whose classes are to be considered for
    * partial mocking
    *
    * @throws IllegalArgumentException if given a class literal for an interface, an annotation, an array, a
    * primitive/wrapper type, or a {@linkplain java.lang.reflect.Proxy#isProxyClass(Class) proxy class} created for an
    * interface, or if given a value/instance of such a type
    *
    * @see #NonStrictExpectations(Integer, Object...)
    */
   protected NonStrictExpectations(Object... classesOrObjectsToBePartiallyMocked)
   {
      super(classesOrObjectsToBePartiallyMocked);
   }

   /**
    * Same as {@link #NonStrictExpectations(Object...)}, but considering that the invocations inside the block will
    * occur in a given number of iterations.
    * 

    * The effect of specifying a number of iterations larger than 1 (one) is equivalent to multiplying by that number
    * the lower and upper invocation count limits for each invocation inside the expectation block.
    * Note that by default the invocation count range for a non-strict expectation is [0, ∞), that is, a lower limit of
    * 0 (zero) and no upper limit, so the number of iterations will only be meaningful if a positive and finite limit is
    * explicitly specified for the expectation.
    * 
    * In
    * the Tutorial
    *
    * @param numberOfIterations the positive number of iterations for the whole set of invocations recorded inside the
    * block; when not specified, 1 (one) iteration is assumed
    * @param classesOrObjectsToBePartiallyMocked one or more classes or objects whose classes are to be considered for
    * partial mocking
    *
    * @see #NonStrictExpectations()
    */
   protected NonStrictExpectations(Integer numberOfIterations, Object... classesOrObjectsToBePartiallyMocked)
   {
      super(classesOrObjectsToBePartiallyMocked);
      getCurrentPhase().setNumberOfIterations(numberOfIterations);
   }
}