Example

Let's say we have a (very stupid) Spring bean like this:

 
@Component
public class MyBean {
 
    @Autowired
    private CompanyRepository companyRepository;
 
    public Message generateMessage() throws SAXException {
        final String[] allEmployees = companyRepository.getAllEmployees();
        final String message = StringUtils.join(allEmployees, ", ");
 
        final long id = IdGenerator.generateNewId();
        return new Message(id, message);
    }
}
 

and for demonstration we'd like to mock the static method call to IdGenerator.generateNewId(). Let's write a simple test bootstrapped by Spring using the classloader version of PowerMockRule:

 
@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration("classpath:/example-context.xml")
@PrepareForTest(IdGenerator.class)
public class SpringExampleTest {
 
    @Rule
    public PowerMockRule rule = new PowerMockRule();
 
    @Autowired
    private MyBean myBean;
 
    @Test
    public void mockStaticMethod() throws Exception {
        // Given
        final long expectedId = 2L;
        mockStatic(IdGenerator.class);
        when(IdGenerator.generateNewId()).thenReturn(expectedId);
 
        // When
        final Message message = myBean.generateMessage();
 
        // Then
        assertEquals(expectedId, message.getId());
        assertEquals("John Doe, Paul Anderson, Jane Doe", message.getContent());
    }
 

If you run this test you'll get the following error:

 
java.lang.RuntimeException: java.lang.ClassCastException: com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl cannot be cast to javax.xml.parsers.DocumentBuilderFactory
	at powermock.examples.spring.CompanyRepository.getAllEmployees(CompanyRepository.java:42)
	at powermock.examples.spring.MyBean.generateMessage(MyBean.java:31)
	at org.powermock.examples.spring.mockito.SpringExampleTest.mockStaticMethod(SpringExampleTest.java:58)
...
 

The reason is that companyRepository.getAllEmployees() implementation called from MyBean bean above parses the employee list using Java's XML parsing (javax.xml.parsers.DocumentBuilderFactory). Thus we must use the PowerMockIgnore annotation to ignore the framework:

 
@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration("classpath:/example-context.xml")
@PrepareForTest(IdGenerator.class)
@PowerMockIgnore({"org.w3c.*", "javax.xml.*"})
public class SpringExampleTest {
 
    @Rule
    public PowerMockRule rule = new PowerMockRule();
 
    ....
    // Same code as in the previous example
 

Re-run the test and it'll now pass.

Introducing PowerMock Java Agent

To make it easier to use PowerMock for integration testing version 1.4.9 introduces yet another way to bootstrap the framework, this time using a java agent. Instead of using classloaders to bootstrap and perform byte-code manipulation we now use Java's instrumentation API. This means that you won't run into classloading issues as those presented in the previous example. The test looks exactly the same though:

 
@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration("classpath:/example-context.xml")
@PrepareForTest(IdGenerator.class)
public class SpringExampleTest {
 
    @Rule
    public PowerMockRule rule = new PowerMockRule();
 
    @Autowired
    private MyBean myBean;
 
    @Test
    public void mockStaticMethod() throws Exception {
        // Given
        final long expectedId = 2L;
        mockStatic(IdGenerator.class);
        when(IdGenerator.generateNewId()).thenReturn(expectedId);
 
        // When
        final Message message = myBean.generateMessage();
 
        // Then
        assertEquals(expectedId, message.getId());
        assertEquals("John Doe, Paul Anderson, Jane Doe", message.getContent());
    }
 

Even though the test looks exactly the same the internal implementation has a lot of differences. To have a look at the real code behind the to examples have a look in subversion here for the first example and here for the java agent example.

Round-up

Using the Java agent can help you out when you run into hard-to-resolve classloading issues with PowerMock. The implementation is still experimental and we are aware of some bugs and limitations. To know more and find help getting started with the agent please have a look at the documentation.

Mocking final classes

Unlike EasyMock and Mockito, JMock doesn't support mocking classes out of the box. For this to work you need to have the jmock-legacy jar file in your classpath. But even if you have you cannot mock classes that are final:

 
public final class FinalClass {
 
