Testing REST APIs With REST Assured

@Test
public void testStatusPage()
{
  expect()
     .statusCode(200)
     .log().ifError()
  .when()
     .get("/status/server");
}

As you can see, this fluent API is very expressive, so I don’t really need to explain what the above is supposed to do. The example also shows that REST Assured is using defaults for the target server IP and port.

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

Here we add authentication “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 to ensure that a user with bad credentials can’t log in. You can see that we do not need to know how the authentication is actually translated into an HTTP-header but can concentrate on the logic.

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

AlertDefinition alertDefinition = new AlertDefinition(….);
Header acceptJson = new Header("Accept", "application/json")

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 by passing a ContentType and that we expect JSON back via the acceptJson that we defined earlier. For the URL, a query parameter with the name ‘resourceId’ and value ‘10001’ should be appended.

{
  "vendor": [
    {
      "name": "msc-loaded-modules",
      "displayName": "msc-loaded-modules",
      "description": "Number of loaded modules",
      "type": "gauge",
      "unit": "none",
      "tags": "tier=\"integration\"",
      "multi": false
    },
    {
      "name": "BufferPool_used_memory_mapped",
      "displayName": "BufferPool_used_memory_mapped",
      "description": "The memory used by the pool: mapped",
      "type": "gauge",
      "unit": "byte",
      "tags": "tier=\"integration\"",
      "multi": false
    },
    {
      "name": "BufferPool_used_memory_direct",
      "displayName": "BufferPool_used_memory_direct",
      "description": "The memory used by the pool: direct",
      "type": "gauge",
      "unit": "byte",
      "tags": "tier=\"integration\"",
      "multi": false
    }
  ]
}

One can then run the following queries (preceded by a ‘> ‘) and get the results below it.

# Get the names of all the objects below vendor
> vendor.name
[msc-loaded-modules, BufferPool_used_memory_mapped, BufferPool_used_memory_direct]

# Find the name of all objects below 'vendor' that have a unit of 'none'
> vendor.findAll { vendor -> vendor.unit == 'none' }.name
[msc-loaded-modules]

# Find objects below vendor that have a name of 'msc-loaded-modules' 
vendor.find { it.name = 'msc-loaded-modules' }
{unit=none, displayName=msc-loaded-modules, name=msc-loaded-modules, description=Number of loaded modules, type=gauge, tags=tier="integration", multi=false}

In the previous example, there is a mystical it, which represents the expression before the find keyword.

// Do an OPTIONS call to the remote and then translate into JsonPath
JsonPath jsonPath =
    given()
      .header("Accept",APPLICATION_JSON)
    .options("http://localhost:8080/metrics/vendor")
      .extract().body().jsonPath();

// Now find the buffer direct pool
Map<String,String> aMap = jsonPath.getMap("find {it.name == 'BufferPool_used_memory_direct'}");
// And make sure its display name is correct
assert directPool.get("displayName").equals("BufferPool_used_memory_direct");

Note, that the JSONPath expressions follow the Groovy GPath syntax. I have created a small JsonPath explorer that can be used to test queries against a given JSON input document.

when()
   .get("http://localhost:8080/metrics/base")
.then()
   .header("ETag",notNullValue())
   .body("scheduleId", hasItem( numericScheduleId)) 
   .body(containsString("total-started-thread-count"));

Here the containsString(), notNullValue() and hasItem() methods are such a matchers that look for the passed expression in all of the message body retrieved from the call to the REST API. Using the matches again make the test code very expressive and ensure good readability.