cat /proc//limits

the limit was still set to the initial value of 1024:

Limit                     Soft Limit           Hard Limit           Units
Max cpu time              unlimited            unlimited            seconds
Max file size             unlimited            unlimited            bytes
Max data size             unlimited            unlimited            bytes
Max stack size            8388608              unlimited            bytes
Max core file size        0                    unlimited            bytes
Max resident set          unlimited            unlimited            bytes
Max processes             63810                63810                processes
Max open files                1024                     1024                    files
Max locked memory         65536                65536                bytes
Max address space         unlimited            unlimited            bytes
Max file locks            unlimited            unlimited            locks
Max pending signals       63810                63810                signals
Max msgqueue size         819200               819200               bytes
Max nice priority         0                    0
Max realtime priority     0                    0
Max realtime timeout      unlimited            unlimited            us

It was not until we found this thread that the reason and solution became clear. Our Tomcat instance was started as a service during boot and there's a bug discovered and filed (with patch) in 2005 that doesn't seem to have been resolved yet. The bug reveals itself by ignoring the max number of open files limit when starting daemons in Ubuntu/Debain. So the work-around suggested by "BOK" was to edit /etc/init.d/tomcat and add:

ulimit -Hn 16384
ulimit -Sn 16384

Finally the max number of open files for Tomcat was increased!

 
def words = ['ant', 'buffalo', 'cat', 'dinosaur']
def wordsWithSizeGreaterThanFour = words.findAll { it.length() > 4 }
 

At the first line we simply define a list with some words but the second line is more interesting. Here we search the words list for all words that are longer than 4 characters by calling the findAll with a Groovy closure. The closure has an implicit variable called "it" which represents the current item in the list. The result is a new list, wordsWithSizeGreaterThanFour, containing buffalo and dinosaur. Pretty nice and simple! There are other interesting methods that we can use on collections in Groovy as well, e.g.

• find - finds the first item matching a closure predicate
• collect - collect the return value of calling a closure on each item in a collection
• sum - Sum all the items in the collection
• max/min - returns the max/min values of the collection

So how do we take advantage of this when validating our XML or JSON responses with REST Assured?

XML Example

Let's say we have a resource at "localhost:8080/shopping" that returns the following XML:

 
<shopping>
      <category type="groceries">
        <item>Chocolate</item>
        <item>Coffee</item>
      </category>
      <category type="supplies">
        <item>Paper</item>
        <item quantity="4">Pens</item>
      </category>
      <category type="present">
        <item when="Aug 10">Kathryn's Birthday</item>
      </category>
</shopping>
 

Let's also say we want to write a test that verifies that the category of type groceries has items Chocolate and Coffee. In REST Assured it can look like this:

 
expect().
         body("shopping.category.find { it.@type == 'groceries' }.item", hasItems("Chocolate", "Coffee")).
when().
         get("/shopping");

What's going on here? First of all the XML path "shopping.category" returns a list of all categories. On this list we invoke a function, find, to return the single category that has the XML attribute, type, equal to "groceries". On this category we then continue by getting all the items associated with this category. Since there are more than one item associated with the groceries category a list will be returned and we verify this list against the hasItems Hamcrest matcher.

But what if you want to get the items and not validate them against a Hamcrest matcher? This is also simple using the XmlPath class:

 
// Get the response body as a String
String response = get("/shopping").asString();
// And get the grocieries from the response. "from" is statically imported from the XmlPath class
List<String> groceries = from(response).getList("shopping.category.find { it.@type == 'groceries' }.item");
 

If the list of groceries is the only thing you care about in the response body you can also use a shortcut:

 
// Get the response body as a String
List<String> groceries = get("/shopping").path("shopping.category.find { it.@type == 'groceries' }.item");
 

Depth-first search

It's actually possible to simplify the previous example even further:

 
expect().
         body("**.find { it.@type == 'groceries' }", hasItems("Chocolate", "Coffee")).
when().
         get("/shopping");
 

** is a shortcut for doing depth first searching in the XML document. We search for the first node that has an attribute named type equal to "groceries". Notice also that we don't end the XML path with "item". The reason is that toString() is called automatically on the category node which returns a list of the item values.

Root path

Let's expand the example by also validating that the category of type supplies contains Paper and Pens:

 
expect().
         body("**.find { it.@type == 'groceries' }", hasItems("Chocolate", "Coffee")).
         body("**.find { it.@type == 'supplies' }", hasItems("Paper", "Pens")).
when().
         get("/shopping");
 

