JSONassertify: Bringing JSONassert into the Future with Balance

For over a decade, JSONassert has been a valuable tool in the toolbox of Java developers for easily writing test cases focused on comparing JSON. Its ability to simplify JSON comparisons in unit tests has been invaluable, streamlining the testing process across numerous Java projects I’ve worked on over the years. While the original JSONassert project has served us well, it has seen limited updates in recent years.

My recent development work on projects including jsonparamunit, a library for making parameterized JUnit 5 tests, has JSONassert as a core foundation. After a triggering event, I was inspired to action and created my own fork of JSONassert: JSONassertify.

Appreciating the Original JSONassert

Before diving into JSONassertify, it’s important to acknowledge the significant contributions of JSONassert’s original developers. JSONassert has made JSON comparisons in unit tests straightforward and reliable. The original project can be found on GitHub, where it continues to be developed and available.

As of June 2024, JSONassert is 29th in Testing Frameworks & Tools on MVN Repository

The benefit that JSONassert brings is by encapsulating the complexity of comparing JSON and generating helpful error messages when the JSON does not match into a simple line of code that is intuitive for anyone writing JUnit tests. This is a pattern I’ve used extensively in numerous Java projects and is one of my favorite patterns when dealing with JSON.

The sales pitch of JSONassert is making a basic assertEquals for JSON comparison in JUnit tests.

Why Fork JSONassert?

Despite its utility, the JSONassert project has seen minimal updates over the years. The inciting event for me was the release of JSONassert 1.5.2 that unexpectedly required Java 21, posing a challenge for many developers still working with earlier versions of Java including myself, who has several projects targeting Java 17.

While I am confident that the developers behind JSONassert will address this challenge with a future release, it was not the only reason I was motivated to fork the project.

One design decision made in 2016 was to change the JSON library implementation from org.json to the orphaned com.vaadin.external.google:android-json library, which has only had one release in 2014 and is clearly no longer maintained.

The android-json library used by JSONassert has not been updated since 2014.

The code base for JSONassert while not large, also could benefit from some cleanup such as adding missing Java Docs. A task which I was willing to perform.

It is also worth mentioning that forking JSONassert is available under the Apache 2.0 license, which explicitly allows for such modifications and enhancements.

Measured Enhancements in JSONassertify

JSONassertify builds on the solid foundation of JSONassert leaving the overwhelming majority of the functionality in place. However, there are a number of changes that take the project in a slightly different direction motivated to meet the needs of projects that I’m working on. The changes that are part of the initial release include:

1. Switch back to org.json: Switching back to org.json from the unsupported com.vaadin.external.google:android-json JSON parsing library. This is unquestionably a breaking change to the library as it did break some of the unit tests. The behavior of this JSON parsing library is different and therefore will result in different behavior in edge cases.
2. Upgrade to JUnit 5: The unit tests have been upgraded from JUnit 4to JUnit 5 to utilize the more modern testing framework
3. Utilize Dependabot to stay up-to-date: My intent is to keep JSONassertify up-to-date with new releases as its dependencies, specifically org.json, receive updates. The updates to org.json often address CVEs so this is a critical aspect.
4. GitHub Actions for Builds: A build action has been configured in GitHub Actions to compile and test all pull requests. This is minor but a critical part of modern software development. Additionally, CodeQL has been enabled allowing for the scanning of code issues of which many, but not all have been addressed in the initial release of JSONassertify.
5. Reporting code coverage: Another minor change is utilizing Codecov to report unit test coverage which for the initial release sits at 87%. Hopefully this can be improved in the future.
6. Code Formatting and Documentation: The codebase has been formatted, and missing JavaDocs have been added to improve readability and maintainability. There is still room for improvement here.
7. Overhauled project webpage: The original JSONassert webpage documentation has been moved to use GitHub pages to deploy from the repository using Jekyll to https://unitvectory-labs.github.io/JSONassertify/.
8. Java Version Targeting: JSONassertify targets Java 8 (for now), maintaining backward compatibility until Java 8 is fully deprecated. When necessary the targeted version will progress to the next non-deprecated version. The change JSONassert made to move to Java 21 while it may be backpedaled, was the motivation for JSONassertify.

A Continuation, Not a Replacement

Despite these updates, JSONassertify is fundamentally the same as JSONassert. The functionality and core codebase remains unchanged, and the same classes and methods are retained, albeit under a different package. This ensures that developers can transition to JSONassertify with minimal disruption.

Using JSONassertify looks nearly identical to JSONassert, you first include it as a dependency in your Java project:

<dependency>
    <groupId>com.unitvectory</groupId>
    <artifactId>jsonassertify</artifactId>
    <version>0.0.1</version>
    <scope>test</scope>
</dependency>

The only other major change is that to the package switching from “org.skyscreamer.jsonassert” to “com.unitvectory.jsonassertify” which will need to be updated for existing projects.

Otherwise, JSONassertify works the exact same way as always:

JSONObject data = getRESTData("/friends/367.json");
String expected = "{friends:[{id:123,name:\"Corby Page\"},{id:456,name:\"Carter Page\"}]}";
JSONAssert.assertEquals(expected, data, false);

Moving Forward

My motivation for updating JSONassertify was to meet my own personal needs for Java projects that I’m working on. However, I hope by making these enhancements others find this work useful.

I invite you to explore JSONassertify on GitHub and contribute to its development. Your feedback and contributions are invaluable as we continue to improve this tool for the developer community.