January 09, 2015

Mocking System static void methods..config for Maven, JUnit, PowerMock, PowerMockito, and Mockito

Abstract
I previously wrote about Mocking return values of static methods..config for Maven, JUnit, PowerMock, EasyMock, and Mockito. The previous article focused on the need to mock a static method which returns a value. This article is also about mocking static methods, but static void methods - methods that return no value. Why would you need to mock such a method? Well my unit test needs to verify that a static void method was being called.  Specifically I wanted to Mockito.times(1) verify my application was calling the following System static void method on the Thread class: 

Thread.setDefaultUncaughtExceptionHandler(eh); 
My application's proper error handling depends on setting a default exception handler so it makes sense to have a unit test for it. Performing a Mockito.times(1) verify testing for this System static void method call however, has a number of challenges, including:
  1. It's a static method
  2. It's a static void method meaning it does not return a value
  3. It's a JVM System class
The purpose of this article is to show a simple JUnit code example to verify a call to a JVM System static void method such as Thread.setDefaultUncaughtExceptionHandler(eh).

System Requirements
This example was developed and run using the following system setup. If yours is different, it may work but no guarantees.
  • JDK 1.7.0_11
  • Eclipse Luna
  • Maven 3.2.1 (Embedded with Eclipse)
The rest of the software dependencies can be found in this article.

Maven POM dependencies
Listing 1 shows the Maven POM dependencies needed to run the unit test listed below.  From my research, these are the only dependencies you need.  

WARNING: If you do have JUnit or Mockito as direct dependencies, most likely you'll get at version mismatch and the unit tests will fail to run. They are pulled in as transitive dependencies of what's in Listing 1. 
Listing 1: Maven POM dependencies
<dependency>
    <groupId>org.powermock</groupId>
    <artifactId>powermock-module-junit4</artifactId>
    <version>1.5.6</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.powermock</groupId>
    <artifactId>powermock-api-easymock</artifactId>
    <version>1.5.6</version>
    <scope>test</scope>
</dependency>       
<dependency>
    <groupId>org.powermock</groupId>
    <artifactId>powermock-api-mockito</artifactId>
    <version>1.5.6</version>
    <scope>test</scope>
</dependency>        
<dependency>
    <groupId>org.easymock</groupId>
    <artifactId>easymock</artifactId>
    <version>3.2</version>
    <scope>test</scope>
</dependency>

Class Using a System static void method
Listing 2 shows a wrapper class which wraps the call to the System static void method Thread.setDefaultUncaughtExceptionHandler(eh). The reason for the wrapper class is described in the Mockito documentation which states such a wrapper class is required "If you need to mock classes loaded by the java system/bootstrap classloader (those defined in the java.lang or java.net etc)." I called my wrapper class ThreadTools.

Listing 2: Java ThreadTools wrapper class
/**
 * @author Michael Remijan mjremijan@yahoo.com @mjremijan
 */
public class ThreadTools {
  public void setUncaughtExceptionHandler(UncaughtExceptionHandler handler) {
    Thread.setDefaultUncaughtExceptionHandler(handler);
  }
} 

As you can see, ThreadTools is very simple. It doesn't add any overhead to your application to use this wrapper class and it is essential for the unit test to work properly. Now that we have a class to test, let's next take a look at what the unit test looks like.

Verifying a static void method in a unit test 
The goal of the unit test is to verify the System static void method Thread.setDefaultUncaughtExceptionHandler(eh)is actually called. In the Mockito world, verifing that a method has been called with certain parameter values is usually accomplished with code that looks like:

Mockito.verify(mockedObject, Mockito.times(1)).someMethod("param");

The above statement is used to verify that someMethod was called on the mockedObject only times(1) with exactly the "param" value passed to the method. We want to do something similary, only with a JVM System static void method, which makes it a little bit harder.
  
Listing 3 shows the Java source code for a very simple unit test which does exactly this. For this unit test you are going to be using a combination of PowerMockRunner, PowerMockito, and Mockito. Let's step through this unit test line by line.

NOTE: You'll be using PowerMockRunner, PowerMockito, and Mockito all at the same time, for sanity's sake, avoid using static imports! Static imports are a great convenience, but when mixing so many different technologies it get very hard to keep straight which methods are coming from which classes.

Listing 3: Java ThreadToolsTest class
import java.lang.Thread.UncaughtExceptionHandler;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.mockito.Mockito;
import org.powermock.api.mockito.PowerMockito;
import org.powermock.core.classloader.annotations.PrepareForTest;
import org.powermock.modules.junit4.PowerMockRunner;

@RunWith(PowerMockRunner.class)
@PrepareForTest(ThreadTools.class) 
public class ThreadToolsTest {
  @Test
  public void testSetDefaultUncaughtExceptionHandleIsCalled() throws Exception {
    // Prepare
    PowerMockito.mockStatic(Thread.class);

    // Mock
    UncaughtExceptionHandler handler
      = Mockito.mock(UncaughtExceptionHandler.class);
    
    // Test
    new ThreadTools().setUncaughtExceptionHandler(handler);
    
    // Verify
    PowerMockito.verifyStatic(Mockito.times(1));
    Thread.setDefaultUncaughtExceptionHandler(handler);
  }
}

Let's take a look at this code in a bit more detail.

#9 @RunWith
We need to run the test with the PowerMockRunner, not the normal JUnit runner.

#10 @PrepareForTest
We need to prepare the wrapper class that uses the System static void method. This is important and easy to get confused. Do not prepare the System class, which in this example is Thread.class. You must prepare the wrapper class which is ThreadTools.class. To make the test easy, we created a wrapper class specifically for calling Thread.setDefaultUncaughtExceptionHandler(eh). In general, the class you must @PrepareForTest must be whatever class is making the System static void method call.

#12 PowerMockito.mockStatic(Thread.class)
Use PowerMockito to prepare the Thread.class for mocking.  Unlike normal mocking, this does not return a mock object, it just prepares Thread.class for mocking in the PowerMockito framework.

#18 Mockito.mock(UncaughtExceptionHandler.class)
This is a normal mock of the UncaughtExceptionHandler interface. Ultimately this mock should be passed to Thread.setUncaughtExceptionHander(eh) and  the goal of the unit test is to verify this has happened.

#22 new ThreadTools().setUncaughtExceptionHandler(handler)
This will now perform the test.  An instance of our wrapper class ThreadTools is created and its setUncaughtExceptionHandler(eh) method is called.  This in turn will call a "mocked" Thread.class.  After this test is performed, we should be able to verify the "mocked" Thread.class did get called.  We'll see this in the next lines.

#25 PowerMockito.verifyStatic(Mockito.times(1));
This tells the PowerMockito framework that it needs to verify that the class it statically mocked on line #15 (Thread.class) had a static void method called only 1 time.  But which method?  Look at the next like of code.

#26 Thread.setDefaultUncaughtExceptionHandler(handler);
The previously like, line #25 told PowerMockito to verify the static void method was called only 1 time. This line tells PowerMockito which method, which is setDefaultUncaughtExceptionHandler(eh).  Not only that, but it also tells PowerMockito that the parameter passed that to method should have been the handler object which is the mock of UncaughtExceptionHandler we create on line #18.

Conclusion
Mocking statics is not trivial, and mocking System static void method is even more tricky.  But PowerMockRunner, PowerMockito, and Mockito are powerful tools which make it possible. Put it all together with Maven and you have a good system to verifying your code base.

References
Using PowerMock with Mockito. (n.d.). code.google.com. Retrieved January 2015, from https://code.google.com/p/powermock/wiki/MockitoUsage13

Mocking system classes. (n.d.). code.google.com. Retrieved January 2015, from https://code.google.com/p/powermock/wiki/MockSystem

Class Mockito. (n.d.). docs.mockito.googlecode.com. Retrieved January 2015, from http://docs.mockito.googlecode.com/hg/org/mockito/Mockito.html#1

fatmind. (2014 May 4). powermock example. github.com. Retrieved January 2015, from https://gist.github.com/fatmind/4110984
Enjoy!