    public String helloWorld() {
        return "Hello world";
    }
}
 

But here PowerMock can help. What you need to do is to use the PowerMock JUnit runner and to prepare the FinalClass for test:

 
@RunWith(PowerMockRunner.class)
@PrepareForTest(FinalClass.class)
 

But unfortunately this is not enough. For PowerMock to work it needs something called a "ProxyFrameworkImpl" that helps the reflection utilities in PowerMock to find an unproxied class type of a proxied class. It also needs an "AnnotationEnabler" that's used for injecting mocks. This may sound complicated but since JMock is using CGLib to create class proxies you can use PowerMock's EasyMock implementation of the "ProxyFrameworkImpl" and "AnnotationEnabler". This works because EasyMock is also using CGLib. Thus you need to put the powermock-api-easymock.jar in your class-path (note that you don't need the easymock.jar in the classpath).

Once we have the powermock-api-easymock.jar in the classpath and have added the two annotations we're ready to test the FinalClass. Here's a full example:

 
@RunWith(PowerMockRunner.class)
@PrepareForTest(FinalClass.class)
public class JMockFinalClassTest {
    private Mockery context = new JUnit4Mockery(){{
        setImposteriser(ClassImposteriser.INSTANCE);
    }};
 
    private FinalClass tested;
 
    @Before
    public void setup() throws Exception {
        tested = context.mock(FinalClass.class);
    }
 
    @Test
    public void mockFinalClassWithPowerMockAndJMock() throws Exception {
        // Given
        final String expected = "something";
        context.checking(new Expectations(){{
            one(tested).helloWorld();
            will(returnValue(expected));
        }});
 
        // When
        final String actual = tested.helloWorld();
 
        // Then
        assertEquals(expected, actual);
        context.assertIsSatisfied();
    }
}
 

Mocking Stubbing static methods

Now that we know how to mock final classes, how about static methods? The bad news is that you can't mock them. But the good news on the other hand is that PowerMock provides a MemberModification API that allows you to stub, suppress and replace methods. So to stub a static method regardless of the underlying mock framework you can do:

 
stub(method(ClassWithStaticMethod.class, "staticMethodName")).toReturn(someObject);
 

To demonstrate how this can be used with JMock imagine that we want to test the generateMessage method in this example:

 
public class JMockExample {
    private final FinalClass finalClass;
 
    public JMockExample(FinalClass finalClass) {
        this.finalClass = finalClass;
    }
 
    public String generateMessage() {
        return "Message is: "+ finalClass.helloWorld() + ClassWithStaticMethod.returnString();
    }
}
 

where FinalClass is the same as in the previous example and ClassWithStaticMethod looks like this:

 
public class ClassWithStaticMethod {
    public static String returnString() {
        return "a string";
    }
}
 

A full JMock test with PowerMock can look like this:

 
@RunWith(PowerMockRunner.class)
@PrepareForTest({FinalClass.class, ClassWithStaticMethod.class})
public class JMockStaticMethodTest {
    private Mockery context = new JUnit4Mockery(){{
        setImposteriser(ClassImposteriser.INSTANCE);
    }};
 
    private FinalClass finalClassMock;
    private JMockExample tested;
 
    @Before
    public void setup() throws Exception {
        finalClassMock = context.mock(FinalClass.class);
        tested = new JMockExample(finalClassMock);
    }
 
    @Test
    public void stubbingAndMockingWithPowerMockAndJMock() throws Exception {
        // Given
        context.checking(new Expectations(){{
            one(finalClassMock).helloWorld();
            will(returnValue("Hello "));
        }});
 
        // Stub the static method
        stub(method(ClassWithStaticMethod.class, "returnString")).toReturn("JMock");
 
        // When
        final String message = tested.generateMessage();
 
        // Then
        assertEquals("Message is: Hello JMock", message);
        context.assertIsSatisfied();
    }
}
 

You can check out the examples from our SVN repo.

Notes

JMock also provides its own JUnit runner called "JMock" that automatically calls context.assertIsSatisfied() after each test. Normally you can use PowerMock with other JUnit runners using the PowerMockRule but unfortunatley the JMock runner extends from a deprecated runner which doesn't support rules.

Conclusion

As you can see it's pretty simple to use some PowerMock basics even for unsupported frameworks as JMock. Of course it's possible to create full-blown support for JMock using PowerMock to enable e.g. new instance and static method mocking but until that day it's good to know that alternatives exist. If you're interested to know more about PowerMock please visit our webpage.

Naive example

Let's say we have a very simple Spring bean like this:

 
@Component
public class MyBean {
 
    public Message generateMessage() {
        final long id = IdGenerator.generateNewId();
        return new Message(id, "My bean message");
    }
}
 

and we want to test the generateMessage method in an integration test. In this test we assume that it's really important for us to mock the static call to IdGenerator.generateNewId(). But in order to run the test as a Spring integration test we need to use the SpringJUnit4ClassRunner which prevents us from using the PowerMockRunner. So by taking advantage of the PowerMockRule we can still benefit from PowerMock's functionality:

 
@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration("classpath:/example-context.xml")
@PrepareForTest(IdGenerator.class)
public class SpringExampleTest {
 
    @Rule
    public PowerMockRule rule = new PowerMockRule();
 
    @Autowired
    private MyBean myBean;
 
    @Test
    public void mockStaticMethod() throws Exception {
        // Given
        final long expectedId = 2L;
        mockStatic(IdGenerator.class);
        when(IdGenerator.generateNewId()).thenReturn(expectedId);
 
        // When
        final Message message = myBean.generateMessage();
 
        // Then
        assertEquals(expectedId, message.getId());
        assertEquals("My bean message", message.getContent());
    }
 

If you're used to PowerMock you can see that the only difference between this test and a standard PowerMock test is that we use the PowerMockRule instead of the PowerMockRunner. You can find the complete example in our SVN repo.

Limitations

For trivial tests like this the Objenesis deep-cloner works just as well as the X-Stream version but in more complex situations X-Stream is more robust. There may still be bugs lurking around and we're thankful for contributions. For example it's not possible to mock system classes using any of the implementations yet.

Conclusion

We'll continue to work on the Objenesis deep-cloner but until it's working better you can use the X-Stream version to combine PowerMock with frameworks that require a JUnit runner. Please refer to this page to get started with the rule.

In PowerMock we're using a custom classloader to byte-code manipulate classes that are normally not mockable to make them mockable. But when running a test case there may be some cases when the user needs to byte-code manipulate a certain class (X) in the first test method but needs to have the class unmodified in the second. For example you may want to remove the static initializer of class X in testA but in testB you want the static initializer intact. There's no standard way for a Java classloader to reload a class that has already been loaded so what to do? The solution is to execute that particular test method in a new classloader. Using this approach we can simply load X again and this time we won't modify it. In PowerMock we've also implemented a custom JUnit runner which allows us to execute certain test-methods in another classloader. Without going into too much detail the problem is that we need to execute some test methods in a new classloader as well as being able to supply and receive state between our classloaders. The end user shouldn't be aware that the unit test they're running is actually chunked up into several different JUnit test cases executed in many different classloaders.

Requirements

Our goal was to be able to execute any block of code in any given classloader without using any byte-code manipulation. We can't make any assumptions about the class such as it being serializable or having a default constructor. We also need the outcome of this code-block to be used by the original/invoking classloader.

Solution

The solution was to implement a ClassLoaderExecutor which takes a Runnable or Callable and executes this code-block in any classloader. In the case of Callable the result from the callable invocation is cloned back to the original classloader calling the method. Let's look at an example.

First we define the code-block to be executed in the other classloader:

 
public class MyCodeBlock implements Callable<MyResult>
	/*
         * All code inside this method will be executed in a different class-loader.
         */
	public MyResult call() throws Exception {
		OperationToExecute operationToExecute = new OperationToExecute();
		...
		return operationToExecute.execute();
	}
}
 

Then we simply execute this block using the ClassLoaderExecutor:

 
// Instantiate the classloader where the code-block should be executed.
ClassLoader myClassloader = new MyCustomClassLoader();
// Initialize the ClassLoaderExecutor with the classloader
ClassLoaderExecutor classLoaderExecutor = new ClassLoaderExecutor(myClassloader);
/*
 * Pass in the code-block to the ClassLoaderExecutor. The code inside
 * the call method will be executed in the "myClassloader"
 * and the result (MyResult) will be usable from the invoking
 * classloader (the one that called the execute method).
 */
MyResult result = classLoaderExecutor.execute(new MyCodeBlock());
...
 

How does it work?

The first thing that happens when execute is called is that almost the entire object graph of the code-block is deep-cloned into the target classloader (myClassloader in the example above). The objects that are not cloned are those whose classes reside in the rt.jar which are always loaded by the bootstrap classloader. These objects are (in the simple cases) only referred to by a cloned object. Since we cannot make any assumptions about the class structure or hierarchy we cannot simply do deep-cloning using standard Java serialization. Neither can we clone the objects using simple reflection because how do we know which constructor to invoke when instantiating the object using the target classloader? Essentially the trick is to instantiate the class without executing any constructor at all. When this is done we iterate over all fields and instantiate and copy their values recursively. But how can you instantiate a class without invoking a constructor? Unfortunately there's no standard way of doing this. In a modern Sun JVM you can use sun.reflect.ReflectionFactory but it's not guaranteed that other JVM's have implemented this class. To make it more compatible we make use of the excellent Objenesis framework whose sole purpose is to accommodate this across multiple JVM's from different vendors. When all state has been copied from the source to the target classloader using this approach the result of the callable operation (myResult in the example above) is cloned back from the target to the source classloader. This means that the result is directly usable from the source classloader after the execute method has finished.

Conclusion

This article has demonstrated one approach of executing a block of code in any given classloader using deep-cloning without serialization. There are many corner cases which we haven't dealt with here such as dealing with arrays, lists, enum, static final fields, object references etc that the ClassLoaderExecutor also supports. An alternative may be to use XStream as deep-cloner to serialize the object graph to XML and de-serialize it back to the target classloader but the approach suggested here should potentially be faster.

So how do you configure PowerMock to use TestNG? First of all follow the instructions on the getting started page which states everything you need to know to get started with or without Maven. The trick is then to specify the PowerMock object factory in the TestNG suite.xml. An example can be seen here:

Without specifying this object factory the test will never be bootstrapped properly by PowerMock and thus will fail if any PowerMock functionality is used in the test.

Example

Now that we know how to bootstrap PowerMock and TestNG what does a test look like? If you're used to PowerMock there will be no surprises. As usually you have to prepare the class that is normally not testable/mockable for test using the @PrepareForTest annotation. Consider that we have a class like this:

public class ClassUnderTest {
	public void methodToTest() {
	   ..
	   final long id = IdGenerator.generateNewId();
	   ..
	}
}

When testing this class we might want to mock the static call to the IdGenerator. The full test will look like this using the Mockito extension API:

@PrepareForTest(IdGenerator.class)
public class MyTestClass {
    @Test
    public void demoStaticMethodMockingUsingTestNGAndMockito() throws Exception {
        mockStatic(IdGenerator.class);

        when(IdGenerator.generateNewId()).thenReturn(2L);               

        new ClassUnderTest().methodToTest();

        // Optionally verify that the static method was actually called
        verifyStatic();
        IdGenerator.generateNewId();
    }
}

Using the EasyMock API extension the test could look like this:

@PrepareForTest(IdGenerator.class)
public class MyTestClass {
    @Test
    public void demoStaticMethodMockingUsingTestNGAndEasyMock() throws Exception {
        mockStatic(IdGenerator.class);

        expect(IdGenerator.generateNewId()).andReturn(2L);

	replayAll();

        new ClassUnderTest().methodToTest();

        verifyAll();
    }
}

Advanced

Under the hood the PowerMock object factory also creates a proxy around the test class. This proxy adds support for creating and injecting mocks using the @Mock annotation and clears state created by PowerMock between each test. This means that you can create and inject mocks to your test like this:

@PrepareForTest(MyFinalClassExample.class)
public class MockInjectionTest {

    @Mock
    private MyFinalClassExample myExampleMock;

    @Test
    public void demoMockInjection() throws Exception {
	..
	expect(myExampleMock.myExample()).andReturn(8);
	..
    }
}

This works for both the EasyMock and Mockito API extensions. If you for some reason doesn't like that your test class is proxied you can manually extend the org.powermock.modules.testng.PowerMockTestCase to get the same functionality.

Round up

There's still much work to be done with the TestNG object factory such as getting better support for scoped injections and getting PowerMock test listeners in place. If you'd like to contribute in any way just drop us a note using the mailing list. Last but not least we would like to thank Dan Fabulich of the TestNG team for all the help making this possible.

 
public class Greeter {
	public static String getGreeting(String name) {
		return "Greetings " + string;
	}
}
 

And the test:

 
@RunWith(PowerMockRunner.class)
@PrepareForTest( Greeter.class )
public class MockStaticExampleTest {
	@Test
	public void mockStaticExample() throws Exception {
		String expectedGreeting = "greeting";
		String nameToGreet = "name";
 
		mockStatic(Greeter.class);
		expect(Greeting.getGreeting(nameToGreet)).andReturn(expectedGreeting);
		replayAll();
 
		String actualGreeting = Greeter.getGreeting(nameToGreet);
 
		verifyAll();
		assertEquals("Expected and actual greeting did not match",
                                  expectedGreeting, actualGreeting);
	}
}
 

The "power" behind PowerMock lies in its ability to modify the byte-code of the classes specified in the PrepareForTest annotation to make them testable. But because of restrictions enforced by the Java run-time PowerMock is simply not allowed to byte-code manipulate certain classes dynamically. These classes are those that are loaded by Java's bootstrap class-loader such as for example java.net.URLEncoder, java.lang.System and other "system classes" located in the java.lang or java.net package etc. While is this generally not a problem it may be so if you need to mock static methods in these classes because PowerMock cannot prepare them for test. So how do we get around this problem?

How does PowerMock work?

To start of with we probably should describe how PowerMock actually works under hood. What happens when PowerMock makes a class testable is that the byte-code is changed so that each method call, constructor call, field call etc are first routed to something that we refer to as the MockGateway. Simply put the MockGateway decides if it's OK for the call to be delegated to the original method/constructor/field or if a mock object should be returned instead. The MockGateway communicates with a MockRepository which stores all mock objects that has been setup for the current test method. Since PowerMock is just a layer on top of other mock frameworks we leave it for the underlying framework to do the actual mock creation, recording and verification of the mocks. The created mocks are put into the MockRepository by the PowerMock mock extension API. Basically all standard mock frameworks use CGLib to create a mock object which means that they're based on a hierarchical model (CGLib creates a sub class of the class to test at run-time which is the actual mock object) instead of a delegation model which PowerMock uses through it's byte-code manipulation by delegating to the MockGateway. This means that e.g. if a class is final CGLib cannot create a sub-class of it at run-time and therefore we can't mock it. So this is why most mock frameworks have the limitations that PowerMock doesn't.

So how do we mock static methods in a system class?

Since there's no way for PowerMock to modify the byte-code of a system class how do we route all calls to the MockGateway? The answer is quite simple, don't modify the system class itself but modify the class calling the system class! Thus outgoing calls to methods in the system class can be routed to the MockGateway instead of the system class intercepting incoming calls. That sounds simple enough but there's one more catch. As we saw earlier you set up expectations in the EasyMock extension API by reusing the standard expect method, e.g.

 
expect(Greeting.getGreeting(nameToGreet)).andReturn(expectedGreeting);
 

and this usually works fine because Greeting has been prepared for test and the call to method getGreeting is routed to the MockGateway. But in cases of system classes a call to a static method is NOT intercepted by the system class itself as described above and thus the call is never routed to the MockGatway. The solution is to prepare the actual test class for test as well so that the outgoing method call to getGreeting in the expect method is routed to the MockGateway as well! So let's look at a very simple example to demonstrate how to mock a call to URLEncoder.encode(..):

 
public class MyEncoder
	public String performEncode() throws UnsupportedEncodingException {
		return URLEncoder.encode("something", "encoding");
	}
}
 

and the test:

 
@RunWith(PowerMockRunner.class)
@PrepareForTest( { MyEncoder.class, MyEncoderTest.class })
public class MyEncoderTest {
 
