Testing asynchronous systems is hard. Not only does it require handling threads, timeouts and concurrency issues, but the intent of the test code can be obscured by all these details. Awaility is a DSL that allows you to express expectations of a asynchronous system in a concise and easy to read manner.

Simple example

So let's assume that we send an "add user" message to our asynchronous system like this:

 
publish(new AddUserMessage("John Doe"));
 

In your test case Awaitility can help you to easily verify that the database has been updated. In its simplest form it may look something like this:

 
await().until(newUserIsAdded());
 

Awaitility will now block the test execution and wait until the new user is added to the database. newUserIsAdded is a method that you implement yourself in your test case. It specifies the condition that must be fulfilled in order for Awaitility to stop waiting.

 
private Callable<Boolean> newUserIsAdded() {
	return new Callable<Boolean>() {
		public Boolean call() throws Exception {
			return userRepository.size() == 1; // The condition that must be fulfilled
		}
	};
}
 

By default Awaitility will wait for 10 seconds and if the size of the user respository is not equal to 1 during this time it'll throw a TimeoutException failing the test. If you want a different timeout you can define it like this:

 
await().atMost(5, SECONDS).until(newUserWasAdded());
 

Better reuse

Awaitility also supports splitting up the condition into a supplying and a matching part for better reuse. The example above can also be written as:

 
await().until( userRepositorySize(), equalTo(1) );
 

The userRepositorySize method is now a Callable of type Integer:

 
private Callable<Integer> userRepositorySize() {
	return new Callable<Integer>() {
		public Integer call() throws Exception {
			return userRepository.size(); // The condition supplier part
		}
	};
}
 

equalTo is a standard Hamcrest matcher specifiying the matching part of the condition for Awaitility.

Now we could reuse the userRepositorySize in a different test. E.g. let's say we have a test that adds three users at the same time:

 
publish(new AddUserMessage("User 1"), new AddUserMessage("User 2"), new AddUserMessage("User 3"));
 

We now reuse the userRepositorySize supplier and simply update the Hamcrest matcher:

 
await().until( userRepositorySize(), equalTo(3) );
 

Reduce verboseness

Since Java is so verbose Awaitility also provides a way achieve the same result by building up the supplier part without defining a Callable:

 
await().until( callTo(userRepository).size(), equalTo(3) );
 

callTo is method in Awaitility which you can use to define the suppling part inline in the await statement. Which option you like best depends on the use case and readability.

More features

Awaitility uses polling to check if a condition is fulfilled. You can easily specify a polling interval and poll delay (the delay before the first poll commits):

 
with().pollInterval(400, MILLISECONDS).and().pollDelay(2, SECONDS).await().forever().until(somethingHappens());
 

In some cases it's also useful to create named awaits for example if you need multiple awaits in one test. A naive example:

 
publish(new AddUserMessage("User 1"));
await("user 1").until(userRepositorySize(), is(equalTo(1)));
publish(new AddUserMessage("User 2"));
await("user 2").until(userRepositorySize(), is(equalTo(2)));
 

So if the first await statement fails the TimeoutException will indicate that it was the "user 1" statement that failed and so on.

Conclusion

We hope that you find Awaitility easy to use when you need to synchronize asynchronous behaviour in Java. However be aware that since it uses polling to verify that the condition is fulfilled it's not recommended to use it for precise performance testing. In these cases it could be better to use an AOP framework such as AspectJ and leverage on its compile-time weaving.

Please visit our homepage for more info and downloads.

Building the plugin

Building a plugin using maven is easy, simply add the following to your pom:

 
<properties>
	<jmeter.home>installation directory of jmeter</jmeter.home>
</properties>
 
<dependencies>
	<dependency>
		<groupId>org.apache.jmeter</groupId>
		<artifactId>jmeter-core</artifactId>
		<version>2.3.4</version>
		<scope>system</scope>
		<systemPath>${jmeter.home}/lib/ext/ApacheJMeter_core.jar</systemPath>
	</dependency>
	<dependency>
		<groupId>org.apache.jmeter</groupId>
		<artifactId>jmeter-jorphan</artifactId>
		<version>2.3.4</version>
		<scope>system</scope>
		<systemPath>${jmeter.home}/lib/jorphan.jar</systemPath>
	</dependency>
</dependencies>

You probably want to put jmeter.home in your settings.xml instead.

Testing the plugin

