What is Assertion?
An assertion is a way to verify that the expected result and the actual result match or not in the test case. A test is considered successful ONLY if it is completed without throwing any exceptions. If the current value and the expected value match then the assertion passes and when the assertion passes nothing happens. But when an assertion fails, it will fail the test case.
There are various ways to perform assertions in API Testing. For API Testing, we are using Rest Assured, which uses either Hamcrest or JUnit assertions. We are going to discuss Hamcrest Assertions here.
What is Hamcrest?
Hamcrest is a framework for writing matcher objects, allowing ‘match’ rules to be defined declaratively. We do not need to add Hamcrest dependency explicitly as Rest-Assured 4.3.3 version includes itself. To know more about Hamcrest, please refer to this link.
We need to add the below dependency to use Hamcrest in the project.
<dependency>
<groupId>org.hamcrest</groupId>
<artifactId>hamcrest-all</artifactId>
<version>1.3</version>
<scope>test</scope>
</dependency>
To run all the scenarios mentioned below, please add the below mentioned dependencies to the POM.xml.
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.example</groupId>
<artifactId>RestAssured_TestNG_Demo</artifactId>
<version>1.0-SNAPSHOT</version>
<properties>
<hamcrest.version>1.3</hamcrest.version>
<testng.version>7.7.1</testng.version>
<rest-assured.version>5.3.0</rest-assured.version>
<maven.compiler.source>11</maven.compiler.source>
<maven.compiler.target>11</maven.compiler.target>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<!-- Hamcrest Dependency -->
<dependency>
<groupId>org.hamcrest</groupId>
<artifactId>hamcrest-all</artifactId>
<version>${hamcrest.version}</version>
<scope>test</scope>
</dependency>
<!-- TestNG Dependency -->
<dependency>
<groupId>org.testng</groupId>
<artifactId>testng</artifactId>
<version>${testng.version}</version>
</dependency>
<!-- Rest Assured -->
<dependency>
<groupId>io.rest-assured</groupId>
<artifactId>rest-assured</artifactId>
<version>${rest-assured.version}</version>
<scope>test</scope>
</dependency>
</dependencies>
</project>
Below is an example of a JSON Response. I will perform various assertions on this JSON Response.
To use hamcrest assertion, please import the Matchers class, static member.
Number related assertions
- equalTo – It checks whether the retrieved number from the response is equal to the expected number.
- greaterThan – checks extracted number is greater than the expected number.
- greaterThanOrEqualTo – checks whether the extracted number is greater than equal to the expected number.
- lessThan – It checks whether the retrieved number from the response is lesser than the expected number.
- lessThanOrEqualTo – It checks whether the retrieved number from the response is lesser than or equal to the expected number.
Below assertions are imported from the package shown below:-
import static org.hamcrest.Matchers.equalTo;
import static org.hamcrest.Matchers.greaterThan;
import static org.hamcrest.Matchers.greaterThanOrEqualTo;
import static org.hamcrest.Matchers.lessThanOrEqualTo;
import static org.hamcrest.Matchers.lessThan;
Below are examples to show the use of number-related assertions.
import io.restassured.RestAssured;
import io.restassured.http.ContentType;
import org.testng.annotations.Test;
import static org.hamcrest.Matchers.equalTo;
import static org.hamcrest.Matchers.greaterThan;
import static org.hamcrest.Matchers.greaterThanOrEqualTo;
import static org.hamcrest.Matchers.lessThanOrEqualTo;
import static org.hamcrest.Matchers.lessThan;
public class HamcrestNumberExample {
public String endpoint = "https://restful-booker.herokuapp.com/booking/1";
@Test
public void numberAssertions() {
RestAssured.given().contentType(ContentType.JSON)
.when().get(endpoint).then()
.body("totalprice", equalTo(164));
RestAssured.given().contentType(ContentType.JSON)
.when().get(endpoint)
.then().body("totalprice",greaterThan(100));
RestAssured.given().contentType(ContentType.JSON)
.when().get(endpoint)
.then().body("totalprice",greaterThanOrEqualTo(50));
RestAssured.given().contentType(ContentType.JSON)
.when().get(endpoint)
.then().body("totalprice",lessThan(1000));
RestAssured.given().contentType(ContentType.JSON)
.when().get(endpoint)
.then().body("totalprice",lessThanOrEqualTo(1000));
}
}
The output of the above program is
String related Assertions
- equalTo – It checks whether the extracted string from JSON is equal to the expected string.
- equalToIgnoringCase – It checks whether the extracted string from JSON is equal to the expected string without considering the case (small or capital).
- equalToIgnoringWhiteSpace – It checks whether the extracted string from JSON is equal to the expected string by considering the white spaces.
- containsString – It checks whether the extracted string from JSON contains the expected string as a substring.
- startsWith – It checks whether the extracted string from JSON is starting with a given string or character.
- endsWith – It checks whether the extracted string from JSON is ending with a given string or character.
Below assertions are imported from the package shown below:-
import static org.hamcrest.Matchers.containsString;
import static org.hamcrest.Matchers.endsWith;
import static org.hamcrest.Matchers.equalTo;
import static org.hamcrest.Matchers.equalToIgnoringCase;
import static org.hamcrest.Matchers.startsWith;
import static org.hamcrest.Matchers.equalToIgnoringWhiteSpace;
Below are examples to show the use of string-related assertions.
import io.restassured.RestAssured;
import io.restassured.http.ContentType;
import org.testng.annotations.Test;
import static org.hamcrest.Matchers.containsString;
import static org.hamcrest.Matchers.endsWith;
import static org.hamcrest.Matchers.equalTo;
import static org.hamcrest.Matchers.equalToIgnoringCase;
import static org.hamcrest.Matchers.startsWith;
import static org.hamcrest.Matchers.equalToIgnoringWhiteSpace;
public class HamcrestStringAssertions {
public String endpoint = "https://restful-booker.herokuapp.com/booking/1";
@Test
public void stringAssertions() {
RestAssured.given().contentType(ContentType.JSON)
.when().get(endpoint)
.then().body("firstname",equalTo("Mary"));
RestAssured.given().contentType(ContentType.JSON)
.when().get(endpoint)
.then().body("firstname",equalToIgnoringCase("mary"));
RestAssured.given().contentType(ContentType.JSON)
.when().get(endpoint)
.then().body("firstname",containsString("Mary"));
RestAssured.given().contentType(ContentType.JSON)
.when().get(endpoint)
.then().body("firstname",startsWith("M"));
RestAssured.given().contentType(ContentType.JSON)
.when().get(endpoint)
.then().body("firstname",endsWith("y"));
RestAssured.given().contentType(ContentType.JSON)
.when().get(endpoint)
.then().body("firstname",equalToIgnoringWhiteSpace(" Mary "));
}
}
The output of the above program is
nullValue – It checks whether the extracted response from JSON is NULL or Not.
Below assertions are imported from the package shown below:-
import static org.hamcrest.Matchers.hasKey;
import static org.hamcrest.Matchers.is;
import static org.hamcrest.Matchers.nullValue;
Below are examples to show the use of collection-related assertions.
import io.restassured.RestAssured;
import io.restassured.http.ContentType;
import org.testng.annotations.Test;
import static org.hamcrest.Matchers.is;
import static org.hamcrest.Matchers.nullValue;
public class HamcrestNullAssertion {
public String endpoint = "https://restful-booker.herokuapp.com/booking/1";
@Test
public void nullAssertion() {
RestAssured.given().contentType(ContentType.JSON)
.when().get(endpoint)
.then().body("totalprice1", is(nullValue()));
}
}
The output of the above program is
hasKey – It checks whether the extracted map has an expected key.
import io.restassured.RestAssured;
import io.restassured.http.ContentType;
import org.testng.annotations.Test;
import static org.hamcrest.Matchers.hasKey;
public class HamcrestHasKeyAssertion {
public String endpoint = "https://restful-booker.herokuapp.com/booking/1";
@Test
public void collectionAssertions() {
RestAssured.given().contentType(ContentType.JSON)
.when().get(endpoint)
.then().body("bookingdates",hasKey("checkin"));
}
}
The output of the above program is
Not Assertion
The not assertion inverts the meaning of the other assertions. For example, if you want to perform negative assertions, then we can use any assertions with NOT.
The below assertion is imported from the package shown below:-
import static org.hamcrest.Matchers.equalTo;
import static org.hamcrest.Matchers.not;
Below are examples to show the use of negative assertions.
import static org.hamcrest.Matchers.equalTo;
import static org.hamcrest.Matchers.not;
import io.restassured.RestAssured;
import io.restassured.http.ContentType;
import org.testng.annotations.Test;
public class HamcrestNotAssertion {
public String endpoint = "https://restful-booker.herokuapp.com/booking/1";
@Test
public void negativeAssertions() {
RestAssured.given().contentType(ContentType.JSON)
.when().get(endpoint)
.then().body("totalprice",not(equalTo(874)));
}
}
The output of the above program is
Multiple Assert Statements
In the below example, all 3 assertions will fail, but it will only execute the assertion and the first assertion is failed, then other assertions will not be executed.
import io.restassured.RestAssured;
import io.restassured.http.ContentType;
import org.testng.annotations.Test;
import static org.hamcrest.Matchers.equalTo;
public class HamcrestMultipleAssertions {
public String endpoint = "https://restful-booker.herokuapp.com/booking/1";
@Test
public void test1() {
RestAssured.given().contentType(ContentType.JSON)
.when().get(endpoint).then()
.body("firstname", equalTo("Jim"), // will fail
"lastname", equalTo("Smith"), // will fail
"totalprice", equalTo(314)); // will fail
}
}
The output of the above program is
To execute all the assertions present in the test case, we have to combine all the assertions into a single body, just like below. You can see that all the assertions failed, and they are shown in the response.
import io.restassured.RestAssured;
import io.restassured.http.ContentType;
import org.testng.annotations.Test;
import static org.hamcrest.Matchers.equalTo;
public class HamcrestMultipleAssertions {
public String endpoint = "https://restful-booker.herokuapp.com/booking/1";
@Test
public void test1() {
RestAssured.given().contentType(ContentType.JSON)
.when().get(endpoint).then()
.body("firstname", equalTo("Jim"), // will fail
"lastname", equalTo("Smith"), // will fail
"totalprice", equalTo(314)); // will fail
}
}
The output of the above program is
I have tried to show the use of a few of the most commonly used assertion methods. There are many more methods available in Hamcrest package. To know about other methods, write import static org.hamcrest.Matchers and add (.) at the end, it will show the list of all the methods available in Hamcrest.
We are done! Congratulations on making it through this tutorial and hope you found it useful! Happy Learning!!
QA Automation Expert 