0
# JSON Assertions
1

2
Core assertion functionality providing static methods for comparing JSON strings, objects, and arrays with different comparison modes and detailed error reporting. These methods integrate directly with JUnit and throw AssertionError on comparison failures.
3

4
## Capabilities
5

6
### String-to-String Assertions
7

8
Compare JSON strings directly with flexible comparison modes and optional custom error messages.
9

10
```java { .api }
11
public static void assertEquals(String expectedStr, String actualStr, boolean strict) throws JSONException;
12
public static void assertEquals(String message, String expectedStr, String actualStr, boolean strict) throws JSONException;
13
public static void assertEquals(String expectedStr, String actualStr, JSONCompareMode compareMode) throws JSONException;
14
public static void assertEquals(String message, String expectedStr, String actualStr, JSONCompareMode compareMode) throws JSONException;
15
public static void assertEquals(String expectedStr, String actualStr, JSONComparator comparator) throws JSONException;
16
public static void assertEquals(String message, String expectedStr, String actualStr, JSONComparator comparator) throws JSONException;
17
```
18

19
**Usage Examples:**
20

21
```java
22
// Basic strict comparison
23
JSONAssert.assertEquals("{\"name\":\"John\"}", "{\"name\":\"John\"}", true);
24

25
// Lenient comparison with different field order
26
JSONAssert.assertEquals("{\"name\":\"John\",\"age\":30}", "{\"age\":30,\"name\":\"John\"}", false);
27

28
// Custom error message
29
JSONAssert.assertEquals("User data should match", expected, actual, JSONCompareMode.LENIENT);
30

31
// Using comparison modes explicitly
32
JSONAssert.assertEquals(expected, actual, JSONCompareMode.NON_EXTENSIBLE);
33
```
34

35
### String-to-JSONObject Assertions
36

37
Compare JSON strings against JSONObject instances, useful when working with pre-parsed JSON objects.
38

39
```java { .api }
40
public static void assertEquals(String expectedStr, JSONObject actual, boolean strict) throws JSONException;
41
public static void assertEquals(String message, String expectedStr, JSONObject actual, boolean strict) throws JSONException;
42
public static void assertEquals(String expectedStr, JSONObject actual, JSONCompareMode compareMode) throws JSONException;
43
public static void assertEquals(String message, String expectedStr, JSONObject actual, JSONCompareMode compareMode) throws JSONException;
44
```
45

46
**Usage Examples:**
47

48
```java
49
JSONObject actualObject = new JSONObject("{\"name\":\"John\",\"age\":30}");
50

51
// Compare string to object
52
JSONAssert.assertEquals("{\"name\":\"John\"}", actualObject, JSONCompareMode.LENIENT);
53

54
// With custom message
55
JSONAssert.assertEquals("Object comparison failed", "{\"name\":\"John\"}", actualObject, true);
56
```
57

58
### String-to-JSONArray Assertions
59

60
Compare JSON strings against JSONArray instances for array-specific validation scenarios.
61

62
```java { .api }
63
public static void assertEquals(String expectedStr, JSONArray actual, boolean strict) throws JSONException;
64
public static void assertEquals(String message, String expectedStr, JSONArray actual, boolean strict) throws JSONException;
65
public static void assertEquals(String expectedStr, JSONArray actual, JSONCompareMode compareMode) throws JSONException;
66
public static void assertEquals(String message, String expectedStr, JSONArray actual, JSONCompareMode compareMode) throws JSONException;
67
```
68

69
**Usage Examples:**
70

71
```java
72
JSONArray actualArray = new JSONArray("[{\"id\":1},{\"id\":2}]");
73

74
// Compare string to array with different ordering
75
JSONAssert.assertEquals("[{\"id\":2},{\"id\":1}]", actualArray, JSONCompareMode.LENIENT);
76

77
// Strict array ordering
78
JSONAssert.assertEquals("[{\"id\":1},{\"id\":2}]", actualArray, JSONCompareMode.STRICT_ORDER);
79
```
80

81
### JSONObject-to-JSONObject Assertions
82

83
Direct comparison between JSONObject instances with support for custom comparators.
84

