This article explores how to use Java REST-assured to efficiently assert JSON responses in REST API testing. REST-assured is a Java library specifically designed for testing REST APIs, allowing developers to make HTTP calls and verify responses with ease. When working with APIs, verifying JSON response structures and values is essential to ensure data accuracy and consistency across applications. The article will also focus on asserting properties within arrays in JSON responses.<\/p>\n
To understand how we can assert JSON responses effectively, let\u2019s start with an overview of a sample JSON structure that represents a typical API response. This structure will serve as the basis for illustrating different assertion techniques using Java REST-assured.<\/p>\n
Consider the following JSON response from an API endpoint that provides user session information:<\/p>\n
\n{\n \"activeSession\": true,\n \"token\": \"abc123\",\n \"details\": [\n {\n \"accountType\": 2,\n \"accountDescription\": \"Premium\",\n \"username\": \"mr_fish\",\n \"clientId\": 42\n }\n ]\n}\n\n<\/pre>\nThis JSON has an array field details<\/code>, and our goal is to verify the values of the properties within that array.<\/p>\nHere is a controller class, SessionInfoController<\/code>, to handle the HTTP request and produce the above JSON response.<\/p>\n\n@RestController\n@RequestMapping(\"\/api\")\npublic class SessionInfoController {\n\n @GetMapping(\"\/session-info\")\n public Map<String, Object> getSessionInfo() {\n\n Map<String, Object> sessionInfo = Map.of(\n \"activeSession\", true,\n \"token\", \"abc123\",\n \"details\", Collections.singletonList(\n Map.of(\n \"accountType\", 2,\n \"accountDescription\", \"Premium\",\n \"username\", \"mr_fish\",\n \"clientId\", 42\n )\n )\n );\n\n return sessionInfo;\n }\n}\n<\/pre>\n2. Setting Up REST-assured<\/h2>\n
To begin, it\u2019s essential to have REST-assured configured in the project. Adding REST-assured to the project dependencies will enable testing of JSON responses. For configuration with Maven, include the following dependency in the pom.xml<\/code> file:<\/p>\n\n <dependency>\n <groupId>io.rest-assured<\/groupId>\n <artifactId>rest-assured<\/artifactId>\n <version>5.4.0<\/version>\n <scope>test<\/scope>\n <\/dependency>\n<\/pre>\n3. Example Test: Asserting Array Properties<\/h2>\n
Consider an endpoint \/session-info<\/code> that returns this JSON data. The test will be structured to validate each property\u2019s values precisely. Begin by setting REST-assured\u2019s base URI to point to the API server. Then, write the test case using REST-assured\u2019s given()<\/code>, when()<\/code>, and then()<\/code> methods to define assertions for each JSON field, ensuring the response data aligns with expected values. <\/p>\nThe body()<\/code> method in REST-assured is essential for checking specific fields in a JSON response. Used with equalTo()<\/code>, it verifies that each field has the correct value, ensuring the data is accurate and consistent.<\/p>\n\npublic class SessionInfoTest {\n\n @BeforeAll\n public static void setup() {\n RestAssured.baseURI = \"http:\/\/localhost:8080\/api\";\n }\n\n @Test\n public void testSessionInfoResponse() {\n given()\n .contentType(ContentType.JSON)\n .when()\n .get(\"\/session-info\")\n .then()\n .statusCode(200)\n .body(\"activeSession\", equalTo(true))\n .body(\"token\", equalTo(\"abc123\"))\n .body(\"details\", hasSize(1))\n .body(\"details[0].accountType\", equalTo(2))\n .body(\"details[0].accountDescription\", equalTo(\"Premium\"))\n .body(\"details[0].username\", equalTo(\"mr_fish\"))\n .body(\"details[0].clientId\", equalTo(42));\n }\n}\n<\/pre>\nHere\u2019s an explanation of each assertion.
<\/div> <\/div><\/p>\n\nbody(\"activeSession\", equalTo(true))<\/code>: Asserts that the activeSession<\/code> property is true<\/code>.<\/li>\nbody(\"token\", equalTo(\"abc123\"))<\/code>: Verifies that the token<\/code> field matches the expected string \"abc123\"<\/code>.<\/li>\nbody(\"details\", hasSize(1))<\/code>: Checks that the details<\/code> array has exactly one object.<\/li>\nbody(\"details[0].accountType\", equalTo(2))<\/code>: Asserts that the accountType<\/code> field in the first element of details<\/code> is 2<\/code>.<\/li>\nbody(\"details[0].accountDescription\", equalTo(\"Premium\"))<\/code>: Verifies the accountDescription<\/code> field is \"Premium\"<\/code>.<\/li>\nbody(\"details[0].username\", equalTo(\"mr_fish\"))<\/code>: Checks the username<\/code> field is \"mr_fish\"<\/code>.<\/li>\nbody(\"details[0].clientId\", equalTo(42))<\/code>: Asserts that the clientId<\/code> field in the first element of details<\/code> is 42<\/code>.<\/li>\n<\/ul>\n3.1 Asserting the Entire JSON Body as a String<\/h3>\n
REST-assured provides the .extract()<\/code> method, which allows us to capture the response after performing assertions. This approach is useful for checking the full structure and content of the response in one assertion. <\/p>\n\n @Test\n public void testWholeJsonBody() {\n \/\/ Extract the JSON response body as a string\n String body = given()\n .get(\"\/session-info\")\n .then()\n .extract()\n .body()\n .asString();\n\n \/\/ Assert the entire JSON structure as a single string\n assertThat(body)\n .isEqualTo(\"{\\\"details\\\":[{\\\"accountDescription\\\":\\\"Premium\\\",\\\"clientId\\\":42,\\\"username\\\":\\\"mr_fish\\\",\\\"accountType\\\":2}],\\\"activeSession\\\":true,\\\"token\\\":\\\"abc123\\\"}\");\n }\n}\n\n<\/pre>\n\n- Extracting JSON as String<\/strong>: The
given().get(\"\/session-info\").then().extract().body().asString()<\/code> retrieves the JSON response body from the \/session-info<\/code> endpoint as a single string.<\/li>\n- Asserting the JSON String<\/strong>: Using
assertThat(body).isEqualTo(...)<\/code>, we directly compare the extracted JSON string to the expected JSON string to ensure that the entire response body matches exactly.<\/li>\n<\/ul>\n4. Asserting With JSONAssert<\/h2>\n
Comparing JSON as plain strings can lead to test failures due to field ordering differences. We might encounter errors which indicate that the actual JSON response has fields in a different order than expected. JSON objects do not enforce a specific order for fields, so this discrepancy can occur without affecting the content’s meaning.<\/p>\n
To handle this, we can use JSONAssert<\/strong> to perform a relaxed comparison that ignores the order of fields. Here\u2019s how to modify the test to use JSONAssert<\/strong> for an order-independent assertion. <\/p>\n\n @Test\n void whenGetBody_thenCanCompareByWholeString() throws Exception {\n \/\/ Extract the JSON response body as a string\n String body = given()\n .get(\"\/session-info\")\n .then()\n .extract()\n .body()\n .asString();\n\n \/\/ Expected JSON string\n String expectedJson = \"{\\\"activeSession\\\":true,\\\"token\\\":\\\"abc123\\\",\\\"details\\\":[{\\\"accountType\\\":2,\\\"accountDescription\\\":\\\"Premium\\\",\\\"username\\\":\\\"mr_fish\\\",\\\"clientId\\\":42}]}\";\n\n \/\/ Assert JSON, ignoring field order\n JSONAssert.assertEquals(expectedJson, body, JSONCompareMode.LENIENT);\n }\n<\/pre>\n\nJSONAssert.assertEquals()<\/code>: This method allows for JSON comparisons that are tolerant of field order, preventing test failures due to differences in JSON key ordering.<\/li>\nJSONCompareMode.LENIENT<\/code>: This mode ignores field order, comparing only the structure and values within the JSON data. This approach ensures that tests pass as long as all required fields and values are present, regardless of their order.<\/li>\n<\/ul>\n5. Asserting JSON with JSON Assert Hamcrest and JSON Unit Hamcrest<\/h2>\n
When dealing with JSON responses that contain dynamic or changeable fields, JSON Assert Hamcrest<\/strong> and JSONUnit Hamcrest<\/strong> provide effective ways to handle these variances while allowing the test to focus on expected fields and values. Both libraries can be used in combination with REST-assured for flexible assertions that ignore extra fields.<\/p>\nAdding Dependencies for JSON Assert Hamcrest and JSONUnit Hamcrest<\/strong><\/p>\nTo use JSON Assert Hamcrest and JSON Unit Hamcrest, the following dependencies should be added to the pom.xml<\/code>:<\/p>\n\n<dependency>\n <groupId>uk.co.datumedge<\/groupId>\n <artifactId>hamcrest-json<\/artifactId>\n <version>0.2<\/version>\n<\/dependency>\n\n<dependency>\n <groupId>net.javacrumbs.json-unit<\/groupId>\n <artifactId>json-unit<\/artifactId>\n <version>2.27.0<\/version>\n <scope>test<\/scope>\n<\/dependency>\n\n<\/pre>\n5.1 Using JSON Assert Hamcrest<\/h3>\n