This post provides a step-by-step guide on how to add a cucumber layer on top of api tests written in REST-assured.

REST-assured’s DSL already provides a BDD-style writing of tests in the Given-When-Then format, but it is still buried in the code. In other words, if you want to see what scenarios are covered, you still have to dig down into the api tests and read the code. There are no feature files.

The aim of this post is to refactor existing REST-assured api tests by adding cucumber and feature files, so that scenarios can be read more clearly without having to look at the underlying code.

REST-assured API Tests

In this example, we will write code to test user creation api.

First, we have a standalone REST-assured and JUnit Test, which resides in:

src/test/java/io.devqa/scenarios

import io.restassured.RestAssured;
import io.restassured.http.ContentType;
import io.restassured.response.Response;
import org.junit.jupiter.api.*;
import static io.restassured.RestAssured.given;

public class UserTests {

    private static String path;

    private static String validRequest = "{\n" +
            "  \"username\": \"test-api-user\",\n" +
            "  \"email\": \"test-api-user@email.com\",\n" +
            "  \"password\": \"Passw0rd123!\",\n" +
            "  \"name\": \"Test Api-User\" \n}";

    @BeforeAll
    public static void setConfig() {
        RestAssured.baseURI = "https://localhost:8080";
        path = "/users";
    }

    @Test
    public void shouldBeAbleToCreateNewUser() {
        Response createUser = given()
                .auth()
                .preemptive()
                .basic("MY_USERNAME", "MY_PASSWORD")
                .header("Accept", ContentType.JSON.getAcceptHeader())
                .contentType(ContentType.JSON)
                .body(validRequest)
                .post(path)
                .then().extract().response();
        Assertions.assertEquals(201, createUser.getStatusCode());

        String username = createUser.jsonPath().get("username");
        String email = createUser.jsonPath().get("email");
        String name = createUser.jsonPath().get("name");
        String id = createUser.jsonPath().get("id");

        Assertions.assertEquals("test-api-user", username);
        Assertions.assertEquals("test-api-user@email.com", email);
        Assertions.assertEquals("Test Api-User", name);
        Assertions.assertNotNull(id);
    }
}

The above test can be run directly from the class as it can be invoked by JUnit.

The setConfig() method sets the pre-requisite. The test method does the actions (sending the request) and then asserting on the response code and response payload.

Next, we will look at how to put the cucumber layer on top of the above REST-assured api test.

Cucumber and REST-assured API Tests

The first thing we need to do is to add the cucumber dependency in our project.

Using Gradle, in our build.gradle file, we put these under the dependencies:

dependencies {
    testCompile "io.cucumber:cucumber-java:6.2.2"
    testCompile "io.cucumber:cucumber-junit:6.2.2"
}

We also need to create a task in the build.gradle file to run the cucumber feature files which contain the scenarios:

task cucumber() {
    dependsOn assemble, compileTestJava
    doLast {
        mkdir 'build/test-results/'
        javaexec {
            main = "io.cucumber.core.cli.Main"
            classpath = configurations.cucumberRuntime + sourceSets.main.output + sourceSets.test.output
            args = ['--plugin', 'pretty', '--plugin', 'html:build/test-results/functional.html', '--plugin', 'junit:build/test-results/functional.xml','--tags', '@functional', '--glue', 'scenarios', 'src/test/resources']
        }
    }
}

Project Structure for Cucumber

We also need to modify our project structure to accommodate the changes for cucumber.

The feature files will be saved in:

src/test/resources/scenarios

The step definitions will be save in

src/test/java/scenarios

Next, we will create a feature file called UserScenarios.feature and put it under src/test/resources/scenarios folder.

The feature file will look like:

@functional
Feature: User Scenarios

  Scenario: I should be able to create a new user
    Given the users endpoint exists
    When I send a valid create user payload
    Then response status code should be 201
    And create user response should be valid

Now we need to dismantle our REST-assured JUnit test to write step definitions that can be glued to the statements in our feature file.

import io.cucumber.java.en.And;
import io.cucumber.java.en.Given;
import io.cucumber.java.en.Then;
import io.cucumber.java.en.When;

import io.restassured.RestAssured;
import io.restassured.http.ContentType;
import io.restassured.response.Response;

import org.junit.jupiter.api.Assertions;
import static io.restassured.RestAssured.given;

public class UserScenarios {

    private String path;
    private Response response;

    private String validRequest = "{\n" +
            "  \"username\": \"test-api-user\",\n" +
            "  \"email\": \"test-api-user@email.com\",\n" +
            "  \"password\": \"Passw0rd123!\",\n" +
            "  \"name\": \"Test Api-User\" \n}";


    @Given("the users endpoint exists")
    public void preReq() {
        RestAssured.baseURI = "https://localhost:8080";
        path = "/users";
    }

    @When("I send a valid create user payload")
    public void createUser() {
        response = given()
                .auth()
                .preemptive()
                .basic("MY_USERNAME", "MY_PASSWORD")
                .header("Accept", ContentType.JSON.getAcceptHeader())
                .contentType(ContentType.JSON)
                .body(validRequest)
                .post(path)
                .then().extract().response();
    }

    @Then("response status code should be {int}")
    public void checkResponseStatusCode(int code) {
        Assertions.assertEquals(code, response.getStatusCode());
    }

    @And("create user response should be valid")
    public void verifyResponse() {
        String username = response.jsonPath().get("username");
        String email = response.jsonPath().get("email");
        String name = response.jsonPath().get("name");
        String id = response.jsonPath().get("id");

        Assertions.assertEquals("test-api-user", username);
        Assertions.assertEquals("test-api-user@email.com", email);
        Assertions.assertEquals("Test Api-User", name);
        Assertions.assertNotNull(id);
    }
}

As can be seen in the above step definitions, for every line in the scenario in the feature file, we have a corresponding step definition.

The method with the Given annotation sets the pre-requisites. The method with the When annotation does the action of sending the request and finally the method with the Then annotation performs the assertions on the response.

To execute the above, all we need to do is to execute the command ./gradle cucumber in a terminal from the project root.

Once the tests have run, the results are saved in build/test-results/functional.html.

Conclusion

In this post, we covered a step-by-step guide on how to add a cucumber layer on top of the REST-assured API tests. By doing so, we can write our scenarios in feature files which become more readable by non-technical people.

#api-testing #cucumber #rest-assured