Testing REST-apis with Rest Assured

The REST-Api in RHQ is evolving and I had long ago started writing some integration tests against it.
I did not want to do that with pure http calls, so I was looking for a testing framework and found one that I used for some time. I tried to enhance it a bit to better suit my needs, but didn't really get it to work.

I started searching again and this time found Rest Assured, which is almost perfect. Let's have a look at a very simple example:

  expect()
     .statusCode(200)
     .log().ifError()
  .when()
     .get("/status/server");

As you can see, this is a fluent API that is very expressive, so I don't really need to explain what the above is supposed to do.

In the next example I'll add some authentication

  given()
     .auth().basic("user","name23")
  .expect()
     .statusCode(401)
  .when()
     .get("/rest/status"); 

Here we add "input parameters" to the call, which are in our case the information for basic authentication, and expect the call to fail with a "bad auth" response.

Now it is tedious to always provide the authentication bits throughout all tests, so it is possible to tell Rest Assured to always deliver a default set of credentials, which can still be overwritten as just shown:

@Before
public void setUp() {
   RestAssured.authentication = basic("rhqadmin","rhqadmin");
}

There are a lot more options to set as default, like the base URI, port, basePath and so on.

Now let's have a look on how we can supply other parameters

  AlertDefinition alertDefinition = new AlertDefinition(….);

  AlertDefinition result =
  given()
     .contentType(ContentType.JSON)
     .header(acceptJson)
     .body(alertDefinition)
     .log().everything()
     .queryParam("resourceId", 10001)
  .expect()
     .statusCode(201)
     .log().ifError()
  .when()
     .post("/alert/definitions")
  .as(AlertDefinition.class);


We start with creating a Java object AlertDefinition that we use for the body of the POST request. We define that it should be sent as JSON and that we expect JSON back. For the URL, a
query parameter with the name 'resourceId' and value '10001' should be appended. 
We also expect that the call returns a 201 - created and would like to know the details is this is not the case.
Last but not least we tell RestAssured, that it should convert the answer back into an object of type AlertDefinition which we can then use to check constraints or further work with it.

Rest Assured offers another interesting and built-in way to check constraints with the help of XPath or it's JSON-counterpart JsonPath:


  expect()
     .statusCode(200)
     .body("name",is("discovery"))
  .when()
     .get("/operation/definition");


In this (shortened) example we expect that the GET-call returns OK and an object that has a body field with the name 'name' and the value 'discovery'.

Conclusion

Rest Assured is a very powerful framework to write tests against a REST/hypermedia api. With its fluent approach and the expressive method names it allows to easily understand what a certain call is supposed to do and to return.

The Rest Assured web site has more examples and documentation. The RHQ code base now also has >70 tests using that framework.