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.
- Extraction from Headers: You extract a specific header value directly.
- 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
(c) Get the API response nd log on console
(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"
Suggested Posts:
1. Test Basic Authentication in RestAssured
2. Test Preemptive Authentication in RestAssured
3. Test Form Authentication in RestAssured
4. Validate Keys in API in RestAssured
5. Validate XML Schema in RestAssured