Whenever I develop something I want to have a quick build/test cycle. In this case I want to to start the JMeter UI without having to update the JMeter installation or any other manual work. I didn't get chronos to add my plugin to the UI. It seems chronos copied the jar files to JMETER_HOME/lib/junit and this probably works for running an already created test, but not for creating the test. I also failed to the the maven exec plugin to create the command line arguments I needed. Instead I added a small ant script to start JMeter:

<build>
<plugins>
<plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-antrun-plugin</artifactId>
      <configuration>
        <tasks>
<property name="runtime_classpath"
           refid="maven.runtime.classpath" />
          <exec executable="${jmeter.home}/bin/jmeter.bat">
            <arg value="-Jsearch_paths=${runtime_classpath}" />
          </exec>
        </tasks>
      </configuration>
    </plugin>
  </plugins>
</build>

To run the jmeter gui simply run mvn antrun:run. This only works for Windows, I leave other platforms as an exercise to the reader .

Using the plugin

I ended up copying the plugin jar and dependencies to the JMeter installation and used then this modified JMeter distribution when performing the tests. The reason was that I didn't have maven installed on some of the test clients. To copy dependencies you can use mvn dependency:copy-dependencies.
If you want to run JMeter using maven you probably want to look at chronos (although it is not released it seems to work fine):

Using Maven Chronos Without an External JMeter Install

Automated performance testing using JMeter and Maven

First step is to boot an instance. You need the command line tools for this, as neither the AWS Management Web Console nor ElasticFox currently supports this right now (note to developers - please add!).

ec2-run-instances --region eu-west-1 \
     -K pk-YOURKEYHERE.pem \
     -C cert-YOURCERTHERE.pem \
     -b '/dev/sda1=:100' \
     ami-d7a78ca3 \
     -g my-security-group -g common-security-group \
     -t m1.large \
     -k thekeyhere \
     --disable-api-termination \
     --instance-initiated-shutdown-behavior stop \
     -z eu-west-1a

• The command is ec2-run-instances with an 's' in the end. There is another command in the API without the s, which doesn't work.
• -b is the most important flag here. It says to make the boot disk (/dev/sda is Linux speek for C:) 100 GB, despite what the AMI manifest says (which is 30 GB).
• ami-d7a78ca3 is the Windows image, in this case a 64bit Windows 2008.
• -g security-group you should add as many as you like. Remember to think these through, since you cannot change which groups an instance belongs to.
• The flags --disable-api-termination --instance-initiated-shutdown-behavior stop are really nice, because that make sure you cannot accidentally terminate the instance, making the harddrive disappear.
• Note that I'm running in the EU region here.

Ok, so now you have a running Windows server. Once it has booted, you log on using remote desktop (well, as soon as you have the generated password, which takes 15 min). PLease note that the C: drive will show up as 30 GB at this point. The partition is still only 30 GB, even if the virtual harddrive is 100 GB.

1. Go into the windows management console. Go to disk management.
2. Right-click on the C: drive. Choose Extend volume from the context menu.
3. In the wizard that pops up, just accept the defaults, and click finish.

Done! The change is instant (no reboot or anything), and your system drive C: is now 100 GB.

This is the second part of the blog post I wrote about TDD in XCode. Make sure you've followed that tutorial before continuing here, or at least have a project of your own with OCUnit tests ready.

The server which we'll use is called Hudson and is very popular in the Java community. It does not readily support XCode projects but it does allow shell commands, so we'll use that to make our Calculator project compatible. We also want to fetch new versions of the source code as soon as it's checked in. We'll be a bit fancy and use Git as source control software. Here's a summary of what we want to do:

1. Download and install the Hudson continuos integration server
2. Download, install and setup the Git source control software as well as the Git plugin for Hudson
3. Download and install a script that converts OCUnit test results to JUnit format
4. Setup a new job in Hudson that checks out our XCode project and builds and tests it
5. Set up a notification and try it out

Downloading and Installing Hudson

In order to keep the instructions in this tutorial simple, we will have the source code repository and the build server itself on localhost. In real life you'll probably want to setup a dedicated machine.

Head over to the Hudson web site and download your copy of the server. Follow their included installation instructions, it's quite simple. Once you have Hudson up and running you can visit http://localhost:8080 to see the welcome screen. By the way, when you're ready to install Hudson on a real remote server I recommend running it as a Servlet inside Apache Tomcat instead.

Downloading and Setting Up Git

Next we want to install Git. There are several ways to install it. The simplest might be to use the OS X installer, but I personally prefer MacPorts. Either way, go ahead and install it and make sure that you can use the "git" command from Terminal.app when you're done.

