mockit.Mocked Maven / Gradle / Ivy

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

import java.lang.annotation.*;

/**
 * This annotation can be applied to instance fields of a test class, and to parameters of test methods.
 * Such fields and parameters are said to be mock fields and mock parameters, respectively.
 * In either case, the declared type of the annotated field or parameter is the mocked type;
 * any type can be mocked, except for primitive and array types.
 * A mocked instance of that type is automatically created and assigned to the mock field/parameter, for use when
 * {@linkplain NonStrictExpectations recording} or {@linkplain Verifications verifying} expectations.
 * 
 * The effect of declaring a {@code @Mocked} type, by default, is that all new instances of that type, as well as those
 * previously created, will also be mocked instances; this will last for the duration of each test where the associated
 * mock field/parameter is in scope.
 * Also, all methods of the mocked type will be mocked, unless a subset is {@linkplain #value explicitly specified}.
 * 

 * When the mocked type is a class, all super-classes up to but not including {@code java.lang.Object} are also mocked.
 * Additionally, static methods and constructors are mocked as well, just like instance methods.
 * 

 * When mocking an {@code enum} type, the {@code java.lang.Enum} base class is not mocked by default.
 * If needed, however, base types like {@code Object} and {@code Enum} can be mocked by explicitly declaring a mock
 * field or mock parameter of the specific base type.
 * 

 * While a method or constructor is mocked, an invocation does not result in the execution of the original code, but in
 * a (generated) call into JMockit, which then responds with either a default or a recorded result (or with a
 * constraint violation, if the invocation is deemed to be unexpected - which depends on a few factors discussed
 * elsewhere).
 * 

 * Static class initializers (including assignments to {@code static} fields) of a mocked class are not
 * affected, unless {@linkplain #stubOutClassInitialization specified otherwise}.
 * 

 * Normally, a new mocked instance gets created and assigned to a declared mock field/parameter automatically.
 * An exception to that occurs in the case of a mocked {@code enum} type, where the first enumeration element is used.
 * Alternatively, and only in the case of a mock field, the test itself can provide the instance by declaring
 * the field as {@code final} and explicitly assigning it with the desired instance (which will still be a mocked
 * instance); if no instance is necessary (perhaps because only static methods or constructors will be called), then
 * this final field can receive the {@code null} reference.
 * Mock parameters, on the other hand, will always receive a new mocked instance whenever the test method is executed by
 * the test runner.
 *
 * @see #value
 * @see #stubOutClassInitialization
 * @see Tutorial
 */
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.PARAMETER})
public @interface Mocked
{
   /**
    * One or more mock filters.
    * Given a target class for mocking, only those methods and constructors which match at least one filter will be
    * mocked.
    * 

    * Each mock filter must follow the syntax {@code [nameRegex][(paramTypeName...)]}, where
    * {@code nameRegex} is a {@linkplain java.util.regex.Pattern regular expression} for matching method names, and
    * {@code paramTypeName} is the name of a primitive or reference parameter type (actually, any suffix of the type
    * name is enough, like "String" instead of the full class name "java.lang.String").
    * If {@code nameRegex} is omitted the filter matches only constructors.
    * If {@code (paramTypeName...)} is omitted the filter matches methods with any parameters.
    * 

    * If no filters are specified, then all methods and constructors declared in the target class are mocked.
    * 

    * A filter containing just the empty string matches no methods or constructors of the target class;
    * this can be used to obtain a mocked instance where no executable code is actually mocked.
    *
    * @see #stubOutClassInitialization
    * @see Tutorial
    */
   String[] value() default {};

   /**
    * Indicates whether static initialization code in the mocked class should be stubbed out or not.
    * Static initialization includes the execution of assignments to static fields of the class and the execution of
    * static initialization blocks, if any.
    * (Note that {@code static final} fields initialized with compile-time constants are not assigned at
    * runtime, remaining unaffected whether the class is stubbed out or not.)
    * 
    * By default, static initialization code in a mocked class is not stubbed out.
    * The JVM will only perform static initialization of a class once, so stubbing out the initialization code
    * can have unexpected consequences.
    * Static initialization will occur the first time the class is instantiated, has a static method called on it, or
    * has a static field whose value is defined at runtime accessed; these are the only events which prompt the JVM to
    * initialize a class.
    * If the original class initialization code was stubbed out, then it will not be there to be executed at the time of
    * static initialization, potentially leaving static fields {@code null} and later causing
    * {@code NullPointerException}'s to occur.
    */
   boolean stubOutClassInitialization() default false;
}