Overview  Package   Class		JMockit Home
PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

mockit
Class Mockit

java.lang.Object
  mockit.Mockit

public final class Mockit
extends Object

Provides static methods for the mocking and stubbing of arbitrary classes, according to specified mock classes defined in test code. Such methods are intended to be called from test code only.

Once mocked, a "real" method defined in a production class will behave (during test execution) as if its implementation was replaced by a call to the corresponding mock method in the mock class. Whatever value this mock method returns will be the value returned by the call to the mocked method. The mock method can also throw an exception or error, which will then be propagated to the caller of the mocked "real" method. Therefore, while mocked the original code in the real method is never executed (actually, there's still a way to execute the real implementation, although not normally used for testing purposes). The same basic rules apply to constructors, which can be mocked by mock methods with the special name "$init".

The methods in this class can be divided in the following groups:

• Stubbing API: stubOut(Class...), stubOutClass(Class, String...), and stubOutClass(Class, boolean, String...).
• Mockups API for state-oriented mocking: MockUp, setUpMocks(Object...), setUpMock(Class, Class) and its several overloads, setUpStartupMocks(Object...), setUpMocksAndStubs(Class...), and tearDownMocks(Class...) / tearDownMocks().
• Proxy-based utilities: newEmptyProxy(ClassLoader, Class) and its overloads. These are merely convenience methods that create empty implementation classes for one or more interfaces, where all implemented methods do nothing beyond returning a default value according to the return type of each interface method. The created classes can be mocked through the Mockups API, and its instances passed to code under test.

newEmptyProxy

public static <E> E newEmptyProxy(Class<E> interfaceToBeProxied)

Same as newEmptyProxy(ClassLoader, Class), but with the class loader obtained from the interface to be proxied. Note that this may lead to a NoClassDefFoundError if that interface was loaded by the boot class loader (usually, when it's a JRE class). Therefore, you should only use this method for application-defined interfaces.

This method is just a convenience for some uses of the Mockups API. In JMockit Expectations in particular, mocked instances will be automatically created and assigned to any mock fields or parameters.

See Also:

Example

newEmptyProxy

public static <E> E newEmptyProxy(ClassLoader loader,
                                  Class<E> interfaceToBeProxied)

Creates a Proxy implementation for a given interface, in which all methods are empty. Non-void methods will return a default value according to the return type: 0 for int, null for a reference type, and so on.

The equals, hashCode, and toString methods inherited from java.lang.Object are overridden with an appropriate implementation in each case: equals is implemented by comparing the two object references (the proxy instance and the method argument) for equality; hashCode is implemented to return the identity hash code for the proxy instance; and toString returns the standard string representation that Object#toString would have returned.

This method is just a convenience for some uses of the Mockups API. In JMockit Expectations in particular, mocked instances will be automatically created and assigned to any mock fields or parameters.

Parameters:

loader - the class loader under which to define the proxy class; usually this would be the application class loader, which can be obtained from any application class

interfaceToBeProxied - a Class object for an interface

Returns:

the created proxy instance

See Also:

newEmptyProxy(Class), newEmptyProxy(Type...), Example

newEmptyProxy

public static <E> E newEmptyProxy(Type... interfacesToBeProxied)

Creates a Proxy implementation for a given set of interface types. In this created class all methods will be empty, with return values for non-void methods being the appropriate default value (0 for int, null for a reference type, and so on).

The equals, hashCode, and toString methods inherited from java.lang.Object are overridden with an appropriate implementation in each case: equals is implemented by comparing the two object references (the proxy instance and the method argument) for equality; hashCode is implemented to return the identity hash code for the proxy instance; and toString returns the standard string representation that Object#toString would have returned.

This method is just a convenience for some uses of the Mockups API. In JMockit Expectations in particular, mocked instances will be automatically created and assigned to any mock fields or parameters.

Parameters:

interfacesToBeProxied - one or more Type objects, each of which can be a Class object for an interface, a ParameterizedType whose raw type is an interface, or a TypeVariable whose bounds are interfaces

Returns:

the created proxy instance

setUpMock

public static void setUpMock(Class<?> realClass,
                             Class<?> mockClass)

Similar to setUpMocks(Object...), but accepting a single mock class and its corresponding real class.

Can also be useful when the real class is not known in advance, such as when it is determined at runtime through configuration or by creating a Proxy for an interface.

Parameters:

realClass - the class to be mocked that is used by code under test

mockClass - the class containing the mock methods for the real class

See Also:

Example

setUpMock

public static void setUpMock(Class<?> realClass,
                             Object mock)

Similar to setUpMocks(Object...), but accepting a single mock and its corresponding real class.

Useful when the real class is not known in advance, such as when it is determined at runtime through configuration of by creating a Proxy for an interface.

Parameters:

realClass - the class to be mocked that is used by code under test

mock - an instance of the class containing the mock methods for the real class

See Also:

Example

setUpMock

public static <T> T setUpMock(Object mockClassOrInstance)

Sets up the mocks defined in the given mock class.

If the type referred to by the mock class is actually an interface, then a new empty proxy is created.

Parameters:

mockClassOrInstance - the mock class itself (given by its Class literal), or an instance of the mock class

Returns:

the new proxy instance created for the mocked interface, or null otherwise

Throws:

IllegalArgumentException - if a given mock class fails to specify the corresponding real class using the @MockClass(realClass = ...) annotation; or if a mock class defines a mock method for which no corresponding real method or constructor exists in the real class; or if the real method matching a mock method is abstract

See Also:

setUpMock(Class, Object), setUpMocks(Object...), Example

setUpMock

public static void setUpMock(String realClassName,
                             Class<?> mockClass)

Same as setUpMock(Class, Class), but accepting the (fully qualified) name of the real class. This is useful when said class is not accessible from the test.

See Also:

Example

setUpMock

public static void setUpMock(String realClassName,
                             Object mock)

Same as setUpMock(Class, Object), but accepting the (fully qualified) name of the real class. This is useful when said class is not accessible from the test.

setUpMocks

public static void setUpMocks(Object... mockClassesOrInstances)

Sets up the mocks defined in one or more mock classes.

After this call, all such mocks are "in effect" until the end of the test method inside which it appears, if this is the case. If the method is a "before"/"setUp" method which executes before all test methods, then the mocks will remain in effect until the end of the test (including any "after"/"tearDown" methods).

Any invocation count constraints specified on mock methods (such as @Mock(invocations = 1), for example) will be automatically verified after the code under test is executed.

For each call made during test execution to a mocked method, the corresponding mock method is called instead. A mock method must have the same signature (ie, name and parameters) as the corresponding mocked/real method. The return type of the mock method must be the same exact type or a compatible one. The throws clause may differ in any way. Note also that the mock method can be static or not, independently of the real method being static or not.

A constructor in the real class can be mocked by a corresponding mock method of name $init, declared with the same parameters and with void return type. It will be called for each new instance of the real class that is created through a call to that constructor, with whatever arguments are passed to it.

Class initializers of the real class (one or more static initialization blocks plus all assignments to static fields) can be mocked by providing a mock method named $clinit in the mock class. This method should return void and have no declared parameters. It will be called at most once, at the time the real class is initialized by the JVM (and since all static initializers for that class are mocked, the initialization will have no effect).

Mock methods can gain access to the instance of the real class on which the corresponding real method or constructor was called. This requires the mock class to define an instance field of name "it", the same type as the real class, and accessible from that class (in general, this means the field will have to be public). Such a field will always be set to the appropriate real class instance, whenever a mock method is called. Note that through this field the mock class will be able to call any accessible instance method on the real class, including the real method corresponding to the current mock method. In this case, however, such calls are not allowed by default because they lead to infinite recursion, with the mock calling itself indirectly through the redefined real method. If the real method needs to be called from the mock method, then the latter must be declared as reentrant.

Parameters:

mockClassesOrInstances - one or more classes (Class objects) or instances of classes which define arbitrary methods and/or constructors, where the ones annotated as mocks will be used to redefine corresponding real methods/constructors in a designated real class (usually, a class on which the code under test depends on)

Throws:

IllegalArgumentException - if a given mock class fails to specify the corresponding real class using the @MockClass(realClass = ...) annotation; or if a mock class defines a mock method for which no corresponding real method or constructor exists in the real class; or if the real method matching a mock method is abstract

See Also:

tearDownMocks(Class[]), Example

In the Tutorial: Using the @MockClass annotation

setUpMocksAndStubs

public static void setUpMocksAndStubs(Class<?>... mockAndRealClasses)

Given a mix of mock and real classes, sets up each mock class for the associated real class, and stubs out each specified regular class.

Parameters:

mockAndRealClasses - one or more mock classes and/or regular classes to be stubbed out

setUpStartupMocks

public static void setUpStartupMocks(Object... mockClassesOrInstances)

Sets up the startup mocks defined in one or more mock classes, just like setUpMocks(Object...) does for regular mock classes. The difference is in the lifetime of the mocks, which will last to the end of the test run. Consequently, this method should only be called once, before the first test begins execution. One way to achieve this is to put the call in the static initializer of a common base class extended by all test classes in the suite. Another way is by configuring what happens at startup through external means.

There are three ways to set up mock classes at startup time:

1. Define a value for the "jmockit-mocks" system property, as a comma-separated list of fully qualified class names.
2. Add a custom "jmockit.properties" file to the classpath, with an entry for the "jmockit-mocks" (or just "mocks") property.
3. Specify the "-javaagent:jmockit.jar=<agentArgs>" JVM argument, with "agentArgs" containing one or more mock class names, separated by semicolons if more than one.

Note that option two above makes it possible to package a whole set of reusable mock classes in a jar file, provided it contains a suitable jmockit.properties file. By simply adding the jar to the classpath before jmockit.jar, the specified mock classes will be loaded and applied automatically on every test run, as soon as JMockit itself gets initialized.

Parameters:

mockClassesOrInstances - one or more mock classes (either Class literals or fully qualified class names) or instances of mock classes

Throws:

IllegalArgumentException - if a given mock class fails to specify the corresponding real class using the @MockClass(realClass = ...) annotation; or if a mock class defines a mock method for which no corresponding real method or constructor exists in the real class; or if the real method matching a mock method is abstract

See Also:

Example

In the Tutorial: Using mocks and stubs over entire test classes and suites

stubOut

public static void stubOut(Class<?>... realClasses)

Stubs out all methods, constructors, and static initializers in the given classes, so that they do nothing whenever executed.

Note that any stubbed out constructor will still call a constructor in the super-class, which in turn will be executed normally unless also stubbed out. The super-constructor to be called is chosen arbitrarily. The classes are stubbed out in the order they are given, so make sure any super-class comes first.

Methods with non-void return type will return the default value for this type, that is, zero for a number or char, false for a boolean, empty for an array, or null for a reference type.

If a different behavior is desired for any method or constructor, then setUpMocks(Object...) and the other similar methods can be used right after the call to this method. They will override any stub previously created with the corresponding mock implementation, if any.

Parameters:

realClasses - one or more regular classes to be stubbed out

See Also:

Example

In the Tutorial: Using the stubbing methods

stubOutClass

public static void stubOutClass(Class<?> realClass,
                                boolean inverse,
                                String... filters)

The same as stubOutClass(Class, String...), but specifying whether filters are to be inverted or not.

Parameters:

inverse - indicates whether the mock filters are to be inverted or not; if inverted, only the methods and constructors matching them are not mocked

stubOutClass

public static void stubOutClass(Class<?> realClass,
                                String... filters)

Same as stubOut(Class...) for the given class, except that only the specified class members (if any) are stubbed out, leaving the rest unaffected. Such class members include the methods and constructors defined by the class, plus any static or instance initialization blocks it might have. Note that if no filters are specified the whole class will be stubbed out.

For methods, the filters are regular expressions for method names, optionally followed by parameter type names between parentheses. For constructors, only the parameters are specified. For more details about the syntax for mock filters, see the MockClass.stubs() annotation attribute.

The special filter "<clinit>" will match all static initializers in the given class.

To stub out instance field initializers it is necessary to actually specify all constructors in the class, because such initialization assignments are copied to each and every constructor by the Java compiler.

Parameters:

realClass - a regular class to be stubbed out

filters - one or more filters that specify which class members (methods, constructors, and/or static initialization blocks) to be stubbed out

See Also:

Example

In the Tutorial: Using the stubbing methods

stubOutClass

public static void stubOutClass(String realClassName,
                                boolean inverse,
                                String... filters)

Same as stubOutClass(Class, boolean, String...), but accepting the (fully qualified) name of the real class. This is useful when said class is not accessible from the test.

stubOutClass

public static void stubOutClass(String realClassName,
                                String... filters)

Same as stubOutClass(Class, String...), but accepting the (fully qualified) name of the real class. This is useful when said class is not accessible from the test.

tearDownMocks

public static void tearDownMocks()

Discards any mocks currently in effect, for all test scopes: the current test method (if any), the current test (which starts with the first "before" method and continues until the last "after" method), the current test class (which includes all code from the first "before class" method to the last "after class" method), and the current test suite.

Notice that a call to this method will tear down all mock classes that were applied through use of the Mockups API that are still in effect, as well as any mock classes or stubs applied to the current test class through @UsingMocksAndStubs. In other words, it would effectively prevent mocks to be set up at the test class and test suite levels. So, use it only if necessary and if it won't discard mock classes that should remain in effect. Consider using tearDownMocks(Class...) instead, which lets you restrict the set of real classes to be restored.

JMockit will automatically restore classes mocked by a test at the end of its execution, as well as all classes mocked for the test class as a whole (through a "before class" method or an @UsingMocksAndStubs annotation) before the first test in the next test class is executed.

See Also:

Example

tearDownMocks

public static void tearDownMocks(Class<?>... realClasses)

Discards any mocks set up for the specified classes that are currently in effect, for all test scopes: the current test method (if any), the current test (which starts with the first "before" method and continues until the last "after" method), the current test class (which includes all code from the first "before class" method to the last "after class" method), and the current test suite.

Notice that if one of the given real classes has a mock class applied at the level of the test class, calling this method would negate the application of that mock class. JMockit will automatically restore classes mocked by a test at the end of its execution, as well as all classes mocked for the test class as a whole (through a "before class" method or an @UsingMocksAndStubs annotation) before the first test in the next test class is executed.

Parameters:

realClasses - one or more real classes from production code, which may have mocked methods

Overview  Package   Class		JMockit Home
PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD