Introduction to JSONassert

1. Overview

In this article, we’ll have a look at the JSONAssert library – a library focused on understanding JSON data and writing complex JUnit tests using that data.

2. Maven Dependency

First, let’s add the Maven dependency:

<dependency>
    <groupId>org.skyscreamer</groupId>
    <artifactId>jsonassert</artifactId>
    <version>1.5.0</version>
</dependency>

Please check out the latest version of the library here.

3. Working With Simple JSON Data

3.1. Using the LENIENT Mode

Let’s start our tests with a simple JSON string comparison:

String actual = "{id:123, name:\"John\"}";
JSONAssert.assertEquals(
  "{id:123,name:\"John\"}", actual, JSONCompareMode.LENIENT);

The test will pass as the expected JSON string, and the actual JSON string are the same.

The comparison mode LENIENT means that even if the actual JSON contains extended fields, the test will still pass:

String actual = "{id:123, name:\"John\", zip:\"33025\"}";
JSONAssert.assertEquals(
  "{id:123,name:\"John\"}", actual, JSONCompareMode.LENIENT);

As we can see, the real variable contains an additional field zip which is not present in the expected String. Still, the test will pass.

This concept is useful in the application development. This means that our APIs can grow, returning additional fields as required, without breaking the existing tests.

3.2. Using the STRICT Mode

The behavior mentioned in the previous sub-section can be easily changed by using the STRICT comparison mode:

String actual = "{id:123,name:\"John\"}";
JSONAssert.assertNotEquals(
  "{name:\"John\"}", actual, JSONCompareMode.STRICT);

Please note the use of assertNotEquals() in the above example.

3.3. Using a Boolean Instead of JSONCompareMode

The compare mode can also be defined by using an overloaded method that takes boolean instead of JSONCompareMode where LENIENT = false and STRICT = true:

String actual = "{id:123,name:\"John\",zip:\"33025\"}";
JSONAssert.assertEquals(
  "{id:123,name:\"John\"}", actual, JSONCompareMode.LENIENT);
JSONAssert.assertEquals(
  "{id:123,name:\"John\"}", actual, false);

actual = "{id:123,name:\"John\"}";
JSONAssert.assertNotEquals(
  "{name:\"John\"}", actual, JSONCompareMode.STRICT);
JSONAssert.assertNotEquals(
  "{name:\"John\"}", actual, true);

3.4. The Logical Comparison

As described earlier, JSONAssert makes a logical comparison of the data. This means that the ordering of elements does not matter while dealing with JSON objects:

String result = "{id:1,name:\"John\"}";
JSONAssert.assertEquals(
  "{name:\"John\",id:1}", result, JSONCompareMode.STRICT);
JSONAssert.assertEquals(
  "{name:\"John\",id:1}", result, JSONCompareMode.LENIENT);

Strict or not, the above test will pass in both the cases.

Another example of logical comparison can be demonstrated by using different types for the same value:

JSONObject expected = new JSONObject();
JSONObject actual = new JSONObject();
expected.put("id", Integer.valueOf(12345));
actual.put("id", Double.valueOf(12345));

JSONAssert.assertEquals(expected, actual, JSONCompareMode.LENIENT);

The first thing to note here is that we are using JSONObject instead of a String as we did for earlier examples. The next thing is that we have used Integer for expected and Double for actual. The test will pass irrespective of the types because the logical value 12345 for both of them is same.

Even in the case when we have nested object representation, this library works pretty well:

String result = "{id:1,name:\"Juergen\", 
  address:{city:\"Hollywood\", state:\"LA\", zip:91601}}";
JSONAssert.assertEquals("{id:1,name:\"Juergen\", 
  address:{city:\"Hollywood\", state:\"LA\", zip:91601}}", result, false);

3.5. Assertions With User Specified Messages

All the assertEquals() and assertNotEquals() methods accept a String message as the first parameter. This message provides some customization to our test cases by providing a meaningful message in the case of test failures:

String actual = "{id:123,name:\"John\"}";
String failureMessage = "Only one field is expected: name";
try {
    JSONAssert.assertEquals(failureMessage, 
      "{name:\"John\"}", actual, JSONCompareMode.STRICT);
} catch (AssertionError ae) {
    assertThat(ae.getMessage()).containsIgnoringCase(failureMessage);
}

In the case of any failure, the entire error message will make more sense:

Only one field is expected: name 
Unexpected: id

The first line is the user specified message and the second line is the additional message provided by the library.

4. Working With JSON Arrays

The comparison rules for JSON arrays differ a little, compared to JSON objects.

4.1. The Order of the Elements in an Array

The first difference is that the order of elements in an array has to be exactly same in STRICT comparison mode. However, for LENIENT comparison mode, the order does not matter:

String result = "[Alex, Barbera, Charlie, Xavier]";
JSONAssert.assertEquals(
  "[Charlie, Alex, Xavier, Barbera]", result, JSONCompareMode.LENIENT);
JSONAssert.assertEquals(
  "[Alex, Barbera, Charlie, Xavier]", result, JSONCompareMode.STRICT);
JSONAssert.assertNotEquals(
  "[Charlie, Alex, Xavier, Barbera]", result, JSONCompareMode.STRICT);

This is pretty useful in the scenario where the API returns an array of sorted elements, and we want to verify if the response is sorted.

4.2. The Extended Elements in an Array

Another difference is that extended elements are not allowed when the dealing with JSON arrays:

String result = "[1,2,3,4,5]";
JSONAssert.assertEquals(
  "[1,2,3,4,5]", result, JSONCompareMode.LENIENT);
JSONAssert.assertNotEquals(
  "[1,2,3]", result, JSONCompareMode.LENIENT);
JSONAssert.assertNotEquals(
  "[1,2,3,4,5,6]", result, JSONCompareMode.LENIENT);

The above example clearly demonstrates that even with the LENIENT comparison mode, the items in the expected array has to match the items in the real array exactly. Adding or removing, even a single element, will result in a failure.

4.3. Array Specific Operations

We also have a couple of other techniques to verify the contents of the arrays further.

Suppose we want to verify the size of the array. This can be achieved by using a concrete syntax as the expected value:

String names = "{names:[Alex, Barbera, Charlie, Xavier]}";
JSONAssert.assertEquals(
  "{names:[4]}", 
  names, 
  new ArraySizeComparator(JSONCompareMode.LENIENT));

The String “{names:[4]}” specifies the expected size of the array.

Let’s have a look at another comparison technique:

String ratings = "{ratings:[3.2,3.5,4.1,5,1]}";
JSONAssert.assertEquals(
  "{ratings:[1,5]}", 
  ratings, 
  new ArraySizeComparator(JSONCompareMode.LENIENT));

The above example verifies that all the elements in the array must have a value between [1,5], both 1 and 5 inclusive. If there is any value less than 1 or greater than 5, the above test will fail.

5. Advanced Comparison Example

Consider the use case where our API returns multiple ids, each one being an Integer value. This means that all the ids can be verified using a simple regular expression ‘\d‘.

The above regex can be combined with a CustomComparator and applied to all the values of all the ids. If any of the ids does not match the regex, the test will fail:

JSONAssert.assertEquals("{entry:{id:x}}", "{entry:{id:1, id:2}}", 
  new CustomComparator(
  JSONCompareMode.STRICT, 
  new Customization("entry.id", 
  new RegularExpressionValueMatcher<Object>("\\d"))));

JSONAssert.assertNotEquals("{entry:{id:x}}", "{entry:{id:1, id:as}}", 
  new CustomComparator(JSONCompareMode.STRICT, 
  new Customization("entry.id", 
  new RegularExpressionValueMatcher<Object>("\\d"))));

The “{id:x}” in the above example is nothing but a placeholder – the x can be replaced by anything. As it is the place where the regex pattern ‘\d‘ will be applied. Since the id itself is inside another field entry, the Customization specifies the position of the id, so that the CustomComparator can perform the comparison.

6. Conclusion

In this quick article, we looked at various scenarios where JSONAssert can be helpful. We started with a super simple example and moved to more complex comparisons.