0
# JSONassert
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: org.skyscreamer:jsonassert
7
- **Package Type**: Maven
8
- **Language**: Java (Java 8+ target)
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>org.skyscreamer</groupId>
13
    <artifactId>jsonassert</artifactId>
14
    <version>1.5.3</version>
15
    <scope>test</scope>
16
  </dependency>
17
  ```
18

19
## Core Imports
20

21
```java
22
import org.skyscreamer.jsonassert.JSONAssert;
23
import org.skyscreamer.jsonassert.JSONCompareMode;
24
```
25

26
For advanced usage:
27

28
```java
29
import org.skyscreamer.jsonassert.JSONCompare;
30
import org.skyscreamer.jsonassert.JSONCompareResult;
31
import org.skyscreamer.jsonassert.comparator.CustomComparator;
32
import org.skyscreamer.jsonassert.Customization;
33
```
34

35
## Basic Usage
36

37
```java
38
import org.skyscreamer.jsonassert.JSONAssert;
39
import org.skyscreamer.jsonassert.JSONCompareMode;
40
import org.json.JSONException;
41

42
public class MyJsonTest {
43
    @Test
44
    public void testJsonEquality() throws JSONException {
45
        String expected = "{\"name\":\"John\", \"age\":30}";
46
        String actual = "{\"age\":30, \"name\":\"John\"}";
47
        
48
        // Lenient comparison - order doesn't matter
49
        JSONAssert.assertEquals(expected, actual, JSONCompareMode.LENIENT);
50
        
51
        // Strict comparison - exact match required
52
        JSONAssert.assertEquals(expected, actual, JSONCompareMode.STRICT);
53
        
54
        // Simple boolean mode
55
        JSONAssert.assertEquals(expected, actual, false); // lenient
56
        JSONAssert.assertEquals(expected, actual, true);  // strict
57
    }
58
    
59
    @Test
60
    public void testJsonArrays() throws JSONException {
61
        String expectedArray = "[{\"id\":1}, {\"id\":2}]";
62
        String actualArray = "[{\"id\":2}, {\"id\":1}]";
63
        
64
        // Arrays can be compared in non-strict order
65
        JSONAssert.assertEquals(expectedArray, actualArray, JSONCompareMode.LENIENT);
66
    }
67
}
68
```
69

70
## Architecture
71

72
JSONassert follows a layered architecture with clear separation of concerns:
73

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

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

84
## Capabilities
85

86
### JSON Assertion Methods
87

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

90
```java { .api }
91
public static void assertEquals(String expectedStr, String actualStr, boolean strict) throws JSONException;
92
public static void assertEquals(String expectedStr, String actualStr, JSONCompareMode compareMode) throws JSONException;
93
public static void assertEquals(String expectedStr, JSONObject actual, JSONCompareMode compareMode) throws JSONException;
94
public static void assertEquals(String expectedStr, JSONArray actual, JSONCompareMode compareMode) throws JSONException;
95
public static void assertNotEquals(String expectedStr, String actualStr, boolean strict) throws JSONException;
96
```
97

98
[JSON Assertions](./assertions.md)
99

100
### JSON Comparison Engine
101

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

104
```java { .api }
105
public static JSONCompareResult compareJSON(String expectedStr, String actualStr, JSONCompareMode mode) throws JSONException;
106
public static JSONCompareResult compareJSON(JSONObject expected, JSONObject actual, JSONComparator comparator) throws JSONException;
107
public static JSONCompareResult compareJSON(JSONArray expected, JSONArray actual, JSONComparator comparator) throws JSONException;
108
```
109

110
[JSON Comparison](./comparison.md)
111

112
### Custom Value Matching
113

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

116
```java { .api }
117
public interface ValueMatcher<T> {
118
    boolean equal(T o1, T o2);
119
}
120

121
public class RegularExpressionValueMatcher<T> implements ValueMatcher<T> {
122
    public RegularExpressionValueMatcher(String pattern);
123
}
124

125
public class ArrayValueMatcher<T> implements LocationAwareValueMatcher<T> {
126
    public ArrayValueMatcher(JSONComparator comparator);
127
    public ArrayValueMatcher(JSONComparator comparator, int index);
128
}
129
```
130

131
[Custom Matchers](./custom-matchers.md)
132

133
### JSON Comparators
134

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

137
```java { .api }
138
public interface JSONComparator {
139
    JSONCompareResult compareJSON(JSONObject expected, JSONObject actual) throws JSONException;
140
    JSONCompareResult compareJSON(JSONArray expected, JSONArray actual) throws JSONException;
141
}
142

143
public class CustomComparator extends DefaultComparator {
144
    public CustomComparator(JSONCompareMode mode, Customization... customizations);
145
}
146
```
147

148
[JSON Comparators](./comparators.md)
149

150
## Types
151

152
### Core Enums and Classes
153

154
```java { .api }
155
public enum JSONCompareMode {
156
    STRICT,      // Not extensible, strict array ordering
157
    LENIENT,     // Extensible, non-strict array ordering  
158
    NON_EXTENSIBLE, // Not extensible, non-strict array ordering
159
    STRICT_ORDER;   // Extensible, strict array ordering
160
    
161
    public boolean isExtensible();
162
    public boolean hasStrictOrder();
163
    public JSONCompareMode withStrictOrdering(boolean strictOrdering);
164
    public JSONCompareMode withExtensible(boolean extensible);
165
}
166

167
public class JSONCompareResult {
168
    public boolean passed();
169
    public boolean failed();
170
    public String getMessage();
171
    public List<FieldComparisonFailure> getFieldFailures();
172
    public List<FieldComparisonFailure> getFieldMissing();
173
    public List<FieldComparisonFailure> getFieldUnexpected();
174
    public boolean isFailureOnField();
175
    public boolean isMissingOnField();
176
    public boolean isUnexpectedOnField();
177
    public JSONCompareResult fail(String field, Object expected, Object actual);
178
    public JSONCompareResult missing(String field, Object expected);
179
    public JSONCompareResult unexpected(String field, Object actual);
180
    public JSONCompareResult fail(String field, ValueMatcherException exception);
181
    public String toString();
182
    
183
    // Deprecated methods
184
    @Deprecated
185
    public Object getActual();
186
    @Deprecated
187
    public Object getExpected();
188
    @Deprecated
189
    public String getField();
190
}
191

192
public class Customization {
193
    public Customization(String path, ValueMatcher<Object> comparator);
194
    public static Customization customization(String path, ValueMatcher<Object> comparator);
195
    public boolean appliesToPath(String path);
196
    public boolean matches(String prefix, Object actual, Object expected, JSONCompareResult result) throws ValueMatcherException;
197
    
198
    // Deprecated method
199
    @Deprecated
200
    public boolean matches(Object actual, Object expected);
201
}
202

203
public class FieldComparisonFailure {
204
    public FieldComparisonFailure(String field, Object expected, Object actual);
205
    public String getField();
206
    public Object getExpected();
207
    public Object getActual();
208
}
209

210
public class JSONParser {
211
    /**
212
     * Parse JSON string into JSONObject, JSONArray, or JSONString.
213
     * Returns JSONObject for objects starting with "{",
214
     * JSONArray for arrays starting with "[", 
215
     * JSONString for quoted strings or numbers.
216
     * 
217
     * @param s Raw JSON string to be parsed
218
     * @return JSONObject, JSONArray, or JSONString instance
219
     * @throws JSONException if string is not valid JSON
220
     */
221
    public static Object parseJSON(String s) throws JSONException;
222
}
223
```