1. Bugfix for NPE when calling facebookStore.createTestUser(false,"...").
2. Added possibility of using a provided HttpClient instance in HttpClientFacebookTestUserStore.
3. Added unit test that displays the use of json-path when asserting data.

Here's a quick reminder of how to create test users for an application. The creation process is handled by an instance of FacebookTestUserStore, e.g. The HttpClientFacebookTestUserStore which uses Apache HttpClient as communication method. The class needs the application ID and the application secret for the application in order to be able to create the users and this is specified in the constructor:

FacebookTestUserStore facebookStore = new HttpClientFacebookTestUserStore("<appId>", "<appSecret>"));

Now you have a choice when creating a test user: You may say that the test user should accept the privileges that you specify for it, which is done by:

FacebookTestUserAccount aTestUser = facebookStore.createTestUser(true, "read_stream");

If you want to give a choice to the test user whether the privileges should be accepted or not, you do the following:

FacebookTestUserAccount aTestUser = facebookStore.createTestUser(false, "read_stream");

The accept/decline choice takes part in the web browser, hence you need the login URL for the test user to access the page. This URL is accessible from the FacebookTestUserAccount:

aTestUser.loginUrl();

Specifying a HttpClient instance to HttpClientFacebookTestUserStore

There might be occasions where you need a special HttpClient instance for communication, for example one instance with proxy settings configures, or another instance where you have stubbed all the communication that takes place. To provide the instance to HttpClientFacebookTestUserStore, just specify it in the constructor:

HttpClient httpClient = new DefaultHttpClient();
FacebookTestUserStore facebookStore = new HttpClientFacebookTestUserStore("<appId>", "<appSecret>", httpClient));

Using json-assert to verify application behavior

The json-assert project, which uses json-path can be used to make life a little less verbose when asserting on data from the JSON document representations of the Facebook data streams that are available in the FacebookTestUserAccount. For example, the user details of a test user can be accessed like this:

aTestUser.getUserDetails();

The result is a java.lang.String containing a JSON Document. To make it easier to assert that the user details actually contain the expected data, you may use json-assert and Hamcrest matchers:

String userDetails = account.getUserDetails();

JsonAssert.with(userDetails).assertThat("$.first_name", equalTo("Sue"));
JsonAssert.with(userDetails).assertThat("$.last_name", equalTo("Ellen"));

Feel free to test it out, the code is open source an can be found on Maven central or on the
Facebook Test Java API project page.

/Tobias

 
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!

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.

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