Introduction to Java integration testing for a RESTful API

This post will focus on basic principles and mechanics of writing Java integration tests for a RESTful API (with a JSON payload). The goal is to provide an introduction to the technologies and to write some tests for basic correctness. The examples will consume the latest version of the GitHub REST API.

For an internal application, this kind of testing will usually run as a late step in a Continuous Integration process, consuming the REST API after it has already been deployed.

When testing a REST resource, there are usually a few orthogonal responsibilities the tests should focus on:

  • the HTTP response code
  • other HTTP headers in the response
  • the payload (JSON, XML)

Each test should only focus on a single responsibility and include a single assertion. Focusing on a clear separation always has benefits, but when doing this kind of black box testing it’s even more important, as the general tendency is to write complex test scenarios in the very beginning.

Another important aspect of the integration tests is adherence to the Single Level of Abstraction Principle – the logic within a test should be written at a high level. Details such as creating the request, sending the HTTP request to the server, dealing with IO, etc should not be done inline but via utility methods.

Testing the HTTP response code

View the code on Gist.

This is a rather simple test, which verifies that a basic happy path is working, without adding to much complexity to the test suite. If, for whatever reason it fails, then there is no need to look at any other test for this URL until this is fixed. Because verifying the response code is one of the most common assertions of the integration testing suite, a custom assertion is used.

View the code on Gist.

Testing other headers of the HTTP response

View the code on Gist.

This ensures that the response when requesting the details of the user is actually JSON. There is a logical progression of the functionality under test – first the response code, to ensure that the request was OK, then the mime type of the request, and only then the verification that the actual JSON is correct.

Testing the JSON payload of the HTTP response

View the code on Gist.

In this case, I know the default representation of GitHub resources is JSON, but usually the Content-Type header of the response should be tested alongside the Accept header of the request – the client asks for a particular type of representation via Accept, which the server should honor.

The Utilities for testing

Here are the utilities that enable the tests to remain at a higher level of abstraction:

  • decorate the HTTP request with the JSON payload (or directly with the POJO):

View the code on Gist.

  • retrieve the JSON payload (or directly the POJO) from the HTTP response:

View the code on Gist.

  • conversion utilities to and from java object (POJO) to JSON:

View the code on Gist.

Dependencies

The utilities and tests make use of of the following libraries, all available in Maven central:

Conclusion

This is only one part of what the complete integration testing suite should be. The tests focus on ensuring basic correctness for the REST API, without going into more complex scenarios, discoverability of the API, consumption of different representations for the same resource or other more advanced areas. I will address these in a further post, in the meantime checkout the full project on github.

If you read this far, you should follow me on twitter here.

, , ,

  • http://twitter.com/fuchshuber Josef Fuchshuber

    We are using REST-assured to test and validate our REST-API. In combination with the maven-failsafe-plugin, maven-jetty-plugin and Jenkins everything works fine! Link: http://code.google.com/p/rest-assured/

    • vivek pradhan

      can u post your REST-assured code / send it to me. I am also looking at using REST assured.

      • baeldung

        Sure, I’m planning to write a folloup article using only rest-assured; for the time being however, you can always check out the github project (link at the end of the post) for about 300 tests done with rest-assured.
        Eugen.

  • http://qweojidxz.com Terisa

    Good post, really good. The information helped me.

  • http://europelibertyreserve.com/ liberty reserve

    I like Your Article about Integration testing of a REST API | baeldung Perfect just what I was looking for! .

  • http://gapkandroid.blogspot.com/ Android Apps

    I like your article about Integration testing of a REST API | baeldung Perfect just what I was looking for! .

  • Anonymous

    This is very helpful series of articles. Very nice job for a newbie who want to start with Spring3.1 restful. I am wandering how can I test the post/put/delete methods from command line, for example using curl. I am able to do the get. But for the post, it always complains ” The server refused this request because the request etity is in a format not supported by the requested resource for the requested m
    thod ().”. My understanding is that the api is expecting foo entity. But how could this be sent from command line (or javascript eventually). My command line is something like:

    curl -u eparaschiv:eparaschiv -v -H “Accept: application/json” -H “Content-type: application/*” -X POST -d ‘{“Foo”:{“name”:”foo4″}}’ http://localhost:8080/rest/api/admin/foo/

    I am wondering if anyone here knows how to do this.

    Thanks a lot,
    Simon

    • Anonymous

      Hi,
      Just a quick note about your curl command – the Accept header is application/json, so your Content-type should be the same. Other than that, you should be able to consume the API via curl commands without any problems. Also, you are asking how to send the Foo resource in the POST, but it looks like you’re already doing that, so you should be fine.
      Thanks for the interesting feedback.
      Eugen.

      • Anonymous

        Thanks for the replay. I tried Context-type with application/json, it’s giving me same error message.I tried different way on the data part and with no luck either.

  • http://update-seputar-software.blogspot.com/2011/12/ultrabook-notebook-tipis-harga-murah.html Harga Notebook

    4567uiyhlkjmbvncxz Glad to be one of many visitors on this amazing website : D.
    http://update-seputar-software.blogspot.com/2011/12/ultrabook-notebook-tipis-harga-murah.html