85
```java { .api }
86
public static void assertEquals(JSONObject expected, JSONObject actual, boolean strict) throws JSONException;
87
public static void assertEquals(String message, JSONObject expected, JSONObject actual, boolean strict) throws JSONException;
88
public static void assertEquals(JSONObject expected, JSONObject actual, JSONCompareMode compareMode) throws JSONException;
89
public static void assertEquals(String message, JSONObject expected, JSONObject actual, JSONCompareMode compareMode) throws JSONException;
90
public static void assertEquals(JSONObject expected, JSONObject actual, JSONComparator comparator) throws JSONException;
91
public static void assertEquals(String message, JSONObject expected, JSONObject actual, JSONComparator comparator) throws JSONException;
92
```
93

94
### JSONArray-to-JSONArray Assertions
95

96
Direct comparison between JSONArray instances with flexible ordering and element matching.
97

98
```java { .api }
99
public static void assertEquals(JSONArray expected, JSONArray actual, boolean strict) throws JSONException;
100
public static void assertEquals(String message, JSONArray expected, JSONArray actual, boolean strict) throws JSONException;
101
public static void assertEquals(JSONArray expected, JSONArray actual, JSONCompareMode compareMode) throws JSONException;
102
public static void assertEquals(String message, JSONArray expected, JSONArray actual, JSONCompareMode compareMode) throws JSONException;
103
```
104

105
### Negative Assertions
106

107
All assertion methods have corresponding `assertNotEquals` variants that verify JSON structures do NOT match.
108

109
```java { .api }
110
public static void assertNotEquals(String expectedStr, String actualStr, boolean strict) throws JSONException;
111
public static void assertNotEquals(String message, String expectedStr, String actualStr, boolean strict) throws JSONException;
112
public static void assertNotEquals(String expectedStr, String actualStr, JSONCompareMode compareMode) throws JSONException;
113
public static void assertNotEquals(String message, String expectedStr, String actualStr, JSONCompareMode compareMode) throws JSONException;
114
public static void assertNotEquals(String expectedStr, String actualStr, JSONComparator comparator) throws JSONException;
115
public static void assertNotEquals(String message, String expectedStr, String actualStr, JSONComparator comparator) throws JSONException;
116
public static void assertNotEquals(JSONObject expected, JSONObject actual, boolean strict) throws JSONException;
117
public static void assertNotEquals(String message, JSONObject expected, JSONObject actual, boolean strict) throws JSONException;
118
public static void assertNotEquals(JSONObject expected, JSONObject actual, JSONCompareMode compareMode) throws JSONException;
119
public static void assertNotEquals(String message, JSONObject expected, JSONObject actual, JSONCompareMode compareMode) throws JSONException;
120
public static void assertNotEquals(JSONObject expected, JSONObject actual, JSONComparator comparator) throws JSONException;
121
public static void assertNotEquals(String message, JSONObject expected, JSONObject actual, JSONComparator comparator) throws JSONException;
122
public static void assertNotEquals(JSONArray expected, JSONArray actual, boolean strict) throws JSONException;
123
public static void assertNotEquals(String message, JSONArray expected, JSONArray actual, boolean strict) throws JSONException;
124
public static void assertNotEquals(JSONArray expected, JSONArray actual, JSONCompareMode compareMode) throws JSONException;
125
public static void assertNotEquals(String message, JSONArray expected, JSONArray actual, JSONCompareMode compareMode) throws JSONException;
126
```
127

128
**Usage Examples:**
129

130
```java
131
// Verify JSON structures are different
132
JSONAssert.assertNotEquals("{\"status\":\"active\"}", "{\"status\":\"inactive\"}", false);
133

134
// Verify arrays don't match
135
JSONAssert.assertNotEquals("[1,2,3]", "[1,2,4]", JSONCompareMode.STRICT);
136
```
137

138
## Error Handling
139

140
All assertion methods throw `JSONException` for JSON parsing errors and `AssertionError` for comparison failures. The AssertionError messages include detailed information about where differences were found:
141

142
```java
143
// Example failure message:
144
// name
145
// Expected: John
146
//      got: Jane
147
```
148

149
## Comparison Mode Behavior
150

151
- **STRICT**: Exact match required, no additional fields allowed, array order matters
152
- **LENIENT**: Additional fields allowed, array order doesn't matter  
153
- **NON_EXTENSIBLE**: No additional fields allowed, array order doesn't matter
154
- **STRICT_ORDER**: Additional fields allowed, array order matters