	@Test
	public void demoOfSystemClassMocking() throws Exception {
		mockStatic(URLEncoder.class);
 
		expect(URLEncoder.encode("something", "encoding"))
                         .andReturn("something else");
		replayAll();
 
		assertEquals("something else", new MyEncoder().performEncode());
 
		verifyAll();
	}
}
 

But wait, will this work for final system classes?

That's a really good question because as we said earlier PowerMock delegates the mock creation process to the underlying mock framework (such as EasyMock) which uses CGLib. So even when mocking static methods the underlying mock framework is still used to create the CGLib mock of the class where the static methods are located. PowerMock then make use of the underlying framework's functionality to hold state for all recorded method invocations etc so that we don't have to deal with that in PowerMock as well. So usually what PowerMock does when it encounters a final class that should be prepared for test is simply to remove the final modifier. This means that CGLib can be used to create the mock object of this class without any problems. But what about a final system class? There's no way for PowerMock to remove the final modifier of a system class so what to do? What PowerMock does in these cases is to create a completely new class at run-time with the exact same structure as the original final system class. I.e. all method names and their corresponding signature are copied to a this new replica class. To allow for partial mocking all static methods of the replica class delegates to the original method in the final system class. It's also the replica class that is being mocked by the underlying mock framework instead of the original system class. The MockGateway then figures out that all methods bound for this particular system class should be routed to the replica mock instead. Thus mocking of static methods in final system classes such as java.lang.System or java.lang.String works as well. As a side note it would actually be possible to use this technique to implement duck-typing in Java as well. Anyway, here's an example to demonstrate what we've just said:

 
public class SystemPropertyMockDemo {
 
