Tutorials123: QA Automation with Rest Assured

How to Use Hamcrest Matchers in GET API via Rest Assured

Hamcrest is a framework for writing matcher objects, which allow 'match' rules to be defined declaratively. In Rest Assured, we use Hamcrest matchers to write expressive assertions for validating the API response.

We can use the Hamcrest Matchers API in a GET API test by employing the assertThat assertion within your testing framework (like JUnit or TestNG), where the actual value is an element extracted from the API's response body or headers, and the matcher defines the specific expectation.

The entire process follows three theoretical steps: Execute, Extract, and Assert.

You use the Hamcrest Matchers API in a GET API test by employing the assertThat assertion within your testing framework (like JUnit or TestNG), where the actual value is an element extracted from the API's response body or headers, and the matcher defines the specific expectation.

The entire process follows three theoretical steps: Execute, Extract, and Assert.

1. Execute the GET Request

First, your testing tool performs the GET request to the target API endpoint. The result of this execution is the API Response, which contains:

Status Line: The HTTP Status Code (example: 200 OK).
Headers: Metadata about the response (e.g., Content-Type, Date).
Body: The payload, usually in JSON or XML format.

2. Extract the Actual Value

This step involves parsing the response and pulling out the specific piece of data you want to validate.

Extraction from the Body: If the response body is JSON (which is common), you use a JSONPath or XPath expression (depending on the testing library, like REST Assured) to navigate the structure and isolate the required value.

Example: Extracting a product name from a nested JSON object.

Extraction from Headers: You extract a specific header value directly.

Example: Extracting the value of the Content-Type header.

Extraction of Status Code: You get the numeric HTTP status code.

This extracted data becomes the actual value (actual_value) for your Hamcrest assertion.

3. Assert with Hamcrest Matchers

The final step is the assertion, where the extracted value is verified against the expected condition using the Hamcrest syntax: assertThat(actual_value,matcher).

Maven Dependencies:

<dependencies>
    <!-- Rest Assured -->
    <dependency>
        <groupId>io.rest-assured</groupId>
        <artifactId>rest-assured</artifactId>
        <version>5.3.0</version>
        <scope>test</scope>
    </dependency>

    <!-- Hamcrest -->
    <dependency>
        <groupId>org.hamcrest</groupId>
        <artifactId>hamcrest</artifactId>
        <version>2.2</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Commonly Used Hamcrest Matchers

Matcher	Description
equalTo(value)	Check equality
hasItem(value)	Check if a list contains item
hasItems(val1, val2)	Check if list contains multiple items
not(value)	Asserts the opposite
containsString(str)	Check substring match
startsWith(str)	Check if string starts with

API to be tested:

https://reqres.in/api/users?page=2

API Response of above API

Java Code:

import io.restassured.RestAssured;
import static io.restassured.RestAssured.*;
import static org.hamcrest.Matchers.*;

public class GetApiHamcrestExample {
    public static void main(String[] args) {

        // Set base URI
        RestAssured.baseURI = "https://reqres.in";

        // GET Request with Hamcrest matchers for assertions
        given()
            .log().all()
        .when()
            .get("/api/users?page=2")
        .then()
            .log().all()
            .statusCode(200)
            .body("page", equalTo(2))  // validate page number
            .body("data.id", hasItems(7, 8, 9))  // check if certain user IDs are present
            .body("data.first_name", hasItem("Michael"))  // check first_name list contains value
            .body("support.url", containsString("reqres.in"))  // substring match
            .body("data.email[0]", startsWith("michael"));  // starts with
    }
}

Code Explanation:

(a) Set the base URI

(b) Send the API request

(d) Validate API response by Matchers API methods like equalTo(), hasItems(), hasItem(), etc.

Output:

Got 200 server code response as shown below in the response. The validated data from Matcher's API is also mentioned below.

Request:
GET https://reqres.in/api/users?page=2

Response:
200 OK
...
Assertions:
page == 2
data.id contains 7, 8, 9
data.first_name contains "Michael"
support.url contains "reqres.in"
data.email[0] startsWith "michael"

How to validate Response by Matchers API in Rest Assured

How to Use Hamcrest Matchers in GET API via Rest Assured