Exploring the Jersey Test Framework

1. Overview

In this tutorial, we’re going to take a look at the Jersey Test Framework and see how we can use it to quickly write integration tests.

As we’ve already seen in previous articles, Jersey is an open source framework for developing RESTful Web Services. We can learn more about Jersey in our introduction to creating an API with Jersey and Spring article – here.

2. Application Setup

The Jersey Test Framework is a tool to help us verify the correct implementation of our server-side components. As we’ll see later, it provides a fast and fuss-free way for writing integration tests and can handle communicating with our HTTP APIs very well.

Likewise, it works almost out-of-the-box and it’s easy to integrate with our Maven-based projects. The framework is primarily based on JUnit although it is possible to use with TestNG as well which makes it usable in almost all environments.

In the next section, we’ll see which dependencies we need to add to our application in order to use the framework.

2.1. Maven Dependencies

First of all, let’s add the Jersey Test Framework core dependency to our pom.xml:

<dependency>
    <groupId>org.glassfish.jersey.test-framework</groupId>
    <artifactId>jersey-test-framework-core</artifactId>
    <version>3.1.1</version>
    <scope>test</scope>
</dependency>

As always, we can get the latest version from Maven Central.

Nearly almost all Jersey tests use the defacto Grizzly test container factory, which we will also need to add:

<dependency>
    <groupId>org.glassfish.jersey.test-framework.providers</groupId>
    <artifactId>jersey-test-framework-provider-grizzly2</artifactId>
    <version>3.1.1</version>
    <scope>test</scope>
</dependency>

Again we can find the latest version in Maven Central.

3. Getting Started

In this next section, we’ll cover the basic steps needed to write a simple test.

We’re going to begin by testing the simple Greetings resource on our server:

@Path("/greetings")
public class Greetings {

    @GET
    @Path("/hi")
    public String getHiGreeting() {
        return "hi";
    }
}

3.1. Configuring the Test

Now let’s define our test class:

public class GreetingsResourceIntegrationTest extends JerseyTest {

    @Override
    protected Application configure() {
        return new ResourceConfig(Greetings.class);
    }
    //...
}

We can see in the above example that to develop a test using the Jersey Test Framework our test needs to subclass JerseyTest.

Next, we override the configure method which returns a custom resource configuration for our test and only contains the Greetings resource. This is, of course, the resource that we wish to test.

3.2. Writing Our First Test

Let’s start by testing a simple GET request from our greetings API:

@Test
public void givenGetHiGreeting_whenCorrectRequest_thenResponseIsOkAndContainsHi() {
    Response response = target("/greetings/hi").request()
        .get();

    assertEquals("Http Response should be 200: ", Status.OK.getStatusCode(), response.getStatus());
    assertEquals("Http Content-Type should be: ", MediaType.TEXT_HTML, response.getHeaderString(HttpHeaders.CONTENT_TYPE));

    String content = response.readEntity(String.class);
    assertEquals("Content of ressponse is: ", "hi", content);
}

Notice that we have full access to the HTTP response – so we can do things like checking the status code to make sure the operation was actually successful, or work with the actual body of the response.

Let’s explain in more detail what we do in the above example:

1. Send an HTTP GET request to ‘/greetings/hi’
2. Check the HTTP status code and content type response headers
3. Test the contents of the response contains the string “hi”

4. Testing GET to Retrieve Resources

Now, that we’ve seen the basic steps involved in creating tests. Let’s test the simple Fruit API that we introduced in the excellent Jersey MVC Support article.

4.1. Get Plain JSON

In the below example we’re working with the response body as a standard JSON String:

@Test
public void givenFruitExists_whenSearching_thenResponseContainsFruit() {
    final String json = target("fruit/search/strawberry").request()
        .get(String.class);
    assertThat(json, containsString("{\"name\":\"strawberry\",\"weight\":20}"));
}

4.2. Get Entity Instead of JSON

We can also map the response directly to a Resource entity class – for example:

   @Test
    public void givenFruitExists_whenSearching_thenResponseContainsFruitEntity() {
        final Fruit entity = target("fruit/search/strawberry").request()
            .get(Fruit.class);

        assertEquals("Fruit name: ", "strawberry", entity.getName());
        assertEquals("Fruit weight: ", Integer.valueOf(20), entity.getWeight());
    }

This time, we specify the Java type the response entity will be converted to in the get method – a Fruit object.