Even though this works you can probably see that the XML path is almost duplicated for the two body expectations and this is of course something we want to avoid. To address this we can use a root path and path arguments:

 
expect().
         rootPath("**.find { it.@type == '%s' }").
         body("", withArgs("groceries"), hasItems("Chocolate", "Coffee")).
         body("", withArgs("supplies"), hasItems("Paper", "Pens")).
when().
         get("/shopping");
 

By specifiying a "root path" we don't need to duplicate the entire path just to change the category type.

JSON Example

Let's say we have a resource at "/store" that returns the following JSON document:

 
{ "store" : {
  "book" : [
          { "author" : "Nigel Rees",
            "category" : "reference",
            "price" : 8.95,
            "title" : "Sayings of the Century"
          },
          { "author" : "Evelyn Waugh",
            "category" : "fiction",
            "price" : 12.99,
            "title" : "Sword of Honour"
          },
          { "author" : "Herman Melville",
            "category" : "fiction",
            "isbn" : "0-553-21311-3",
            "price" : 8.99,
            "title" : "Moby Dick"
          },
          { "author" : "J. R. R. Tolkien",
            "category" : "fiction",
            "isbn" : "0-395-19395-8",
            "price" : 22.99,
            "title" : "The Lord of the Rings"
          }
        ]
   }
}
 

Example 1

As a first example let's say we want to make the request to "/store" and assert that the titles of the books with a price less than 10 are "Sayings of the Century" and "Moby Dick":

 
expect().
        body("store.book.findAll { it.price < 10 }.title", hasItems("Sayings of the Century", "Moby Dick")).
when().
        get("/store");
 

Just as in the XML examples above we use a closure to find all books with a price less than 10 and then return the titles of all the books. We then use the hasItems matcher to assert that the titles are the ones we expect. Using JsonPath we can return the titles instead:

 
// Get the response body as a String
String response = get("/store").asString();
// And get all books with price < 10 from the response. "from" is statically imported from the JsonPath class
List<String> bookTitles = from(response).getList("store.book.findAll { it.price < 10 }.title");
 

Example 2

Let's consider instead that we want to assert that the sum of the length of all author names are greater than 50. This is a rather complex question to answer and it really shows the strength of closures and Groovy collections. In REST Assured it looks like this:

 
expect().
        body("store.book.author.collect { it.length() }.sum()", greaterThan(50)).
when().
        get("/store");
 

First we get all the authors ("store.book.author") and invoke the collect method on the resulting list with the closure { it.length() }. What it does is to call the length() method on each author in the list and returns the result to a new list. On this list we simply call the sum() method to sum all the length's. The end result is 53 and we assert that it's greater than 50 by using the greaterThan matcher. But it's actually possible to simplify this even further. Consider the words example from the beginning of the article again:

 
def words = ['ant', 'buffalo', 'cat', 'dinosaur']
 

Groovy has a very handy way of calling a function for each element in the list by using the * notation, e.g.

 
def words = ['ant', 'buffalo', 'cat', 'dinosaur']
assert [3, 6, 3, 8] == words*.length()
 

I.e. Groovy returns a new list with the lengths of the items in the words list. We can utilize this for the author list in REST Assured as well:

 
expect().
        body("store.book.author*.length().sum()", greaterThan(50)).
when().
        get("/store");
 

And of course we can use JsonPath to actually return the result:

 
// Get the response body as an input stream
InputStream response = get("/store").asInputStream();
// Get the sum of all author length's as an int. "from" is again statically imported from the JsonPath class
int sumOfAllAuthorLengths = from(response).getInt("store.book.author*.length().sum()");
// We can also assert that the sum is equal to 53 as expected.
assertThat(sumOfAllAuthorLengths, is(53));
 

Summary

At a first glance the syntax may seem quite strange and complex but once you get used to it it's extremely powerful and actually quite simple. It's also a good place to start if you work with Java and want to understand the benefit of closures. There are a lot more features that can help you parsing and validating JSON and XML using REST Assured than the ones shown in this article. For further reading refer to the REST Assured web-page and read up on Groovy collections. Enjoy!

Example

Let's say you have a simple HTML page that performs file-uploading from a browser like this:

<html>
<body>
	<form id="upload" action="/fileUpload" method="post" enctype="multipart/form-data">
		<input type="file" name="file" size="40">
		<input type=submit value="Upload!">
	</form>
</body>
</html>

We also assume that we have a server that receives the file and return a JSON response like this if everything was ok:

 
{ "fileUploadResult" : "OK" }
 

Now let's use REST Assured to upload a file and assert that the upload was OK:

 
given().
         multiPart(new File("/home/johan/some_large_file.bin")).
expect().
         body("fileUploadResult", is("OK")).
when().
         post("/fileUpload");
 

With so little code you've now managed to POST a large file using multi-part form data encoding to the server and asserted that the expected JSON bundled in the response body was correct.

But how can this work? We haven't even specified a control name? Well if you don't define a control name specifically REST Assured will default to "file". In many cases this is of course not the case. For example let's say we change the control name in the HTML form to "file2" instead:

<html>
<body>
	<form id="upload" action="/fileUpload" method="post" enctype="multipart/form-data">
		<input type="file" name="file2" size="40">
		<input type=submit value="Upload!">
	</form>
</body>
</html>

REST Assured still makes it simple:

 
given().
         multiPart("file2", new File("/home/johan/some_large_file.bin")).
expect().
         body("fileUploadResult", is("OK")).
when().
         post("/fileUpload");
 

Multiple parts

You can even send multiple files, streams, byte-arrays and form parameters in the same request:

 
InputStream inputStream = ..
 
given().
         multiPart("file1", new File("/home/johan/some_large_file.bin")).
         multiPart("file2", new File("/home/johan/some_other_large_file.bin")).
         multiPart("file3", "file_name.bin", inputStream).
         formParam("name", "value").
expect().
         body("fileUploadResult", is("OK")).
when().
         post("/advancedFileUpload");
 

Summary

As you've hopefully seen it's very simple do multi-part form data uploading with REST Assured. Credits should of course also go to Apache HTTP Client for making it possible. To get started with REST Assured today just visit the web-site. Enjoy!

Easy parsing of the response body

JSON

Let's assume that a REST service at localhost:8080/json returns:

 
{
"lotto":{
 "lottoId":5,
 "winning-numbers":[2,45,34,23,7,5,3],
 "winners":[{
   "winnerId":23,
   "numbers":[2,45,34,23,3,5]
 },{
   "winnerId":54,
   "numbers":[52,3,12,11,18,22]
 }]
}
}
 

As a recap let's say you want to validate that the lottoId is equal to 5 and winnerIds are 23 and 54 you can do like this:

 
expect().
         body("lotto.lottoId", equalTo(5)).
         body("lotto.winners.winnderId", hasItems(23, 54)).
when().
       get("/lotto");
 

where "equalTo" and "hasItems" are standard Hamcrest matchers. But what if you want to return the lottoId or winnder id's and do something with the values? For this reason JsonPath has been added to REST Assured. Example:

 
String response = get("/lotto").asString();
 
// Assuming we've statically imported the "from" method in JsonPath we can do:
int lottoId = from(response).get("lotto.lottoId");
List<Integer> winnerIds = from(response).get("lotto.winners.winnderId");
 
..
 

You can also set a so called "root path" so that you don't have to repeat the entire path for every "get":

 
String responseString = get("/lotto").asString();
 
JsonPath response = new JsonPath(responseString).setRoot("lotto");
int lottoId = response.get("lottoId");
List<Integer> winnerIds = response.get("winners.winnderId");
 

XML

The equilvant of JsonPath for XML is called XmlPath and it works in very much the same way as JsonPath but arguably a bit more complex because of the nature of XML. Consider the following XML available at localhost:8080/xml:

 
<records>
   <car name='HSV Maloo' make='Holden' year='2006'>
      <country>Australia</country>
      <record type='speed'>Pickup Truck with speed of 271kph</record>
   </car>
   <car name='P50' make='Peel' year='1962'>
      <country>Isle of Man</country>
      <record type='size'>Street-Legal Car at 99cm wide, 59kg</record>
   </car>
</records>
 

Now let's make a request and parse the XML:

 
// Get the XML from localhost:8080/xml
String xml = get("/xml").asString();
 