In the Terminal, change directory to your XCode project folder and type:

		git init
	

You now have a working source code repository in your project folder. Neat. Before you continue create a text file called .gitignore and let it contain:

		build/*
		*.pbxuser
		*.mode1v3
		.DS_Store
		test-reports/*
	

That's a listing of the files and folders that should not be version controlled, since they are temporary or just used for XCode. Feel free to add any other files that you think only should be present locally. Now add all files (that aren't ignored) using:

		git add *
	

and finally commit them to a first version using:

		git commit -m "Initial import"
	

Fetching the Script

We need to fetch one more thing, ocunit2junit.rb, which is a little Ruby script that I wrote. Since you now have git, you can also download it using git (or clone the repo, which is the correct term). Change directory to /tmp and then type like this:

git clone git://github.com/ciryon/OCUnit2JUnit.git

Copy the script from /tmp/OCUnit2JUnit/ anywhere, like to /usr/local/bin/. Make sure it's executable by typing chmod +x ocunit2junit.rb.

The script will parse output from xcodebuild (the console command for building your XCode project) and look for output from OCUnit. The test results (success, failure, time passed etc) will be saved in the "test-reports" folder in the same XML format that JUnit uses. This also happens to be a format that Hudson understands.

Setting Up Hudson

Now head back to your Hudson welcome screen. Select Manage Hudson, Manage plugins and check "Hudson GIT plugin" under Available. Hudson will automatically download and install the plugin. Afterwards just restart Hudson.

We're ready to create a job in Hudson for our project. From the main screen select "New job", Build a free-style software project and call it "Calculator". There are some settings which you should fill in:

• Select to use git as source code management tool. The URL should be the file path to your project, like:

  /Users/youruser/XCodeProjects/Calculator/

• Select to poll SCM with Schedule:

  * * * * *

  That means it'll check every minute if there are changes. If you want to check less often, do that.

• Add new build step and select to execute shell. Use this command (make sure to point to the version of the iPhone SDK you want to use):

  xcodebuild -target "UnitTests" -sdk /Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator3.1.2.sdk/ -configuration "Debug" | /usr/local/bin/ocunit2junit.rb

• Select to also publish a JUnit test result report and the Test report XMLs reside at

  test-reports/*.xml

Trying it out

This is the moment of truth. Try to change your CalculatorTest.m so that one of the test cases fail. Type:

	git -a commit CalculatorTest.m "Broke the test, on purpose"

and see what happens. If all goes well, and you have entered everything correctly, Hudson should automatically notice there's a new version available, build it and try to run the test suite. Check the results and how it reports the test failure. Nice, eh? Fix the error and commit the test class again to see how Hudson reacts.

There are many settings, plugins and cool things to try out in Hudson. Go into Manage Hudson-> Configure system and setup your email settings, to allow Hudson to send mail. Then go back to configure your Calculator job and at the bottom select E-mail Notification. Enter your own email address and see how it works after you commits a file that breaks the build. If you don't want a mail, you can get an instant message, or perhaps have the server play a loud annoying sound? Everyone in your team should be aware of when a build fails, so it can be fixed right away. This is one of the great advantages of having a continuos integration server.

First, to enable FindBugs reporting in Maven, just add report section to your pom files, something like example below, but of course, you can do your own configuration.

<reporting>
  <plugins>
    <plugin>
      <groupId>org.codehaus.mojo</groupId>
      <artifactId>findbugs-maven-plugin</artifactId>
      <version>2.3</version>
      <configuration>
        <excludeFilterFile>exclude.xml</excludeFilterFile>
        <findbugsXmlOutput>true</findbugsXmlOutput>
        <findbugsXmlWithMessages>true</findbugsXmlWithMessages>
        <threshold>Low</threshold>
        <effort>Max</effort>
        <xmlOutput>true</xmlOutput>
      </configuration>
    </plugin>
  </plugins>
</reporting>

Then you can just use command mvn site if you want to generate more comprehensive project information or mvn findbugs:findbugs for only FindBugs reports.

Finally use mvn dashboard:dashboard to generate charts.

Voila. We have got nice graphic reports.
Well, not so nice. We have bugs we need to fix.

I soon came to understand that I would not be able to take advantage of all the wonderful possibilities that instrumentation offers. The reason for that is quite simple; the application that we are in the process of developing is not only extensive but also complicated with multiple activities, self-defined intents, and hundreds of views that also include scrollable lists. It would not make sense for me to spend a month writing one single test case that would only take 20 seconds to test manually. That is how Robotium-Solo was born. I needed a test framework that would help me write good and powerful test cases that emulated real users. The test case should be able to do what a real user does: click on anything that is clickable, look for irregularities, automatically move from activity to activity, etc. More importantly, I should not have to spend more than 10 minutes writing a test case that involves more then one activity.

With the help of Robotium-Solo a test case spanning over multiple activities could look like this:

public void testTextIsSaved() throws Exception {
   solo.clickOnText("Other");
   solo.clickOnButton("Edit");
   assertTrue(solo.searchText("Edit Window"));
   solo.enterText(0, "Some text for testing purposes")
   solo.clickOnButton("Save");
   assertTrue(solo.searchText("Changes have been made successfully"));
   solo.clickOnButton("Ok");
   assertTrue(solo.searchText("Some text for testing purposes"));
}

As you can see, I don’t have to specify any technical details or tell Robotium-Solo where to look for something, such as scrolling down a list when needed. It handles the above and more all on its own.

If you are interested in writing test cases of similar nature have a look at http://www.robotium.org. It makes writing powerful test cases a breeze.

1. You are not allowed to write any production code unless it is to make a failing unit test pass.
2. You are not allowed to write any more of a unit test than is sufficient to fail; and compilation failures are failures.
3. You are not allowed to write any more production code than is sufficient to pass the one failing unit test.

That means that test cases are written before any production code. Not all tests are written up front, it's rather that a small test is written, then a small piece of production code is written that only allows that test to pass. This is repeated in many small iterations: test, fail, code, pass, test, fail, code, pass...

Many people consider TDD to encourage clean code, simple architectures and a stable system that's actually testable. Plus, it's also fun! We've previously written about various aspects of TDD, but in this tutorial we'll focus on how it works for XCode projects, where you write apps for Mac and iPhone. We will create a simple XCode project, do some special configuration steps and then demonstrate how TDD can be used to write your app. We're going to use OCUnit and its framework SenTestingKit, which nowadays is included with Apple's XCode tools.

Creating the Calculator project

Let's start by creating a new project in XCode. You can pick any template, since we aren't going to touch the generated code. I picked a Window-based iPhone project. Name the project Calculator. Select New Target from the Project menu. Under Cocoa select Unit test Bundle. Call it UnitTests (I've had problems with space in the target name so avoid that) and add it to the project. We now need to change some small settings for this target. Select the UnitTests target and hit Command-I for Info. Select the Build tab and locate Other Linker Flags. Replace Cocoa with Foundation. Also remove the entry for GCC_PREFIX_HEADER.

Now it's time to create your test suite. Create a new group in your project and call it "Test Classes". Add a new File to this group and make sure it's a Cocoa->Objective-C test case class. Name it CalculatorTest.m. Uncheck "Also create CalculatorTest.h" since we don't need a header file. Don't add it to the Calculator target, but check it to be included in UnitTests. Open CalculatorTest.m file and above the @implementation declaration add:

#import <SenTestingKit/SenTestingKit.h>
#import "Calculator.h"
@interface CalculatorTest : SenTestCase
{

}
@end

This is just because we don't want a rather empty header file. All your test classes will look like this.

Following TDD, we should build right away. First make sure that the active target is "UnitTets" and then press the "Build" button. This will not only do a normal build, but also perform some shell script magic and actually execute the unit tests. Now the build fails of course, since Calculator.h can't be found.

So let's add a file which represents production code. Create a new empty Cocoa Touch Objective-C class called Calculator.m (also create the .h file), this is the class that we want to test. Don't forget to check that they should be included in both your targets. Notice that we mix Cocoa and Cocoa Touch, that's is fine - all code is executed on your Mac. Build again, and this time you'll see in the build log that everything built and the test suite was executed, but contained 0 test cases. Let's remedy that.

Writing test cases

Next we want to write our first test case. Open up CalculatorTest.m and add the following method:

-(void)testAdd
{
        Calculator* calculator = [[Calculator alloc] init];
        int result = [calculator add:5 to:6];
}

All methods that start with "test" will be recognized as being a test case, and automatically run when building the target. Try and build and you'll unsurprisingly get the erro "unrecognized selector sent to instance...". That's all good. Let's add the add method to our Calculator class. In Calculator.h add:

-(int)add:(int)a to:(int)b;

Then in Calculator.m add:

-(int)add:(int)a to:(int)b
{
        return 0;
}

That should be enough to let it compile and run, right? Try it out! You'll see that it indeed build and executes the tests.

Now we change the test so that it actually checks that we get the expected value back. We want to "assert" that the returned value is what we expected. Change the test case to look like this:

-(void)testAdd
{
        Calculator* calculator = [[Calculator alloc] init];
        int expected = 11;
        int result = [calculator add:5 to:6];
        STAssertEquals(expected, result,
                @"We expected %d, but it was %d",expected,result);
}

Build and you see that the test runs and fails since our calculator always returns 0 regardless of the input. Change the production code so that it returns a+b and rerun the test. Nice, we have a successful build and our test works! Notice the fast cycle of test, code, fix, rerun. The point of TDD is to write tests and production code in small iterations so that you always have something stable (= the tests pass). If you follow the rules of TDD you'll have a growing amount of test cases and you'll right away know when something breaks.

Let's write one more test. Now we want to add the functionality to allow one number to be divided by another. Start up like before with a new test case like this:

-(void)testDivide
{
        Calculator* calculator = [[Calculator alloc] init];
        float expected = 2.5;
        int result = [calculator divide:5 by:2];
        STAssertEquals(expected, result,
                @"We expected %d, but it was %d",expected,result);
}

You see, this time we expect to get back a float. Add the corresponding divide method to Calculator.h and Calculator.m. If you need help see the full code listing at the end of this article. You might notice that just returning a/b gives you 2.0. Type cast the return value to (float)a/b and you'll be fine. Go ahead when you got it working.

What happens if you try to divide something with zero? Well, why not add a test case for this scenario? If you're into maths you know that the result of this operation is undefined. How do you expect something to be undefined? This is tricky. Start off by just expecting any number and see what you get back. As you see, the float value "inf" is returned. It seems like Objective-C treats the zero as "a value approaching zero" and that will indeed result in infinity in a division. But, hey, that might not be what we want our calculator to do. Let's change the test case to expect an exception to be raised instead:

-(void)testDivideByZero
{
        Calculator* calculator = [[Calculator alloc] init];
        STAssertThrows([calculator divide:5 by:0],
                @"We expected an exception to be raised when dividing by 0");
}

Build and notice the error message when no exception was raised. Now change the production code to something like this:

-(float)divide:(int)a by:(int)b
{
        float result =  (float)a/b;
        if (result==INFINITY) {
                [NSException raise:@"Cannot divide by zero!"
                            format:@"Not possible to divide %d with %d", a,b];
        }
        return result;
}

Rerun and smile as the test passes! There are many different variants of asserts you can do with SenTestingKit. Compare objects with STAssertEqualObjects. STAssertTrue to check that a returned boolean is true. Open up SentTestCase_Macros.h if you want to see what you can play around with. By the way. You might have tried using NSLog in your test cases (just to experiment). This is nothing you would do in real life, as you want all necessary information in the fail message and output nothing if the test passes. Anyway, since the tests are actually run using a separate shell script for the UnitTest target you won't see the log in your console as usual. Instead check the build log and click the "text" icon to the right for the "Run test suite" step.

Wrapping up

Finally, if you look at your test class you might notice that we're allocating a new Calculator for every test case, and we never release them. That's no good. Luckily there are setUp and tearDown methods that will be launched automatically before and after each test case. Change your implementation to look like this (this is the final listing):

#import <SenTestingKit/SenTestingKit.h>
#import "Calculator.h"
@interface CalculatorTest : SenTestCase
{
        Calculator* calculator;
}
@end

@implementation CalculatorTest

- (void) setUp
{
        calculator = [[Calculator alloc] init];
}

-(void)tearDown
{
        [calculator release];
}

-(void)testAdd
{
        int expected = 11;
        int result = [calculator add:5 to:6];
        STAssertEquals(expected, result,
                @"We expected %d, but it was %d",expected,result);
}

-(void)testDivide
{
        float expected = 2.5;
        float result = [calculator divide:5 by:2];
        STAssertEquals(expected, result,
                @"We expected %f, but it was %f",expected,result);
}

-(void)testDivideByZero
{
        STAssertThrows([calculator divide:5 by:0],
                @"We expected an exception to be raised when dividing by 0");
}
@end

For completeness, here's the listing for Calculator.h:

#import 

@interface Calculator : NSObject {

}

-(int)add:(int)a to:(int)b;
-(float)divide:(int)a by:(int)b;

@end

and for Calculator.m:

#import "Calculator.h"

@implementation Calculator

-(int)add:(int)a to:(int)b
{
        return a+b;
}

-(float)divide:(int)a by:(int)b
{
        float result =  (float)a/b;
        if (result==INFINITY) {
                [NSException raise:@"Cannot divide by zero!"
                            format:@"Not possible to divide %d with %d", a,b];
        }
        return result;
}

@end

Next blog post we'll see how to automate the running of test cases on a build server called Hudson!

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.

As always you need to add @RunWith(PowerMockRunner.class) at the class-level of your test in order to bootstrap PowerMock itself. The classes that are normally not mockable needs to be prepared for testability by using the @PrepareForTest annotation.

Example #1 - Static methods

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

Let's say that in our test we want to mock the static call to the IdGenerator.generateNewId() and have it return 2 using the Mockito extension API. This can be achieved the following way:

 
@RunWith(PowerMockRunner.class)
// We prepare the IdGenerator for test because the static method is normally not mockable
@PrepareForTest(IdGenerator.class)
public class MyTestClass {
    @Test
    public void demoStaticMethodMocking() throws Exception {
	mockStatic(IdGenerator.class);
       /*
        * Setup the expectation using the standard Mockito syntax,
        * generateNewId() will now return 2 everytime it's invoked
        * in this test.
        */
	when(IdGenerator.generateNewId()).thenReturn(2L);		
 
	new ClassUnderTest().methodToTest();
 
	// Optionally verify that the static method was actually called
	verifyStatic();
	IdGenerator.generateNewId();
    }
}
 

Example #2 - Mock private methods (partial mocking)

Partial mocking of both static and instance methods works in PowerMock regardless if the method or class is final or private. Let's say we'd like to test the "methodToTest" in isolation from the private "methodToMock" method in the example below:

 
public final class PrivatePartialMockingExample {
    public String methodToTest() {
        return methodToMock("input");
    }
 
    private String methodToMock(String input) {
        return "REAL VALUE = " + input;
    }
}
 

To achieve this we can do:

 
@RunWith(PowerMockRunner.class)
@PrepareForTest(PrivatePartialMockingExample.class)
public class PrivatePartialMockingExampleTest {
    @Test
    public void demoPrivateMethodMocking() throws Exception {
	final String expected = "TEST VALUE";
	final String nameOfMethodToMock = "methodToMock";
	final String input = "input";
 
	PrivatePartialMockingExample underTest = spy(new PrivatePartialMockingExample());
 
	/*
	 * Setup the expectation to the private method using the method name
	 */
	when(underTest, nameOfMethodToMock, input).thenReturn(expected);
 
	assertEquals(expected, underTest.methodToTest());
 
	// Optionally verify that the private method was actually called
	verifyPrivate(underTest).invoke(nameOfMethodToMock, input);
    }
}
 

It's also possible to do the same thing without having to specify the method name using an overridden version of when:

 
@RunWith(PowerMockRunner.class)
@PrepareForTest(PrivatePartialMockingExample.class)
public class PrivatePartialMockingExampleTest {
    @Test
    public void demoPrivateMethodMocking() throws Exception {
        final String expected = "TEST VALUE";
        final String input = "input";
 
        /*
         * We get the method to mock by specifying the class where the
         * method is defined as well as its parameter types.
         */
        final Method methodToMock = method(PrivatePartialMockingExample.class, String.class);
 
        PrivatePartialMockingExample underTest = spy(new PrivatePartialMockingExample());
 
	// Notice how we pass the actual method instead of the name
        when(underTest, methodToMock).withArguments(input).thenReturn(expected);
 
        assertEquals(expected, underTest.methodToTest());
 
	// Optionally verify that the private method was actually called
        verifyPrivate(underTest).invoke(methodToMock).withArguments(input);
    }
}
 

This approach allows for more a refactor friendly code since you can change the method name of the private method without having to change your test.

Example #3 - Mock construction of new objects

Sometimes it might be good to mock construction of new objects. Consider the following example:

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

To test the create method in isolation from the file system we'd like to mock the construction of the new File instance in order to specify our expectations. To do this in PowerMock you need to prepare the class that creates the new object (since we don't want the new object to be created in our test, we'd like to return a mock object instead). Thus we prepare DirectoryStructure.class instead of File.class. The test may look like this when we expect that the directory doesn't exists:

 
@RunWith(PowerMockRunner.class)
@PrepareForTest(DirectoryStructure.class)
public class DirectoryStructureTest {
    @Test
    public void createDirectoryStructureWhenPathDoesntExist() throws Exception {
        final String directoryPath = "mocked path";
 
        File directoryMock = mock(File.class);
 
	// This is how you tell PowerMockito to mock construction of a new File.
        whenNew(File.class).withArguments(directoryPath).thenReturn(directoryMock);
 
	// Standard expectations
        when(directoryMock.exists()).thenReturn(false);
        when(directoryMock.mkdirs()).thenReturn(true);
 
        assertTrue(new NewFileExample().createDirectoryStructure(directoryPath));
 
        // Optionally verify that a new File was "created".
        verifyNew(File.class).withArguments(directoryPath);
    }
}
 

