update

README.md

@@ -38,6 +38,39 @@ The library has some tweaks which helps you make assertions without writing any
 compile 'com.github.fslev:json-compare:<version.from.maven.central>'
 ```
 
+Match any JSON convertible Java objects
+```javascript
+String expectedString = "{\"a\":1, \"b\": [4, 2, \"\\\\d+\"]}";
+String actualString = "{\"a\":1, \"b\":[4, 2, 5], \"c\":3}";
+JSONCompare.assertMatches(expectedString, actualString); // assertion passes
+
+// actual represented as Map
+Map<String, Object> actualMap = new HashMap<>();
+actualMap.put("a", 1);
+actualMap.put("b", Arrays.asList(4, 2, 5));
+actualMap.put("c", 3);
+JSONCompare.assertMatches(expectedString, actualMap); // assertion passes
+
+// Failed assertion
+String anotherActualString = "{\"a\":10, \"b\":[4, 20, 5], \"c\":3}";
+JSONCompare.assertNotMatches(expectedString, anotherActualString); // assertion passes
+JSONCompare.assertMatches(expectedString, anotherActualString); // assertion fails
+
+==>
+
+org.opentest4j.AssertionFailedError: FOUND 2 DIFFERENCE(S):
+
+
+_________________________DIFF__________________________
+a -> 
+Expected value: 1 But got: 10
+
+_________________________DIFF__________________________
+b -> 
+Expected element from position 2 was NOT FOUND:
+2
+```
+
 # <a name="compare-modes"></a>Compare modes
 
 Assert that expected JSON is included within the actual JSON:
@@ -79,13 +112,6 @@ String actual = "{\"foobar\":\"some value\"}";
 JSONCompare.assertMatches(expected, actual);
 ```
 
-Match any JSON convertible Java objects  
-```javascript
-String expected = "{\"a\":1,\"b\":[4, 2, \"\\\\d+\"]}";
-Map<String, Object> actual = Map.of("a", 1, "b", Arrays.asList(1, 2, 3, 4));
-JSONCompare.assertMatches(expected, actual);
-```
-
 JSONCompare by default matches JSON fields and values using regular expressions.  
 If you have unintentional regex characters inside either expected values or expected fields, then you can quote them:  
 

src/test/java/io/json/compare/matcher/readme/ReadmeTests.java

@@ -0,0 +1,36 @@
+package io.json.compare.matcher.readme;
+
+import io.json.compare.JSONCompare;
+import org.junit.jupiter.api.Test;
+
+import java.util.Arrays;
+import java.util.HashMap;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+public class ReadmeTests {
+
+    @Test
+    public void matchJsonConvertibleJavaObjects() {
+        String expectedString = "{\"a\":1, \"b\": [4, 2, \"\\\\d+\"]}";
+        String actualString = "{\"a\":1, \"b\":[4, 2, 5], \"c\":3}";
+        JSONCompare.assertMatches(expectedString, actualString); // assertion passes
+
+        // actual represented as Map
+        Map<String, Object> actualMap = new HashMap<>();
+        actualMap.put("a", 1);
+        actualMap.put("b", Arrays.asList(4, 2, 5));
+        actualMap.put("c", 3);
+        JSONCompare.assertMatches(expectedString, actualMap); // assertion passes
+
+        // Failed assertion
+        String anotherActualString = "{\"a\":10, \"b\":[4, 20, 5], \"c\":3}";
+        JSONCompare.assertNotMatches(expectedString, anotherActualString); // assertion passes
+        AssertionError error = assertThrows(AssertionError.class, () -> JSONCompare.assertMatches(expectedString, anotherActualString));
+        assertTrue(error.getMessage().matches("(?s).*FOUND 2 DIFFERENCE.*" +
+                "a ->.*Expected value: 1 But got: 10.*" +
+                "b ->.*Expected element from position 2 was NOT FOUND.*"));
+    }
+}