	public String getSystemProperty() throws IOException {
		return System.getProperty("property");
	}
}
 

and the test:

 
@RunWith(PowerMockRunner.class)
@PrepareForTest( { SystemPropertyMockDemo.class, SystemPropertyMockDemoTest.class })
public class SystemPropertyMockDemoTest
 
	@Test
	public void demoOfFinalSystemClassMocking() throws Exception {
		mockStatic(System.class);
 
		expect(System.getProperty("property")).andReturn("my property");
 
		replayAll();
 
		assertEquals("my property",
                                  new SystemPropertyMockDemo().getSystemProperty());
 
		verifyAll();
	}
}
 

Conclusion

As we've seen PowerMock is capable of achieving things not normally possible with standard mock frameworks because of technical limitations. Using PowerMock you can virtually choose any design you like without having to worry about the testability (or mockability to be more precise) aspects. Please visit our website for more information and downloads.

Background

PowerMock is intended for developers who want to unit test code in isolation from its environment. The environment may be for example other classes or
objects, other systems such as a database or a file-system. To isolate the unit you
can use a technique called mocking. Mocks let you record and verify behavior
according to your needs in order to get a deterministic behavior when executing
your test, for example provide a certain return value. A similar technique is stubs
that simply remove functionality and you don’t care about the return value.

Why?

There already exists frameworks that provide both mocks and stubs, so why
create another one? First of all PowerMock is not a new framework built from
scratch, instead it extends existing mock frameworks such as EasyMock and
Mockito. In most cases these frameworks are still sufficient. However, there are
cases when more power is needed!

To be able to use mock objects your code needs to be designed in a way that
makes it possible to replace collaborators, for example by using the Dependency
Injection pattern. Most often this is a good thing, but sometimes it leads to more
complexity and a more complicated production code that is more difficult to
understand. Another problem is legacy code which is seldom designed with unit
testing in mind. When trying to introduce Dependency Injection you are often
forced to perform a gigantic refactoring touching almost every class. Depending
on how brave you are this can either be a problem or an opportunity.

Another common situation is when there is some initialization routine in your
code or some third party library that does something that prevents you from
unit testing your code. This can both be a constructor or a static initializer. For
example, did you know that an interface can have a static initializer? This means
that just implementing an interface can execute code beyond your control!

Goals

Since there are many good mock frameworks out there already we think that
instead of creating something entirely new we want to reuse the API’s that
people already use and extend them with more capabilities. This means that
PowerMock consists of extension APIs to other popular mock frameworks.
EasyMock was the first API that we supported since we have been using it a lot.
In version 1.1 we also have some basic support for Mockito and we have serious
plans for a JMock extension. PowerMock is fully extendable and you can create
an extension on your own as well.

A key goal of PowerMock is to allow you to unit test your code without having to
think about the testability aspects. We would of course never encourage you to
write inflexible code that is hard to maintain, but we leave the design decisions
up to you and not to the technical limitations of a test or mock framework.

Another important goal is that PowerMock should be just another jar file. As a
user you should not have to care how PowerMock does its magic. You just put it
in your classpath and then you’re good to go. You don’t need to install any IDE
plugin, change the JVM settings or mess with your build environment.

When to use it

Using a 3rd party or legacy framework

• Sometimes communication with a particular framework is done through
  static methods (for example Java ME). PowerMock allows you to setup
  expectations for these static methods and simulate the behavior you need
  to test.
• Other frameworks require you to subclass classes that contain static
  initializers or constructors doing something that prevents you from unit-
  testing your code in isolation. PowerMock allows you to remove static
  initializers and suppress constructors. It also allows you to mock classes
  inside a signed jar files even though a class is package-private.

Design

• You really want to enforce the fact that some methods are private. PowerMock allows mocking and testing of both private and final methods..
• You want to read or write private state from your test without adding unnecessary methods to the production code that are used only for test purposes.
• In some cases you want to create a new instance of an object in your production code but still be able to replace this instance with a mock object from your test.

Examples

All examples in this article are written with the EasyMock extension API.
The examples are written in a way that easily demonstrates the capabilities of
PowerMock and are sometimes very naive. In the examples both the code being
tested and the actual test are completely pointless and is not a recommended
way of coding! The reason why we use such examples is of course that code that
typically need PowerMock is often quite complex and it would be hard to focus
on what we are trying to demonstrate.

When writing tests with PowerMock you basically always need to supply
two annotations at the class-level of your test as you will see in the examples
below. The first is the RunWith annotation which tells JUnit to run the test
with a specific JUnit runner. In PowerMock’s case you always specify the
PowerMockRunner, i.e. @RunWith(PowerMockRunner.class). This is what
bootstraps the entire PowerMock framework and this is how you can see that
a test is using PowerMock. The PowerMockRunner initializes PowerMock’s
classloader which starts to load all classes relevant for your particular test. Some
of these classes need to be prepared in order to allow for testability. These are
the classes that you wish to mock, for example those containing final or static
methods. You supply these classes to the @PrepareForTest annotation. What
PowerMock does then is to modify the byte-code of these classes at run-time so
that they become testable. Let’s look at a couple of examples to clear things up.

Mocking final classes or methods

Imagine writing a unit test for this fictive class:

public class SomeService {
    private final SomeDao someDao;
    public SomeService(SomeDao someDao) {
        this.someDao = someDao;
    }
    public String getFormattedData() {
        String data = ”Data is missing”;
        final String actualData = someDao.getData();
        if (actualData != null) {
            data = actualData;
        }
        return data;
    }
}

For those of you who are used to unit testing it doesn’t look like any problems
at first since it’s easy to inject a mock implementation of the SomeDao class to
an instance of the SomeService at construction since it’s using the Dependency
Injection pattern. But let’s look at the actual implementation of the SomeDao
class.

public final class SomeDao extends JdbcDaoSupport {
    public final String getData() {
        /* Query a database for data,
            this is not something we want to do in a unit test */
        getJdbcTemplate().queryForObject(”some sql”, String.class);
    }
}

As you may see this class communicates with a database which is typically
something we want to avoid in a unit test. The problem is that both the class
and the method is final so we wouldn’t be able to mock this class with standard
EasyMock. But PowerMock makes this possible using the standard EasyMock
syntax:

@RunWith(PowerMockRunner.class)
@PrepareForTest(SomeDao.class)
public class SomeServiceTest {
    @Test
    public void returnedValueIsActualData() throws Exception {
        final String expectedData = ”data”;
         // We use PowerMock.createMock(..) to create
         // the mock object since it’s final.
        SomeDao someDaoMock = createMock(SomeDao.class);
        expect(someDaoMock.getState()).andReturn(expectedData);
        replayAll();
        SomeService tested = new SomeService(someDaoMock);
        final String actualData = tested.getFormattedData();
        verifyAll();
        assertEquals(expectedData, actualData);
    }
}

Looking closely you may see that we’re using the replayAll() and verifyAll()
methods of the PowerMock API. These methods will replay and verify all mocks
created by PowerMock so that you don’t have to keep track of them yourself.
Of course PowerMock provides the standard replay(..) and verify(..) methods as
well if you’d rather want to use those.

Mocking and testing private methods

Sometimes you may want to enforce encapsulation and use private methods.
There’s a debate going on on whether one should test private methods by
themselves or not but we’ll leave that decision up to you. Mocking a method
of the class being tested is known as partial mocking. PowerMock lets you do
partial mocking and also invoke private methods during a test. Let’s say we have
the following class:

public class DataService {
    public boolean replaceData(final String dataId,
                      final byte[] binaryData) {
        // ...do something... then
        return modifyData(dataId, binaryData);
    }
    public boolean deleteData(final String dataId) {
        // ...do something else... then
        return modifyData(dataId, null);
    }
    private boolean modifyData(String dataId, byte[] binaryData) {
        // Imagine this method doing something
         // complex and expensive.
    }
}

DataService has two public methods that both calls the private modifyData
method and you may want to unit test these methods. You may want to test
replace replaceData without invoking modifyData or maybe just test the private
method itself. PowerMock lets you do both. To mock the modifyData method
you create a partial mock using PowerMock.createPartialMock(..) and to setup
expectations for a private method you use the PowerMock.expectPrivate(..)
method. For the replaceData method the test could look like this:

@RunWith(PowerMockRunner.class)
@PrepareForTest(DataService.class)
public class DataServiceTest {
    @Test
    public void testReplaceData() throws Exception {
        final String methodName = ”modifyData”;
        final byte[] expectedBinaryData = new byte[] { 42 };
        final String expectedDataId = ”id”;
        // Mock only the modifyData method
        DataService tested =
             createPartialMock(DataService.class, methodName);
        /*
         * This is the simplest way to expect
         * a method call to a private method.
         */
        expectPrivate(tested, methodName, expectedDataId,
                expectedBinaryData).andReturn(true);
        replay(tested);
        assertTrue(tested.replaceData(expectedDataId,
                 expectedBinaryData));
        verify(tested);
    }
}

PowerMock also provides utility methods located in the Whitebox class that can
assist you with accessing internal state, executing private methods or constructors
etc. So if we’d like to test the modifyData method instead of mocking it we can
do so by using the Whitebox.invokeMethod(..) functionality:

boolean success = (Boolean) Whitebox.invokeMethod(tested, ”modifyData”,
”myDataId”, new byte[]{42}); 

As you can see you just supply the instance containing the method, the method
name itself and the arguments that you want to pass to the method.

Note that in general you should avoid testing and mocking private methods
as these tests are often fragile and tightly coupled with the implementation.
During refactoring, when you most need your test cases, you may be forced to
simply throw away tests that are too tightly coupled to the old implementation.
Therefore, when writing tests you should always focus on testing expected
behavior and not check implementation details.

Mocking new object constructions

Let’s say we have a class that looks like this:

public class Directory {
    public boolean createDirectoryStructure(String directoryPath) {
        File directory = new File(directoryPath);
        if (directory.exists()) {
            throw new IllegalArgumentException(”\”” +
                directoryPath + ”\” already exists.”);
        }
        return directory.mkdirs();
    }
}

When unit testing this class we want to isolate ourselves from the file-system
environment since what’s interesting for us to test whether a directory already
exists or not. So what we want to do is to create a mock object of the File class
and replace the file instance with this mock object. This is something that is
normally not possible since we’re creating a new File instance in our code. But
with PowerMock you can indeed do so:

@RunWith(PowerMockRunner.class)
@PrepareForTest( Directory.class )
public class DirectoryTest {
    @Test
    public void givenThatDirectoryDoesntExistAssertThatItIsCreated() {
        final String path = ”directoryPath”;
        File fileMock = createMock(File.class);
        expectNew(File.class, path).andReturn(fileMock);
        expect(fileMock.exists()).andReturn(false);
        expect(fileMock.mkdirs()).andReturn(true);
        replayAll();
        Directory tested = new Directory();
        assertTrue(tested.createDirectoryStructure(path));
        verifyAll();
    }
} 

As you can see we’re using the expectNew functionality of PowerMock to
intercept the call to new File and return the mock object instead. Note that we
prepare the Directory class for test and not the File class. The reason for this is
that it is the Directory instance that creates a new File instance and thus the File
class itself doesn’t have to be prepared for test.

Suppressing unwanted behavior

Sometimes you want to suppress a method, constructor or static initializer
of your production code when executing your test because they are of no
importance to the test or they even prevent you from testing your unit. Let’s
take a look at the following example:

public class ExampleWithBaseClass extends ThirdPartyFrameworkBaseClass {
    private final String message;
    public ExampleWithBaseClass(String message) {
        this.message = message;
    } 