Example #4 - Modify code structure or change invocations

A new noteworthy feature of the 1.3 release is the new "member modification" API. Using this API you can suppress methods, fields or constructors as well stubbing and replacing methods and fields.
Below you can see some examples of how to suppress members in a class:

 
// Suppress a constructor in class ClassWithConstructor
suppress(constructor(ClassWithConstructor.class));
// Suppress method "myMethod" in class MyClass
suppress(method(MyClass.class, "myMethod"));
// Suppress all methods in class MyClass
suppress(methodsDeclaredIn(MyClass.class));
// Suppress field with name "myField" in class MyClass
suppress(field(MyClass.class, "myField"));
 

You can also stub methods:

 
//Stub the "getObject" method in class SuppressMethod to always return expectedValue
stub(method(SuppressMethod.class, "getObject")).andReturn(expectedValue);
 

And replace method invocations:

 
// Duck-typing of static methods
replace(method(MyClass.class, "getData")).with(method(MyClass2.class, "getTestData"));
// Replace method invocation with an invocation handler to allow for proxy-based AOP
replace(method(MyClass.class, "getData")).with(new MyInvocationHandler());
 

All methods can be statically imported from org.powermock.api.support.membermodification.MemberModifier and org.powermock.api.support.membermodification.MemberMatcher. For real examples refer to MemberModificationExampleTest.java in subversion.