5. Testing POST to Create Resources

In order to create a new Resource in our API – we will make good use of POST requests. In the next section, we’ll see how to test this part of our API.

5.1. Post Plain JSON

Let’s start by posting a plain JSON String to test the creation of a new fruit resource:

@Test
public void givenCreateFruit_whenJsonIsCorrect_thenResponseCodeIsCreated() {
    Response response = target("fruit/created").request()
        .post(Entity.json("{\"name\":\"strawberry\",\"weight\":20}"));

    assertEquals("Http Response should be 201 ", Status.CREATED.getStatusCode(), response.getStatus());
    assertThat(response.readEntity(String.class), containsString("Fruit saved : Fruit [name: strawberry colour: null]"));
}

In the above example, we make use of the post method which takes an Entity object parameter. We use the convenient json method to create an entity from the corresponding JSON string.

5.2. Post Entity Instead of JSON

As we’ve already seen with get requests we can also post a Resource entity class directly – for example:

@Test
public void givenCreateFruit_whenFruitIsInvalid_thenResponseCodeIsBadRequest() {
    Fruit fruit = new Fruit("Blueberry", "purple");
    fruit.setWeight(1);

    Response response = target("fruit/create").request(MediaType.APPLICATION_JSON_TYPE)
        .post(Entity.entity(fruit, MediaType.APPLICATION_JSON_TYPE));

    assertEquals("Http Response should be 400 ", 400, response.getStatus());
    assertThat(response.readEntity(String.class), containsString("Fruit weight must be 10 or greater"));
}

This time we use the entity method to post our Fruit entity and also specify the media type as JSON.

5.3. Form Submissions Using POST

In our final post example we will see how to test form submissions via a post request:

@Test
public void givenCreateFruit_whenFormContainsNullParam_thenResponseCodeIsBadRequest() {
    Form form = new Form();
    form.param("name", "apple");
    form.param("colour", null);
    
    Response response = target("fruit/create").request(MediaType.APPLICATION_FORM_URLENCODED)
        .post(Entity.form(form));

    assertEquals("Http Response should be 400 ", 400, response.getStatus());
    assertThat(response.readEntity(String.class), containsString("Fruit colour must not be null"));
 }

Similarly, we make use of the Entity class but this time pass a form which contains a number of parameters to our post request.

6. Testing Other HTTP Verbs

Sometimes we need to test other HTTP endpoints such as PUT and DELETE. This is of course perfectly possible using the Jersey Test Framework.

Let’s see a simple PUT example:

@Test
public void givenUpdateFruit_whenFormContainsBadSerialParam_thenResponseCodeIsBadRequest() {
    Form form = new Form();
    form.param("serial", "2345-2345");

    Response response = target("fruit/update").request(MediaType.APPLICATION_FORM_URLENCODED)
        .put(Entity.form(form));

    assertEquals("Http Response should be 400 ", 400, response.getStatus());
    assertThat(response.readEntity(String.class), containsString("Fruit serial number is not valid"));
}

Once we have called the request method, we can invoke any HTTP method on the current request object.

7. Additional Features

The Jersey test framework contains a number of additional configuration properties which can help aid debugging and testing.

In the next example we’ll see how to programmatically enable a feature with a given name:

public class FruitResourceIntegrationTest extends JerseyTest {

    @Override
    protected Application configure() {
        enable(TestProperties.LOG_TRAFFIC);
        enable(TestProperties.DUMP_ENTITY);
        //...

When we create and configure our Jersey application under test. We can also enable additional properties. In this case, we enable two logging properties – LOG_TRAFFIC and DUMP_ENTITY which will provide useful additional logging and debug information during test runs.

8. Supported Containers

As we’ve already mentioned the defacto container used when writing tests with the Jersey Test Framework is Grizzly. However, a number of other containers are supported:

• In-Memory container
• HttpServer from Oracle JDK
• Simple container (org.simpleframework.http
• Jetty container (org.eclipse.jetty)

For more information on how to configure these containers, please see the documentation here.

9. Conclusion

To summarize, in this tutorial, we’ve explored the Jersey Test Framework. First, we started by introducing how to configure the Jersey Test Framework and then we saw how to write a test for a very simple API.

In the next section, we saw how to write tests for a variety of GET and POST API endpoints. Finally, we looked at some additional features and the containers that the Jersey Test Framework supports.