mockit.Mocked Maven / Gradle / Ivy

/*
 * Copyright (c) 2006 JMockit developers
 * This file is subject to the terms of the MIT license (see LICENSE.txt).
 */
package mockit;

import java.lang.annotation.*;
import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.*;

/**
 * Indicates an instance field of a test class as being a mock field, or a parameter of a test method as a mock parameter;
 * in either case, the declared type of the field/parameter is a mocked type, whose instances are mocked instances.
 * 
 * Mocked types can also be introduced by other annotations: {@linkplain Injectable @Injectable}, {@link Capturing @Capturing}.
 * Their effect is to constrain or extend the mocking capabilities here specified.
 * 

 * 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 Expectations recording} and/or {@linkplain Verifications verifying} expectations.
 * For a mock field, the test itself can provide the instance by declaring the field as final and assigning it the desired
 * instance (or null).
 * 

 * The effect of declaring a @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.
 * All non-private methods of the mocked type will be mocked.
 * 

 * When the mocked type is a class, all super-classes up to but not including java.lang.Object are also mocked.
 * Additionally, static methods and constructors are mocked as well, just like instance methods;
 * native methods are also mocked, provided they are public or protected.
 * 

 * 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 {@linkplain Expectations#result result} (or with a
 * {@linkplain Expectations#times constraint} violation, if the invocation is deemed to be unexpected).
 * 
 * Mocking will automatically cascade into the return types of all non-void methods belonging to the mocked type,
 * except for non-eligible ones (primitive wrappers, String, and collections/maps).
 * When needed, such cascaded returns can be overridden by explicitly recording a return value for the mocked method.
 * If there is a mock field/parameter with the same type (or a subtype) of some cascaded type, then the original instance from that mock
 * field/parameter will be used as the cascaded instance, rather than a new one being created;
 * this applies to all cascading levels, and even to the type of the mock field/parameter itself (ie, if a method in class/interface
 * "A" has return type A, then it will return itself by default).
 * Finally, when new cascaded instances are created, {@linkplain Injectable @Injectable} semantics apply.
 *
 * @see Tutorial
 */
@Retention(RUNTIME)
@Target({FIELD, PARAMETER})
public @interface Mocked {}