Note that this also works for the EasyMock extension API.

Round up

We've just seen some examples of how to use PowerMock's extension API for Mockito to allow to mock things normally not possible. For more information please visit our web page at www.powermock.org.

Unit testing is often used to test complex units with one or more collaborators, usually with the help of mock objects. But the greatest value with unit testing, in my opinion, lies in testing the lowest level utility methods; the building blocks that simply have to be bullet-proof in order for the rest of the system to have a stable foundation.

Let's say that we have an Article domain object, storing article numbers from the database in the form "01234567":

public class Article {

    /**
     * 8 character numeric article number, eg "01234567".
     */
    private String articleNumber = "";

    public String getArticleNumber() {
        return articleNumber;
    }

    public void setArticleNumber(String articleNumber) {
        this.articleNumber = articleNumber;
    }
}

Business now demands that the article number should be formatted with dots here and there. They have added the story "User should see article numbers formatted as 123.456.78" to the Sprint Backlog.

We decide to write a test for this:

import static org.junit.Assert.assertEquals;
import org.junit.Test;

public class ArticleTest {

    @Test
    public void testGetFormattedArticleNumberNoZeros() {
        Article tested = new Article();
        tested.setArticleNumber("98765432");
        assertEquals("987.654.32", tested.getFormattedArticleNumber());
    }
}

We search around for a while, and find several nice tools for parsing formatted strings, but nothing useful for writing formatted strings that will help us in our scenario. Lacking ideas, we desperately try DecimalFormat. It's actually not that bad. If we divide by 100, we'll automatically get the right-most dot, don't we? We decide to give it a try:

import java.math.BigDecimal;
import java.text.DecimalFormat;
import java.text.DecimalFormatSymbols;
import java.text.NumberFormat;

public class Article {

    /**
     * 8 character numeric article number, eg "01234567".
     */
    private String articleNumber = "";

    public String getArticleNumber() {
        return articleNumber;
    }

    public void setArticleNumber(String articleNumber) {
        this.articleNumber = articleNumber;
    }

