or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

assertions.mdcomparators.mdcomparison.mdcustom-matchers.mdindex.md
tile.json

tessl/maven-org-skyscreamer--jsonassert

Write JSON unit tests in less code. Great for testing REST interfaces.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.skyscreamer/jsonassert@1.5.x

To install, run

npx @tessl/cli install tessl/maven-org-skyscreamer--jsonassert@1.5.0

index.mddocs/

JSONassert

A Java library that simplifies JSON unit testing by providing assertion methods that compare JSON strings logically rather than character-by-character. JSONassert offers flexible comparison modes, supports custom value matchers and comparators for advanced validation scenarios, provides detailed error messages that pinpoint specific differences in nested JSON structures, and integrates seamlessly with JUnit testing framework.

Package Information

  • Package Name: org.skyscreamer:jsonassert
  • Package Type: Maven
  • Language: Java (Java 8+ target)
  • Installation: 
    <dependency>
  <groupId>org.skyscreamer</groupId>
  <artifactId>jsonassert</artifactId>
  <version>1.5.3</version>
  <scope>test</scope>
</dependency>

Core Imports

import org.skyscreamer.jsonassert.JSONAssert;
import org.skyscreamer.jsonassert.JSONCompareMode;

For advanced usage:

import org.skyscreamer.jsonassert.JSONCompare;
import org.skyscreamer.jsonassert.JSONCompareResult;
import org.skyscreamer.jsonassert.comparator.CustomComparator;
import org.skyscreamer.jsonassert.Customization;

Basic Usage

import org.skyscreamer.jsonassert.JSONAssert;
import org.skyscreamer.jsonassert.JSONCompareMode;
import org.json.JSONException;

public class MyJsonTest {
    @Test
    public void testJsonEquality() throws JSONException {
        String expected = "{\"name\":\"John\", \"age\":30}";
        String actual = "{\"age\":30, \"name\":\"John\"}";
        
        // Lenient comparison - order doesn't matter
        JSONAssert.assertEquals(expected, actual, JSONCompareMode.LENIENT);
        
        // Strict comparison - exact match required
        JSONAssert.assertEquals(expected, actual, JSONCompareMode.STRICT);
        
        // Simple boolean mode
        JSONAssert.assertEquals(expected, actual, false); // lenient
        JSONAssert.assertEquals(expected, actual, true);  // strict
    }
    
    @Test
    public void testJsonArrays() throws JSONException {
        String expectedArray = "[{\"id\":1}, {\"id\":2}]";
        String actualArray = "[{\"id\":2}, {\"id\":1}]";
        
        // Arrays can be compared in non-strict order
        JSONAssert.assertEquals(expectedArray, actualArray, JSONCompareMode.LENIENT);
    }
}

Architecture

JSONassert follows a layered architecture with clear separation of concerns:

  • JSONAssert: High-level static assertion methods that integrate with JUnit
  • JSONCompare: Core comparison engine that performs the actual JSON comparison logic
  • JSONComparator: Interface for pluggable comparison strategies (Default, Custom, ArraySize)
  • JSONCompareMode: Enum defining comparison behavior (strict/lenient, extensible/non-extensible)
  • JSONCompareResult: Container for comparison results and detailed failure information
  • Value Matchers: Extensible system for custom field-level validation (regex, array matching)
  • Customization: Path-based custom matching for specific JSON fields

This design enables flexible testing scenarios from simple equality checks to complex custom validation while maintaining clear error reporting and JUnit integration.

Capabilities

JSON Assertion Methods

Core assertion functionality providing static methods for comparing JSON strings, objects, and arrays with different comparison modes and detailed error reporting.

public static void assertEquals(String expectedStr, String actualStr, boolean strict) throws JSONException;
public static void assertEquals(String expectedStr, String actualStr, JSONCompareMode compareMode) throws JSONException;
public static void assertEquals(String expectedStr, JSONObject actual, JSONCompareMode compareMode) throws JSONException;
public static void assertEquals(String expectedStr, JSONArray actual, JSONCompareMode compareMode) throws JSONException;
public static void assertNotEquals(String expectedStr, String actualStr, boolean strict) throws JSONException;

