Method Detail

• 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

• 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, similarly to setUpMocks(Object...). The difference is in the lifetime of the mocks, which will last to the end of the current test suite execution. 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 JMockit to apply one or more of the mock classes at startup.

  There are two mechanisms that allow specifying mock classes to be loaded at JMockit startup time:

  1. Using the "-javaagent:jmockit.jar=<agentArgs>" JVM argument, where "agentArgs" contains one or more mock class names (separated by semicolons if more than one).
  2. Using a customized "jmockit.properties" file, which must precede the standard file located inside jmockit.jar (see comments in that file for more details).

  Note that if you pass all desired mock classes to JMockit at startup using one of these two mechanisms, this method won't be used. However, it's also possible to pass only one of those mock classes to JMockit and then call this method in the no-args constructor of the chosen mock class, to cause the remaining mock classes to be applied.

  Note also that it's possible to package a whole set of mock classes in a jar file containing a jmockit.properties file and then, by simply adding the jar to the classpath before jmockit.jar, to have it loaded and applied automatically for any test suite execution, as soon as JMockit itself is initialized.

  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:

  Example

• 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

• 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

• 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