mockit.Capturing 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-2012 Rogério Liesenfeld
 * This file is subject to the terms of the MIT license (see LICENSE.txt).
 */
package mockit;

import java.lang.annotation.*;

/**
 * Indicates a mock field or a mock parameter for which all classes extending/implementing the mocked type will
 * also get mocked.
 * 
 * In the case of a non-final "capturing" mock field, mocked instances will (by default) be captured and assigned to
 * the mock field as they are created.
 * Otherwise (ie, when applied to a {@code final} mock field or to a mock parameter), instances are still captured but
 * not made directly available to the test.
 * The {@link #maxInstances} attribute allows an upper limit to the number of captured instances to be specified.
 * If multiple capturing mock fields of the same type are declared, this attribute can be used so that each distinct
 * instance gets assigned to a separate field.
 * 

 * Note that, once a capturing mocked type is in scope, the capture of implementation classes and their instances can
 * happen at any moment before the first expected invocation is recorded, or during the recording and replay phases.
 * 

 * In the Tutorial
 * 

 * Sample tests:
 * SubclassTest,
 * CapturingImplementationsTest,
 * PropertySetterTest
 *
 * @see #classNames classNames
 * @see #inverse inverse
 * @see #maxInstances maxInstances
 */
@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.PARAMETER})
public @interface Capturing
{
   /**
    * When the annotation is applied to an instance field, this attribute specifies the maximum number of new instances
    * to capture (by assigning them to the field) while the test is running, between those instances which are
    * assignable to the mocked type and are created during the test.
    * 

    * If {@code maxInstances} is zero (or negative), no instances created by a test are captured.
    * 

    * If the value for this attribute is positive or unspecified (the default is {@code Integer.MAX_VALUE}), then
    * whenever an assignable instance is created during test execution and the specified number of new instances has not
    * been previously assigned, the (non-{@code final}) mock field will be assigned that new instance.
    * 

    * It is valid to declare two or more fields of the same mocked type with a positive number of {@code maxInstances}
    * for each one of them, say {@code n1}, {@code n2}, etc.
    * In this case, the first {@code n1} new instances will be assigned to the first field, the following {@code n2} new
    * instances to the second, and so on.
    * 

    * Notice that this attribute does not apply to {@code final} mock fields, which cannot be reassigned.
    */
   int maxInstances() default Integer.MAX_VALUE;

   /**
    * One or more implementation class filters.
    * Only classes which implement/extend the base type and match at least one filter will be considered.
    * 
    * Each filter must contain a {@linkplain java.util.regex.Pattern regular expression} for matching fully qualified
    * class names.
    */
   String[] classNames() default {};

   /**
    * Indicates whether the implementation filters are to be inverted or not.
    * If inverted, only the classes matching them are not captured.
    */
   boolean inverse() default false;
}