JSON Assertions

JSON Comparison Engine

Low-level comparison functionality that provides programmatic access to JSON comparison results without JUnit integration, useful for custom test frameworks or validation logic.

public static JSONCompareResult compareJSON(String expectedStr, String actualStr, JSONCompareMode mode) throws JSONException;
public static JSONCompareResult compareJSON(JSONObject expected, JSONObject actual, JSONComparator comparator) throws JSONException;
public static JSONCompareResult compareJSON(JSONArray expected, JSONArray actual, JSONComparator comparator) throws JSONException;

JSON Comparison

Custom Value Matching

Advanced validation system enabling custom field-level matching with regular expressions, array validation, and path-based customization for complex JSON structures.

public interface ValueMatcher<T> {
    boolean equal(T o1, T o2);
}

public class RegularExpressionValueMatcher<T> implements ValueMatcher<T> {
    public RegularExpressionValueMatcher(String pattern);
}

public class ArrayValueMatcher<T> implements LocationAwareValueMatcher<T> {
    public ArrayValueMatcher(JSONComparator comparator);
    public ArrayValueMatcher(JSONComparator comparator, int index);
}

Custom Matchers

JSON Comparators

Pluggable comparison strategies including default comparison logic, custom field-level matching, and specialized array size comparison for different validation scenarios.

public interface JSONComparator {
    JSONCompareResult compareJSON(JSONObject expected, JSONObject actual) throws JSONException;
    JSONCompareResult compareJSON(JSONArray expected, JSONArray actual) throws JSONException;
}

public class CustomComparator extends DefaultComparator {
    public CustomComparator(JSONCompareMode mode, Customization... customizations);
}

JSON Comparators

Types

Core Enums and Classes

public enum JSONCompareMode {
    STRICT,      // Not extensible, strict array ordering
    LENIENT,     // Extensible, non-strict array ordering  
    NON_EXTENSIBLE, // Not extensible, non-strict array ordering
    STRICT_ORDER;   // Extensible, strict array ordering
    
    public boolean isExtensible();
    public boolean hasStrictOrder();
    public JSONCompareMode withStrictOrdering(boolean strictOrdering);
    public JSONCompareMode withExtensible(boolean extensible);
}

public class JSONCompareResult {
    public boolean passed();
    public boolean failed();
    public String getMessage();
    public List<FieldComparisonFailure> getFieldFailures();
    public List<FieldComparisonFailure> getFieldMissing();
    public List<FieldComparisonFailure> getFieldUnexpected();
    public boolean isFailureOnField();
    public boolean isMissingOnField();
    public boolean isUnexpectedOnField();
    public JSONCompareResult fail(String field, Object expected, Object actual);
    public JSONCompareResult missing(String field, Object expected);
    public JSONCompareResult unexpected(String field, Object actual);
    public JSONCompareResult fail(String field, ValueMatcherException exception);
    public String toString();
    
    // Deprecated methods
    @Deprecated
    public Object getActual();
    @Deprecated
    public Object getExpected();
    @Deprecated
    public String getField();
}

public class Customization {
    public Customization(String path, ValueMatcher<Object> comparator);
    public static Customization customization(String path, ValueMatcher<Object> comparator);
    public boolean appliesToPath(String path);
    public boolean matches(String prefix, Object actual, Object expected, JSONCompareResult result) throws ValueMatcherException;
    
    // Deprecated method
    @Deprecated
    public boolean matches(Object actual, Object expected);
}

public class FieldComparisonFailure {
    public FieldComparisonFailure(String field, Object expected, Object actual);
    public String getField();
    public Object getExpected();
    public Object getActual();
}

public class JSONParser {
    /**
     * Parse JSON string into JSONObject, JSONArray, or JSONString.
     * Returns JSONObject for objects starting with "{",
     * JSONArray for arrays starting with "[", 
     * JSONString for quoted strings or numbers.
     * 
     * @param s Raw JSON string to be parsed
     * @return JSONObject, JSONArray, or JSONString instance
     * @throws JSONException if string is not valid JSON
     */
    public static Object parseJSON(String s) throws JSONException;
}