CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-skyscreamer--jsonassert

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

—

Pending
Overview
Eval results
Files

comparison.mddocs/

JSON Comparison

Low-level comparison functionality that provides programmatic access to JSON comparison results without JUnit integration. These methods return JSONCompareResult objects containing detailed comparison information, making them useful for custom test frameworks or validation logic where you need to inspect comparison results rather than just pass/fail assertions.

Capabilities

String Comparison

Compare JSON strings and return detailed comparison results including specific field differences, missing fields, and unexpected fields.

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

Usage Examples:

import org.skyscreamer.jsonassert.JSONCompare;
import org.skyscreamer.jsonassert.JSONCompareResult;
import org.skyscreamer.jsonassert.JSONCompareMode;

// Compare with mode
JSONCompareResult result = JSONCompare.compareJSON(
    "{\"name\":\"John\",\"age\":30}", 
    "{\"name\":\"Jane\",\"age\":30,\"city\":\"NYC\"}", 
    JSONCompareMode.LENIENT
);

if (result.failed()) {
    System.out.println("Comparison failed: " + result.getMessage());
    
    // Get specific failure details
    for (FieldComparisonFailure failure : result.getFieldFailures()) {
        System.out.println("Field: " + failure.getField());
        System.out.println("Expected: " + failure.getExpected());
        System.out.println("Actual: " + failure.getActual());
    }
}

// Compare with custom comparator
CustomComparator customComparator = new CustomComparator(JSONCompareMode.LENIENT);
result = JSONCompare.compareJSON(expected, actual, customComparator);

JSONObject Comparison

Direct comparison between JSONObject instances with customizable comparison strategies.

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

Usage Examples:

JSONObject expected = new JSONObject("{\"id\":1,\"name\":\"John\"}");
JSONObject actual = new JSONObject("{\"id\":1,\"name\":\"John\",\"active\":true}");

// Compare with different modes
JSONCompareResult strict = JSONCompare.compareJSON(expected, actual, JSONCompareMode.STRICT);
JSONCompareResult lenient = JSONCompare.compareJSON(expected, actual, JSONCompareMode.LENIENT);

System.out.println("Strict passed: " + strict.passed());   // false - extra field
System.out.println("Lenient passed: " + lenient.passed()); // true - extra field allowed

JSONArray Comparison

Compare JSONArray instances with flexible element ordering and matching strategies.

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

Usage Examples:

JSONArray expected = new JSONArray("[{\"id\":1},{\"id\":2}]");
JSONArray actual = new JSONArray("[{\"id\":2},{\"id\":1}]");

// Different ordering behavior
JSONCompareResult strictOrder = JSONCompare.compareJSON(expected, actual, JSONCompareMode.STRICT_ORDER);
JSONCompareResult lenient = JSONCompare.compareJSON(expected, actual, JSONCompareMode.LENIENT);

System.out.println("Strict order passed: " + strictOrder.passed()); // false - different order
System.out.println("Lenient passed: " + lenient.passed());          // true - order doesn't matter

JSONString Comparison

Compare JSONString objects by their JSON string representations.

public static JSONCompareResult compareJson(JSONString expected, JSONString actual);

Usage Examples:

import org.json.JSONString;

JSONString expected = new JSONString() {
    public String toJSONString() { return "{\"value\":\"test\"}"; }
};

JSONString actual = new JSONString() {
    public String toJSONString() { return "{\"value\":\"test\"}"; }
};

JSONCompareResult result = JSONCompare.compareJson(expected, actual);
System.out.println("JSONString comparison passed: " + result.passed());

Working with Results

The JSONCompareResult class provides detailed information about comparison outcomes:

Basic Result Information

JSONCompareResult result = JSONCompare.compareJSON(expected, actual, JSONCompareMode.LENIENT);

// Check overall result
boolean success = result.passed();
boolean failure = result.failed();
String message = result.getMessage(); // Detailed failure description

Field-Level Failure Analysis

// Get different types of field failures
List<FieldComparisonFailure> fieldFailures = result.getFieldFailures();     // Value mismatches
List<FieldComparisonFailure> missingFields = result.getFieldMissing();      // Expected but not found
List<FieldComparisonFailure> unexpectedFields = result.getFieldUnexpected(); // Found but not expected

// Check for specific failure types
boolean hasFieldFailures = result.isFailureOnField();
boolean hasMissingFields = result.isMissingOnField();  
boolean hasUnexpectedFields = result.isUnexpectedOnField();

// Process individual failures
for (FieldComparisonFailure failure : fieldFailures) {
    String fieldPath = failure.getField();
    Object expectedValue = failure.getExpected();
    Object actualValue = failure.getActual();
    
    System.out.println("Field " + fieldPath + " failed:");
    System.out.println("  Expected: " + expectedValue);
    System.out.println("  Actual: " + actualValue);
}

Advanced Comparison Scenarios

// Using comparison results for custom validation logic
public boolean isJsonValid(String expected, String actual) {
    try {
        JSONCompareResult result = JSONCompare.compareJSON(expected, actual, JSONCompareMode.LENIENT);
        
        if (result.passed()) {
            return true;
        }
        
        // Allow certain types of differences
        if (result.isUnexpectedOnField() && !result.isFailureOnField() && !result.isMissingOnField()) {
            // Only extra fields, which might be acceptable
            return true;
        }
        
        return false;
    } catch (JSONException e) {
        return false;
    }
}

// Custom error reporting
public void reportJsonDifferences(String expected, String actual) throws JSONException {
    JSONCompareResult result = JSONCompare.compareJSON(expected, actual, JSONCompareMode.STRICT);
    
    if (result.failed()) {
        System.out.println("JSON Comparison Failed:");
        System.out.println("Overall message: " + result.getMessage());
        
        if (result.isFailureOnField()) {
            System.out.println("\nField value mismatches:");
            result.getFieldFailures().forEach(f -> 
                System.out.println("  " + f.getField() + ": expected " + f.getExpected() + ", got " + f.getActual())
            );
        }
        
        if (result.isMissingOnField()) {
            System.out.println("\nMissing fields:");
            result.getFieldMissing().forEach(f -> 
                System.out.println("  " + f.getField() + ": expected " + f.getExpected())
            );
        }
        
        if (result.isUnexpectedOnField()) {
            System.out.println("\nUnexpected fields:");
            result.getFieldUnexpected().forEach(f -> 
                System.out.println("  " + f.getField() + ": got " + f.getActual())
            );
        }
    }
}

Error Handling

  • JSONException: Thrown when JSON parsing fails for either expected or actual values
  • IllegalArgumentException: Thrown when expected and actual JSON types don't match (e.g., comparing object to array)

Integration with Assertions

The JSONCompare methods serve as the backend for JSONAssert. The assertion methods use these comparison functions and throw AssertionError when result.failed() returns true:

// This assertion method internally uses:
JSONCompareResult result = JSONCompare.compareJSON(expectedStr, actualStr, compareMode);
if (result.failed()) {
    throw new AssertionError(result.getMessage());
}

Install with Tessl CLI

npx tessl i tessl/maven-org-skyscreamer--jsonassert

docs

assertions.md

comparators.md

comparison.md

custom-matchers.md

index.md

tile.json