JMockit 101

1. Introduction

With this article, we’ll be starting a new series centered around the mocking toolkit JMockit.

In this first installment, we’ll talk about what JMockit is, its characteristics, and how mocks are created and used with it.

Later articles will focus on and go deeper into its capabilities.

2. JMockit

First of all, let’s talk about what JMockit is: a Java framework for mocking objects in tests (you can use it for both JUnit and TestNG ones).

It uses Java’s instrumentation APIs to modify the classes’ bytecode during runtime in order to dynamically alter their behavior. Some of its strong points are its expressibility and its out-of-the-box ability to mock static methods.

Maybe you’re new to JMockit, but it’s definitely not due to it being new. JMockit’s development started in June 2006 and its first stable release dates to December 2012, so it’s been around for a time now (the current version is 1.24 at the time of writing the article).

2.1. Maven Dependency

First, we’ll need to add the jmockit dependency to our project:

<dependency> 
    <groupId>org.jmockit</groupId> 
    <artifactId>jmockit</artifactId> 
    <version>1.49</version>
</dependency>

2.2. The Expressibility of JMockit

As told before, one of the strongest points of JMockit is its expressibility. In order to create mocks and define their behavior, instead of calling methods from the mocking API, we just need to define them directly.

This means that we won’t do things like:

API.expect(mockInstance.method()).andThenReturn(value).times(2);

Instead, expect things like:

new Expectation() {
    mockInstance.method(); 
    result = value; 
    times = 2;
}

It might seem that it is more code, but we could simply put all three lines just on one. The really important part is that we don’t end up with a big “train” of chained method calls. Instead, we end up with a definition of how we want the mock to behave when called.

If we take into account that on the result = value part we could return anything (fixed values, dynamically generated values, exceptions, etc), the expressiveness of JMockit gets even more evident.

2.3. The Record-Replay-Verify Model

Tests using JMockit are divided into three differentiated stages: record, replay, and verify.

1. In the record phase, during test preparation and before the invocations to the methods we want to be executed, we will define the expected behavior for all tests to be used during the next stage.
2. The replay phase is the one in which the code under test is executed. The invocations of mocked methods/constructors previously recorded in the previous stage will now be replayed.
3. Lastly, in the verify phase, we will assert that the result of the test was the one we expected (and that mocks behaved and were used according to what was defined in the record phase).

With a code example, a wireframe for a test would look something like this:

@Test
public void testWireframe() {
   // preparation code not specific to JMockit, if any

   new Expectations() {{ 
       // define expected behaviour for mocks
   }};

   // execute code-under-test

   new Verifications() {{ 
       // verify mocks
   }};

   // assertions
}

3. Creating Mocks

3.1. JMockit’s Annotations

When using JMockit, the easiest way to use mocks, is to use annotations. There are three for creating mocks (@Mocked, @Injectable, and @Capturing) and one to specify the class under testing (@Tested).

When using the @Mocked annotation on a field, it will create mocked instances of each and every new object of that particular class.

On the other hand, with the @Injectable annotation, only one mocked instance will be created.

The last annotation, @Capturing will behave like @Mocked but will extend its reach to every subclass extending or implementing the annotated field’s type.

3.2. Passing Arguments to Tests

When using JMockit is possible to pass mocks as test parameters. This is quite useful for creating a mock just for that one test in particular, like some complex model object that needs a specific behavior just for one test for instance. It would be something like this:

public class TestPassingArguments {
   
   @Injectable
   private Foo mockForEveryTest;

   @Tested
   private Bar bar;

   @Test
   public void testExample(@Mocked Xyz mockForJustThisTest) {
       new Expectations() {{
           mockForEveryTest.someMethod("foo");
           mockForJustThisTest.someOtherMethod();
       }};

       bar.codeUnderTest();
   }
}

This way of creating a mock by passing it as a parameter, instead of having to call some API method, again shows us the expressibility we’re talking about since the beginning.

3.3. Complete Example

To end this article, we’ll be including a complete example of a test using JMockit.

In this example, we’ll be testing a Performer class that uses Collaborator in its perform() method. This perform() method, receives a Model object as a parameter from which it will use its getInfo() that returns a String, this String will be passed to the collaborate() method from Collaborator that will return true for this particular test, and this value will be passed to the receive() method from Collaborator.

So, the tested classes will look like this:

public class Model {
    public String getInfo(){
        return "info";
    }
}

public class Collaborator {
    public boolean collaborate(String string){
        return false;
    }
    public void receive(boolean bool){
        // NOOP
    }
}

public class Performer {
    private Collaborator collaborator;
	
    public void perform(Model model) {
        boolean value = collaborator.collaborate(model.getInfo());
        collaborator.receive(value);
    }
}

And the test’s code will end up being like this:

public class PerformerTest {

    @Injectable
    private Collaborator collaborator;

    @Tested
    private Performer performer;

    @Test
    public void testThePerformMethod(@Mocked Model model) {
        new Expectations() {{
    	    model.getInfo();result = "bar";
    	    collaborator.collaborate("bar"); result = true;
        }};
        
        performer.perform(model);
        
        new Verifications() {{
    	    collaborator.receive(true);
        }};
    }
}

4. Conclusion

With this, we’ll wrap up our practical intro to JMockit. If you want to learn more about JMockit, stay tuned for future articles.

4.1. Articles in the Series

All articles of the series:

• JMockit 101
• A Guide to JMockit – Expectations
• JMockit Advanced Usage