    /**
     * Retrieves the formatted article number.
     *
     * TODO I didn't find a nice generic formatting method, so I wrote this terrible hack.
     *
     * @return the formatted article number, eg 123.456.78
     */
    public String getFormattedArticleNumber() {
        NumberFormat nf = NumberFormat.getNumberInstance();
        DecimalFormat df = (DecimalFormat) nf;
        BigDecimal number = new BigDecimal(articleNumber);
        number = number.divide(new BigDecimal(100));
        String str = df.format(number);
        return str;
    }
}

We get a failure:

expected:<987[.654.]32> but was:<987[ 654,]32>

The decimal point is a comma (,) in the default locale, and the grouping separator is a blank. We can tweak that by calling the getDecimalFormatSymbols method, giving us a DecimalFormatSymbols that we can change:

DecimalFormatSymbols symbols = df.getDecimalFormatSymbols();
symbols.setDecimalSeparator('.');
symbols.setGroupingSeparator('.');
df.setDecimalFormatSymbols(symbols);

We also make sure the grouping size is always three by calling df.setGroupingSize(3). Here is the code so far:

public String getFormattedArticleNumber() {
    NumberFormat nf = NumberFormat.getNumberInstance();
    DecimalFormat df = (DecimalFormat) nf;
    df.setGroupingSize(3);
    DecimalFormatSymbols symbols = df.getDecimalFormatSymbols();
    symbols.setDecimalSeparator('.');
    symbols.setGroupingSeparator('.');
    df.setDecimalFormatSymbols(symbols);
    BigDecimal number = new BigDecimal(articleNumber);
    number = number.divide(new BigDecimal(100));
    String str = df.format(number);
    return str;
}

Success! Excellent. Now, we suspect that there might be problems with leading zeros, so we add another test:

    @Test
    public void testGetFormattedArticleNumberLeadingZero() {
        Article tested = new Article();
        tested.setArticleNumber("01234567");
        assertEquals("012.345.67", tested.getFormattedArticleNumber());
    }

As we suspected. We get a failure:

expected:<[0]12.345.67> but was:<[]12.345.67>

This can be fixed by setting the minimum integer size to 6:

df.setMinimumIntegerDigits(6);

We run the test suite again. Success! Great. We suspect that trailing zeros can also be troublesome. We add a few tests for that:

    @Test
    public void testGetFormattedArticleNumberSingleTrailingZero() {
        Article tested = new Article();
        tested.setArticleNumber("98765430");
        assertEquals("987.654.30", tested.getFormattedArticleNumber());
    }

    @Test
    public void testGetFormattedArticleNumberTrailingZeros() {
        Article tested = new Article();
        tested.setArticleNumber("98765400");
        assertEquals("987.654.00", tested.getFormattedArticleNumber());
    }

    @Test
    public void testGetFormattedArticleNumberAllZeros() {
        Article tested = new Article();
        tested.setArticleNumber("00000000");
        assertEquals("000.000.00", tested.getFormattedArticleNumber());
    }

We run the tests. The last three tests all fail, indicating that trailing zeros are lost. We fix that by setting the minimum fraction size to 2:

df.setMinimumFractionDigits(2);

Success! The complete method now looks like this:

/**
 * Retrieves the formatted article number.
 *
 * TODO I didn't find a nice generic formatting method, so I wrote this terrible hack.
 *
 * @return the formatted article number, eg 123.456.78
 */
public String getFormattedArticleNumber() {
    NumberFormat nf = NumberFormat.getNumberInstance();
    DecimalFormat df = (DecimalFormat) nf;
    df.setGroupingSize(3);
    df.setMinimumIntegerDigits(6);
    df.setMinimumFractionDigits(2);
    DecimalFormatSymbols symbols = df.getDecimalFormatSymbols();
    symbols.setDecimalSeparator('.');
    symbols.setGroupingSeparator('.');
    df.setDecimalFormatSymbols(symbols);
    BigDecimal number = new BigDecimal(articleNumber);
    number = number.divide(new BigDecimal(100));
    String str = df.format(number);
    return str;
}

It's not pretty, but it works. We check in the code, relax, and think for a while. Is there a simpler way? Of course there is:

/**
 * Retrieves the formatted article number.
 *
 * @return the formatted article number, eg 123.456.78
 */
public String getFormattedArticleNumber() {
    StringBuffer number = new StringBuffer(articleNumber);
    number.insert(3, '.');
    number.insert(7, '.');
    return number.toString();
}

Here, the power of unit testing shows. We don't even think twice about replacing the existing code. The tests still run, so we hook this code into the user interface, run the functional tests, check in, wait for a successful build, and finally ask the Product Owner to run the acceptance tests for the story.

 
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