    public String getMessage() {
        return message;
    }
}

This seems like an easy class to unit test (so easy in fact that you probably
shouldn’t test it, but let’s do it anyway for demonstration purposes). But wait,
let’s look at what the ThirdPartyFrameworkBaseClass class looks like:

public class ThirdPartyFrameworkBaseClass {
    public ThirdPartyFrameworkBaseClass() {
        System.loadLibrary(”framework.dll”);
    }
} 

This class tries to load a dll file which may not be present when you run
a unit test for the ExampleWithBaseClass class and thus will lead to
an exception. With PowerMock you can just suppress the constructor
of the ThirdPartyFrameworkBaseClass so that you can unit test the
ExampleWithBaseClass class in isolation from the native framework dll.
Sometimes this may also save you a lot of time not having to bootstrap an entire
framework. You can achieve this by using the suppressConstructor method of
the PowerMock API. In this case we would do:

@RunWith(PowerMockRunner.class)
@PrepareForTest(ExampleWithBaseClass.class)
public class ExampleWithBaseClassTest {
    @Test
    public void assertThatConstructorMessageDoesntChange() throws
    Exception {
        // This is how we suppress the constructor
        suppressConstructor(ThirdPartyFrameworkBaseClass.class);
        final String message = ”myMessage”;
        ExampleWithBaseClass tested = new
        ExampleWithBaseClass(message);
        assertEquals(message, tested.getMessage());
    }
}

That’s it! PowerMock can also suppress static initializers, methods and fields.

Access private state

For mutable objects internal state may change after a method has been invoked.
When unit testing such objects it’s good to have an easy way to get a hold of this
state and see if it has updated accordingly. PowerMock supplies several useful
reflection utilities specially designed for unit testing. All of these reflection
utilities are located in the org.powermock.reflect.Whitebox class.

For demonstration purposes let’s say we have a class that looks like this:

public class ServiceHolder {
    private final Set