// Get the country of the first car (“from” is statically imported from from XmlPath)
String country = from(xml).get("records.car[0].country”);
 
// Get a list of all car names
List<String> carNames = from(xml).get("records.car.@name");

As with JsonPath you can also set a root path to make it a bit more efficient:

 
XmlPath xmlPath = new XmlPath(xml).setRoot("records");
String country = xmlPath.get("car[0].country");
List<String> carNames = xmlPath.get("car.@name");
 

Filters

Another powerful feature is support for filters. A filter allows you to inspect and alter a request before it's actually committed and also inspect and alter the response before it's returned to the expectations. You can regard it as an "around advice" in AOP terms. Filters can be used to implement custom authentication schemes, session management, logging etc. To create a filter you need to implement the com.jayway.restassured.filter.log.Filter interface. Here's an example filter that simply logs the response body to the console:

 
public class SystemOutFilter implements Filter {
 
    public Response filter(FilterableRequestSpecification requestSpec, FilterableResponseSpecification responseSpec, FilterContext ctx) {
        final Response response = ctx.next(requestSpec, responseSpec); // Invoke the request by delegating to the next filter in the filter chain.
        System.out.println(response.asString());
        return response;
    }
}
 

You can then apply your filter like this:

 
given().filter(new SystemOutFilter()). ..
 

REST Assured already comes with two pre-defined logging filters called ResponseLoggingFilter and ErrorLoggingFilter are there's also shortcuts for using these filters (see below).

Logging

When writing a test it's often useful to see what the response body actually looks like. To easily accomodate this REST Assured provides a shortcut for adding the two logging filters introduced in the previous section. So to log the response body regardless of the status code you can just do:

 
expect().
         log().
         body("lotto.lottoId", equalTo(5)).
         body("lotto.winners.winnderId", hasItems(23, 54)).
when().
         get("/lotto");
 

If you only which to log when an error occurs you can do:

 
expect().
         logOnError().
         body("lotto.lottoId", equalTo(5)).
         body("lotto.winners.winnderId", hasItems(23, 54)).
when().
         get("/lotto");
 

Form authentication

Form authentication is one of the most popular authentication techniques on the net today and using REST Assured it's very simple to test services requiring this scheme. Imagine that the request to localhost:8080/json requires form authentication, we can then do:

 
given().
         auth().form("username", "password").
expect().
         body("lotto.lottoId", equalTo(5)).
         body("lotto.winners.winnderId", hasItems(23, 54)).
when().
         get("/lotto");
 

In many cases it's as simple as that! Basically what happens is that REST Assured parses the login page and logs in for you before making the original request. But if you have many tests or if REST Assured is not able to parse the login page you can supply something called a FormAuthConfig to tell REST Assured how to login. What you provide is the form action and the user name and password input tags. This option will also make your test run faster since there's no need for REST Assured to make an additional requests and parse the login page. For example:

 
given().
         auth().form("username", "password", new FilterConfig("/action", "usernameField", "passwordField").
expect().
         logOnError().
         body("lotto.lottoId", equalTo(5)).
         body("lotto.winners.winnderId", hasItems(23, 54)).
when().
         get("/lotto");
 

If you're using Spring Security there's a pre-defined FilterAuthConfig:

 
given().auth().form("username", "password", FilterConfig.springSecurity()).
 

Reusable specifications

Instead of having to duplicate response expectations and/or request parameters for different tests you can re-use an entire specification. To do this you define a specification using either the RequestSpecBuilder or ResponseSpecBuilder.

E.g. let's say you want to make sure that the expected status code is 200 and that JSON the size of the JSON array "x.y" has size 2 in several tests you can define a ResponseSpecBuilder like this:

 
ResponseSpecBuilder builder = new ResponseSpecBuilder();
builder.expectStatusCode(200);
builder.expectBody("x.y.size()", is(2));
ResponseSpecification responseSpec = builder.build();
 
// Now you can re-use the "responseSpec" in many different tests:
expect().
       spec(responseSpec).
       body("x.y.z", equalTo("something")).
when().
       get("/something");
 

In this example the data defined in "responseSpec" is merged with the additional body expectation and all expectations must be fulfilled in order for the test to pass.

You can do the same thing if you need to re-use request data in different tests. E.g.

 
RequestSpecBuilder builder = new RequestSpecBuilder();
builder.addParameter("parameter1", "parameterValue");
builder.addHeader("header1", "headerValue");
RequestSpecification requestSpec = builder.build();
 
given().
        spec(requestSpec).
        param("parameter2", "paramValue").
expect().
        body("x.y.z", equalTo("something")).
when().
        get("/something");
 

Here the request's data is merged with the data in the "requestSpec" so the request will contain two parameters ("parameter1" and "parameter2") and one header ("header1").

Summary

As you've hopefully seen there are many new useful features added to REST Assured. Other new features that have not been mentioned in this post are e.g. improved HTML parsing, very simple XSD/DTD validation, multi-value parameters, setting root path on expectations, improved configuration of default settings etc etc. In the future we'll hope to add support for JSONP, better XML parsing using XmlPath and a more BDD-like (given, when, then) syntax. Please visit our homepage for more information and downloads.

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.

Example 1 - JSON

Assume that a GET request to http://localhost:8080/lotto returns JSON as:

 
{
 "lotto":{
 "lottoId":5,
 "winning-numbers":[2,45,34,23,7,5,3],
 "winners":[{
   "winnerId":23,
   "numbers":[2,45,34,23,3,5]
 },{
   "winnerId":54,
   "numbers":[52,3,12,11,18,22]
    }
 ]}
}
 

REST assured can then help you to easily make the GET request and verify the response. E.g. if you want to verify that lottoId is equal to 5 you can do like this:

 
expect().body("lotto.lottoId", equalTo(5)).when().get("/lotto");
 

or perhaps you want to check that the winnerId's are 23 and 54:

 
expect().body("lotto.winners.winnerId", hasItems(23, 54)).when().get("/lotto");
 

Note that equalTo and hasItems are standard Hamcrest matchers.

Example 2 - XML

XML can be verified in a similar way. Image that a POST request to http://localhost:8080/greetXML returns:

 
<greeting>
   <firstName>{params("firstName")}</firstName>
   <lastName>{params("lastName")}</lastName>
</greeting>
 

i.e. it sends back a greeting based on the firstName and lastName parameter sent in the request. You can easily perform and verify e.g. the firstName with REST assured:

 
with().parameters("firstName", "John", "lastName", "Doe").expect().body("greeting.firstName", equalTo("John")).when().post("/greetXML");
 

You can also verify XML responses using X-Path. For example:

 
expect().body(hasXPath("/greeting/firstName[text()='John']")).with().parameters("firstName", "John", "lastName", "Doe").post("/greetXML");
 

Authentication

REST assured also supports some authentication schemes, for example basic authentication:

 
given().auth().basic("username", "password").expect().statusCode(200).when().get("/secured/hello");
 

Other supported schemes are OAuth, Digest and certificate authentication.

Conclusion

As you can see it can be really simple to test REST services in Java. REST Assured supports the POST, GET, PUT, DELETE and HEAD http methods and includes specifying and validating e.g. parameters, headers, cookies and body easily. Visit our homepage for more info and downloads.

Scala support

First of all we now have support for Scala! This means that you can write your Awaitility code like this:

 
await until { someMethod() > 3 }
 

What you actually provide is a no argument function that returns a scala.Boolean. To make this work you simply mixin the AwaitilitySupport trait that is provided in the awaitility-scala module. For more information please refer to the documentation.

Field suppliers

Another useful feature is the ability to wait until a field in a class or object has a specific value. In its simplest form you just need to specify the field type. Let's say we have a class with a private field like this:

 
public class Demo {
    @MyAnnotation
    private volatile int myField = 0;
 
    // Other code goes here
}
 

Using Awaitility field suppliers you can then wait until myField matches something without having to add a getter for the field. For example:

 
await().until( fieldIn(demo).ofType(int.class), equalTo(2) );
 

Here Awaitility waits until the field of type int in demo equals to 2 or a timeout occurs (default 10 seconds). If you have more than one field of type int in demo you can also specify the field name to uniquely identify the field:

 
await().until( fieldIn(demo).ofType(int.class).andWithName("myField"), equalTo(2) );
 

You can also get the field based on an annotation to avoid specifying a field name:

 
await().until( fieldIn(demo).ofType(int.class).andAnnotatedWith(MyAnnotation.class), equalTo(2) );
 

Important: Awaitility does nothing to ensure thread safety or thread synchronization! This is your responsibility! Make sure your code is correctly synchronized or that you are using thread safe data structures such as volatile fields or classes such as AtomicInteger and ConcurrentHashMap.

Round off

We hope you'll find the new release of Awaitility useful. Please refer to the release notes for upgrade information and don't forget to visit our home page for downloads.

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().untilCall( to(userRepository).size(), equalTo(3) );
 

to 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.

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.

Failed to get the adb version: Cannot run program "/home/johan/devtools/android/android-sdk-linux_x86-1.6_r1/tools/adb": java.io.IOException: error=2, No such file or directory

I opened the terminal and tried to manually run an Android executable but even here it said that the file couldn't be found! The problem seemed to be that the Android executables requires 32 bit libraries that are not available in Ubuntu 64 by default. To solve this I downloaded the execellent getlibs application which is a utility for automatically resolving dependencies for 32-bit programs on a 64 bit system. So I went into platforms/android-1.6/tools in the Android SDK installation folder and executed:

 
getlibs aapt
 

which installed and upgraded the following libraries:

 
The following NEW packages will be installed:
  ia32-libs lib32asound2 lib32gcc1 lib32ncurses5 lib32stdc++6 lib32z1
  libc6-i386
The following packages will be upgraded:
  libc6 libc6-dev
 

After this was done I went back into Eclipse, did a project clean and refresh and after that I was able to start the Android emulator successfully. Hopefully this may help someone who's in the same situation.

 
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