src/core/src/test/java/solutions/bitbadger/documents/core/tests/java/integration/JsonFunctions.java

@@ -3,6 +3,8 @@ package solutions.bitbadger.documents.core.tests.java.integration;
 import solutions.bitbadger.documents.*;
 import solutions.bitbadger.documents.core.tests.integration.ThrowawayDatabase;
 
+import java.io.PrintWriter;
+import java.io.StringWriter;
 import java.util.List;
 import java.util.Map;
 
@@ -45,9 +47,7 @@ final public class JsonFunctions {
         return maybeJsonB(String.format("{\"id\":\"%s\"", id));
     }
 
-    public static void allDefault(ThrowawayDatabase db) throws DocumentException {
+    private static void checkAllDefault(String json) throws DocumentException {
-        JsonDocument.load(db);
-        final String json = jsonAll(db.getConn(), TEST_TABLE);
         assertTrue(json.startsWith("["), "JSON should start with '[' ($json)");
         switch (Configuration.dialect()) {
             case SQLITE:
@@ -74,13 +74,35 @@ final public class JsonFunctions {
         assertTrue(json.endsWith("]"), "JSON should end with ']' ($json)");
     }
 
-    public static void allEmpty(ThrowawayDatabase db) throws DocumentException {
+    public static void allDefault(ThrowawayDatabase db) throws DocumentException {
-        assertEquals("[]", jsonAll(db.getConn(), TEST_TABLE), "There should have been no documents returned");
+        JsonDocument.load(db);
+        checkAllDefault(jsonAll(db.getConn(), TEST_TABLE));
     }
 
-    public static void byIdString(ThrowawayDatabase db) throws DocumentException {
+    public static void writeAllDefault(ThrowawayDatabase db) throws DocumentException {
         JsonDocument.load(db);
-        final String json = jsonById(db.getConn(), TEST_TABLE, "two");
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonAll(db.getConn(), TEST_TABLE, writer);
+        checkAllDefault(output.toString());
+    }
+
+    private static void checkAllEmpty(String json) {
+        assertEquals("[]", json, "There should have been no documents returned");
+    }
+
+    public static void allEmpty(ThrowawayDatabase db) throws DocumentException {
+        checkAllEmpty(jsonAll(db.getConn(), TEST_TABLE));
+    }
+
+    public static void writeAllEmpty(ThrowawayDatabase db) throws DocumentException {
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonAll(db.getConn(), TEST_TABLE, writer);
+        checkAllEmpty(output.toString());
+    }
+
+    private static void checkByIdString(String json) throws DocumentException {
         switch (Configuration.dialect()) {
             case SQLITE:
                 assertEquals(JsonDocument.two, json, "An incorrect document was returned");
@@ -91,26 +113,65 @@ final public class JsonFunctions {
         }
     }
 
+    public static void byIdString(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        checkByIdString(jsonById(db.getConn(), TEST_TABLE, "two"));
+    }
+
+    public static void writeByIdString(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonById(db.getConn(), TEST_TABLE, writer, "two");
+        checkByIdString(output.toString());
+    }
+
+    private static void checkByIdNumber(String json) throws DocumentException {
+        assertEquals(maybeJsonB("{\"key\":18,\"text\":\"howdy\"}"), json,
+                "The document should have been found by numeric ID");
+    }
+
     public static void byIdNumber(ThrowawayDatabase db) throws DocumentException {
         Configuration.idField = "key";
         try {
             insert(db.getConn(), TEST_TABLE, new NumIdDocument(18, "howdy"));
-            assertEquals(maybeJsonB("{\"key\":18,\"text\":\"howdy\"}"), jsonById(db.getConn(), TEST_TABLE, 18),
+            checkByIdNumber(jsonById(db.getConn(), TEST_TABLE, 18));
-                    "The document should have been found by numeric ID");
         } finally {
             Configuration.idField = "id";
         }
     }
 
-    public static void byIdNotFound(ThrowawayDatabase db) throws DocumentException {
+    public static void writeByIdNumber(ThrowawayDatabase db) throws DocumentException {
-        JsonDocument.load(db);
+        Configuration.idField = "key";
-        assertEquals("{}", jsonById(db.getConn(), TEST_TABLE, "x"), "There should have been no document returned");
+        try {
+            insert(db.getConn(), TEST_TABLE, new NumIdDocument(18, "howdy"));
+            final StringWriter output = new StringWriter();
+            final PrintWriter writer = new PrintWriter(output);
+            writeJsonById(db.getConn(), TEST_TABLE, writer, 18);
+            checkByIdNumber(output.toString());
+        } finally {
+            Configuration.idField = "id";
+        }
     }
 
-    public static void byFieldsMatch(ThrowawayDatabase db) throws DocumentException {
+    private static void checkByIdNotFound(String json) {
+        assertEquals("{}", json, "There should have been no document returned");
+    }
+
+    public static void byIdNotFound(ThrowawayDatabase db) throws DocumentException {
         JsonDocument.load(db);
-        final String json = jsonByFields(db.getConn(), TEST_TABLE,
+        checkByIdNotFound(jsonById(db.getConn(), TEST_TABLE, "x"));
-                List.of(Field.any("value", List.of("blue", "purple")), Field.exists("sub")), FieldMatch.ALL);
+    }
+
+    public static void writeByIdNotFound(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonById(db.getConn(), TEST_TABLE, writer, "x");
+        checkByIdNotFound(output.toString());
+    }
+
+    private static void checkByFieldsMatch(String json) throws DocumentException {
         switch (Configuration.dialect()) {
             case SQLITE:
                 assertEquals(String.format("[%s]", JsonDocument.four), json, "The incorrect document was returned");
@@ -124,10 +185,22 @@ final public class JsonFunctions {
         }
     }
 
-    public static void byFieldsMatchOrdered(ThrowawayDatabase db) throws DocumentException {
+    public static void byFieldsMatch(ThrowawayDatabase db) throws DocumentException {
         JsonDocument.load(db);
-        final String json = jsonByFields(db.getConn(), TEST_TABLE, List.of(Field.equal("value", "purple")), null,
+        checkByFieldsMatch(jsonByFields(db.getConn(), TEST_TABLE, List.of(Field.any("value", List.of("blue", "purple")),
-                List.of(Field.named("id")));
+                Field.exists("sub")), FieldMatch.ALL));
+    }
+
+    public static void writeByFieldsMatch(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonByFields(db.getConn(), TEST_TABLE, writer, List.of(Field.any("value", List.of("blue", "purple")),
+                Field.exists("sub")), FieldMatch.ALL);
+        checkByFieldsMatch(output.toString());
+    }
+
+    private static void checkByFieldsMatchOrdered(String json) throws DocumentException {
         switch (Configuration.dialect()) {
             case SQLITE:
                 assertEquals(String.format("[%s,%s]", JsonDocument.five, JsonDocument.four), json,
@@ -146,9 +219,22 @@ final public class JsonFunctions {
         }
     }
 
-    public static void byFieldsMatchNumIn(ThrowawayDatabase db) throws DocumentException {
+    public static void byFieldsMatchOrdered(ThrowawayDatabase db) throws DocumentException {
         JsonDocument.load(db);
-        final String json = jsonByFields(db.getConn(), TEST_TABLE, List.of(Field.any("numValue", List.of(2, 4, 6, 8))));
+        checkByFieldsMatchOrdered(jsonByFields(db.getConn(), TEST_TABLE, List.of(Field.equal("value", "purple")), null,
+                List.of(Field.named("id"))));
+    }
+
+    public static void writeByFieldsMatchOrdered(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonByFields(db.getConn(), TEST_TABLE, writer, List.of(Field.equal("value", "purple")), null,
+                List.of(Field.named("id")));
+        checkByFieldsMatchOrdered(output.toString());
+    }
+
+    private static void checkByFieldsMatchNumIn(String json) throws DocumentException {
         switch (Configuration.dialect()) {
             case SQLITE:
                 assertEquals(String.format("[%s]", JsonDocument.three), json, "The incorrect document was returned");
@@ -162,32 +248,77 @@ final public class JsonFunctions {
         }
     }
 
-    public static void byFieldsNoMatch(ThrowawayDatabase db) throws DocumentException {
+    public static void byFieldsMatchNumIn(ThrowawayDatabase db) throws DocumentException {
         JsonDocument.load(db);
-        assertEquals("[]", jsonByFields(db.getConn(), TEST_TABLE, List.of(Field.greater("numValue", 100))),
+        checkByFieldsMatchNumIn(jsonByFields(db.getConn(), TEST_TABLE,
-                "There should have been no documents returned");
+                List.of(Field.any("numValue", List.of(2, 4, 6, 8)))));
     }
 
-    public static void byFieldsMatchInArray(ThrowawayDatabase db) throws DocumentException {
+    public static void writeByFieldsMatchNumIn(ThrowawayDatabase db) throws DocumentException {
-        for (ArrayDocument doc : ArrayDocument.testDocuments) { insert(db.getConn(), TEST_TABLE, doc); }
+        JsonDocument.load(db);
-        final String json = jsonByFields(db.getConn(), TEST_TABLE, List.of(Field.inArray("values", TEST_TABLE,
+        final StringWriter output = new StringWriter();
-                List.of("c"))));
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonByFields(db.getConn(), TEST_TABLE, writer, List.of(Field.any("numValue", List.of(2, 4, 6, 8))));
+        checkByFieldsMatchNumIn(output.toString());
+    }
+
+    private static void checkByFieldsNoMatch(String json) {
+        assertEquals("[]", json, "There should have been no documents returned");
+    }
+
+    public static void byFieldsNoMatch(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        checkByFieldsNoMatch(jsonByFields(db.getConn(), TEST_TABLE, List.of(Field.greater("numValue", 100))));
+    }
+
+    public static void writeByFieldsNoMatch(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonByFields(db.getConn(), TEST_TABLE, writer, List.of(Field.greater("numValue", 100)));
+        checkByFieldsNoMatch(output.toString());
+    }
+
+    private static void checkByFieldsMatchInArray(String json) throws DocumentException {
         assertTrue(json.startsWith("["), String.format("JSON should start with '[' (%s)", json));
         assertTrue(json.contains(docId("first")), String.format("The 'first' document was not found (%s)", json));
         assertTrue(json.contains(docId("second")), String.format("The 'second' document was not found (%s)", json));
         assertTrue(json.endsWith("]"), String.format("JSON should end with ']' (%s)", json));
     }
 
-    public static void byFieldsNoMatchInArray(ThrowawayDatabase db) throws DocumentException {
+    public static void byFieldsMatchInArray(ThrowawayDatabase db) throws DocumentException {
         for (ArrayDocument doc : ArrayDocument.testDocuments) { insert(db.getConn(), TEST_TABLE, doc); }
-        assertEquals("[]",
+        checkByFieldsMatchInArray(jsonByFields(db.getConn(), TEST_TABLE, List.of(Field.inArray("values", TEST_TABLE,
-                jsonByFields(db.getConn(), TEST_TABLE, List.of(Field.inArray("values", TEST_TABLE, List.of("j")))),
+                List.of("c")))));
-                "There should have been no documents returned");
     }
 
-    public static void byContainsMatch(ThrowawayDatabase db) throws DocumentException {
+    public static void writeByFieldsMatchInArray(ThrowawayDatabase db) throws DocumentException {
-        JsonDocument.load(db);
+        for (ArrayDocument doc : ArrayDocument.testDocuments) { insert(db.getConn(), TEST_TABLE, doc); }
-        final String json = jsonByContains(db.getConn(), TEST_TABLE, Map.of("value", "purple"));
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonByFields(db.getConn(), TEST_TABLE, writer, List.of(Field.inArray("values", TEST_TABLE, List.of("c"))));
+        checkByFieldsMatchInArray(output.toString());
+    }
+
+    private static void checkByFieldsNoMatchInArray(String json) {
+        assertEquals("[]", json, "There should have been no documents returned");
+    }
+
+    public static void byFieldsNoMatchInArray(ThrowawayDatabase db) throws DocumentException {
+        for (ArrayDocument doc : ArrayDocument.testDocuments) { insert(db.getConn(), TEST_TABLE, doc); }
+        checkByFieldsNoMatchInArray(jsonByFields(db.getConn(), TEST_TABLE,
+                List.of(Field.inArray("values", TEST_TABLE, List.of("j")))));
+    }
+
+    public static void writeByFieldsNoMatchInArray(ThrowawayDatabase db) throws DocumentException {
+        for (ArrayDocument doc : ArrayDocument.testDocuments) { insert(db.getConn(), TEST_TABLE, doc); }
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonByFields(db.getConn(), TEST_TABLE, writer, List.of(Field.inArray("values", TEST_TABLE, List.of("j"))));
+        checkByFieldsNoMatchInArray(output.toString());
+    }
+
+    private static void checkByContainsMatch(String json) throws DocumentException {
         assertTrue(json.startsWith("["), String.format("JSON should start with '[' (%s)", json));
         switch (Configuration.dialect()) {
             case SQLITE:
@@ -202,10 +333,20 @@ final public class JsonFunctions {
         assertTrue(json.endsWith("]"), String.format("JSON should end with ']' (%s)", json));
     }
 
-    public static void byContainsMatchOrdered(ThrowawayDatabase db) throws DocumentException {
+    public static void byContainsMatch(ThrowawayDatabase db) throws DocumentException {
         JsonDocument.load(db);
-        final String json = jsonByContains(db.getConn(), TEST_TABLE, Map.of("sub", Map.of("foo", "green")),
+        checkByContainsMatch(jsonByContains(db.getConn(), TEST_TABLE, Map.of("value", "purple")));
-                List.of(Field.named("value")));
+    }
+
+    public static void writeByContainsMatch(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonByContains(db.getConn(), TEST_TABLE, writer, Map.of("value", "purple"));
+        checkByContainsMatch(output.toString());
+    }
+
+    private static void checkByContainsMatchOrdered(String json) throws DocumentException {
         switch (Configuration.dialect()) {
             case SQLITE:
                 assertEquals(String.format("[%s,%s]", JsonDocument.two, JsonDocument.four), json,
@@ -223,15 +364,39 @@ final public class JsonFunctions {
         }
     }
 
-    public static void byContainsNoMatch(ThrowawayDatabase db) throws DocumentException {
+    public static void byContainsMatchOrdered(ThrowawayDatabase db) throws DocumentException {
         JsonDocument.load(db);
-        assertEquals("[]", jsonByContains(db.getConn(), TEST_TABLE, Map.of("value", "indigo")),
+        checkByContainsMatchOrdered(jsonByContains(db.getConn(), TEST_TABLE, Map.of("sub", Map.of("foo", "green")),
-                "There should have been no documents returned");
+                List.of(Field.named("value"))));
     }
 
-    public static void byJsonPathMatch(ThrowawayDatabase db) throws DocumentException {
+    public static void writeByContainsMatchOrdered(ThrowawayDatabase db) throws DocumentException {
         JsonDocument.load(db);
-        final String json = jsonByJsonPath(db.getConn(), TEST_TABLE, "$.numValue ? (@ > 10)");
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonByContains(db.getConn(), TEST_TABLE, writer, Map.of("sub", Map.of("foo", "green")),
+                List.of(Field.named("value")));
+        checkByContainsMatchOrdered(output.toString());
+    }
+
+    private static void checkByContainsNoMatch(String json) {
+        assertEquals("[]", json, "There should have been no documents returned");
+    }
+
+    public static void byContainsNoMatch(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        checkByContainsNoMatch(jsonByContains(db.getConn(), TEST_TABLE, Map.of("value", "indigo")));
+    }
+
+    public static void writeByContainsNoMatch(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonByContains(db.getConn(), TEST_TABLE, writer, Map.of("value", "indigo"));
+        checkByContainsNoMatch(output.toString());
+    }
+
+    private static void checkByJsonPathMatch(String json) throws DocumentException {
         assertTrue(json.startsWith("["), String.format("JSON should start with '[' (%s)", json));
         switch (Configuration.dialect()) {
             case SQLITE:
@@ -246,10 +411,20 @@ final public class JsonFunctions {
         assertTrue(json.endsWith("]"), String.format("JSON should end with ']' (%s)", json));
     }
 
-    public static void byJsonPathMatchOrdered(ThrowawayDatabase db) throws DocumentException {
+    public static void byJsonPathMatch(ThrowawayDatabase db) throws DocumentException {
         JsonDocument.load(db);
-        final String json = jsonByJsonPath(db.getConn(), TEST_TABLE, "$.numValue ? (@ > 10)",
+        checkByJsonPathMatch(jsonByJsonPath(db.getConn(), TEST_TABLE, "$.numValue ? (@ > 10)"));
-                List.of(Field.named("id")));
+    }
+
+    public static void writeByJsonPathMatch(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonByJsonPath(db.getConn(), TEST_TABLE, writer, "$.numValue ? (@ > 10)");
+        checkByJsonPathMatch(output.toString());
+    }
+
+    private static void checkByJsonPathMatchOrdered(String json) throws DocumentException {
         switch (Configuration.dialect()) {
             case SQLITE:
                 assertEquals(String.format("[%s,%s]", JsonDocument.five, JsonDocument.four), json,
@@ -268,15 +443,38 @@ final public class JsonFunctions {
         }
     }
 
-    public static void byJsonPathNoMatch(ThrowawayDatabase db) throws DocumentException {
+    public static void byJsonPathMatchOrdered(ThrowawayDatabase db) throws DocumentException {
         JsonDocument.load(db);
-        assertEquals("[]", jsonByJsonPath(db.getConn(), TEST_TABLE, "$.numValue ? (@ > 100)"),
+        checkByJsonPathMatchOrdered(jsonByJsonPath(db.getConn(), TEST_TABLE, "$.numValue ? (@ > 10)",
-                "There should have been no documents returned");
+                List.of(Field.named("id"))));
     }
 
-    public static void firstByFieldsMatchOne(ThrowawayDatabase db) throws DocumentException {
+    public static void writeByJsonPathMatchOrdered(ThrowawayDatabase db) throws DocumentException {
         JsonDocument.load(db);
-        final String json = jsonFirstByFields(db.getConn(), TEST_TABLE, List.of(Field.equal("value", "another")));
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonByJsonPath(db.getConn(), TEST_TABLE, writer, "$.numValue ? (@ > 10)", List.of(Field.named("id")));
+        checkByJsonPathMatchOrdered(output.toString());
+    }
+
+    private static void checkByJsonPathNoMatch(String json) {
+        assertEquals("[]", json, "There should have been no documents returned");
+    }
+
+    public static void byJsonPathNoMatch(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        checkByJsonPathNoMatch(jsonByJsonPath(db.getConn(), TEST_TABLE, "$.numValue ? (@ > 100)"));
+    }
+
+    public static void writeByJsonPathNoMatch(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonByJsonPath(db.getConn(), TEST_TABLE, writer, "$.numValue ? (@ > 100)");
+        checkByJsonPathNoMatch(output.toString());
+    }
+
+    private static void checkFirstByFieldsMatchOne(String json) throws DocumentException {
         switch (Configuration.dialect()) {
             case SQLITE:
                 assertEquals(JsonDocument.two, json, "The incorrect document was returned");
@@ -288,9 +486,21 @@ final public class JsonFunctions {
         }
     }
 
-    public static void firstByFieldsMatchMany(ThrowawayDatabase db) throws DocumentException {
+    public static void firstByFieldsMatchOne(ThrowawayDatabase db) throws DocumentException {
         JsonDocument.load(db);
-        final String json = jsonFirstByFields(db.getConn(), TEST_TABLE, List.of(Field.equal("sub.foo", "green")));
+        checkFirstByFieldsMatchOne(jsonFirstByFields(db.getConn(), TEST_TABLE,
+                List.of(Field.equal("value", "another"))));
+    }
+
+    public static void writeFirstByFieldsMatchOne(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonFirstByFields(db.getConn(), TEST_TABLE, writer, List.of(Field.equal("value", "another")));
+        checkFirstByFieldsMatchOne(output.toString());
+    }
+
+    private static void checkFirstByFieldsMatchMany(String json) throws DocumentException {
         switch (Configuration.dialect()) {
             case SQLITE:
                 assertTrue(json.contains(JsonDocument.two) || json.contains(JsonDocument.four),
@@ -303,10 +513,21 @@ final public class JsonFunctions {
         }
     }
 
-    public static void firstByFieldsMatchOrdered(ThrowawayDatabase db) throws DocumentException {
+    public static void firstByFieldsMatchMany(ThrowawayDatabase db) throws DocumentException {
         JsonDocument.load(db);
-        final String json = jsonFirstByFields(db.getConn(), TEST_TABLE, List.of(Field.equal("sub.foo", "green")), null,
+        checkFirstByFieldsMatchMany(jsonFirstByFields(db.getConn(), TEST_TABLE,
-                List.of(Field.named("n:numValue DESC")));
+                List.of(Field.equal("sub.foo", "green"))));
+    }
+
+    public static void writeFirstByFieldsMatchMany(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonFirstByFields(db.getConn(), TEST_TABLE, writer, List.of(Field.equal("sub.foo", "green")));
+        checkFirstByFieldsMatchMany(output.toString());
+    }
+
+    private static void checkFirstByFieldsMatchOrdered(String json) throws DocumentException {
         switch (Configuration.dialect()) {
             case SQLITE:
                 assertEquals(JsonDocument.four, json, "An incorrect document was returned");
@@ -318,15 +539,39 @@ final public class JsonFunctions {
         }
     }
 
-    public static void firstByFieldsNoMatch(ThrowawayDatabase db) throws DocumentException {
+    public static void firstByFieldsMatchOrdered(ThrowawayDatabase db) throws DocumentException {
         JsonDocument.load(db);
-        assertEquals("{}", jsonFirstByFields(db.getConn(), TEST_TABLE, List.of(Field.equal("value", "absent"))),
+        checkFirstByFieldsMatchOrdered(jsonFirstByFields(db.getConn(), TEST_TABLE,
-                "There should have been no document returned");
+                List.of(Field.equal("sub.foo", "green")), null, List.of(Field.named("n:numValue DESC"))));
     }
 
-    public static void firstByContainsMatchOne(ThrowawayDatabase db) throws DocumentException {
+    public static void writeFirstByFieldsMatchOrdered(ThrowawayDatabase db) throws DocumentException {
         JsonDocument.load(db);
-        final String json = jsonFirstByContains(db.getConn(), TEST_TABLE, Map.of("value", "FIRST!"));
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonFirstByFields(db.getConn(), TEST_TABLE, writer, List.of(Field.equal("sub.foo", "green")), null,
+                List.of(Field.named("n:numValue DESC")));
+        checkFirstByFieldsMatchOrdered(output.toString());
+    }
+
+    private static void checkFirstByFieldsNoMatch(String json) {
+        assertEquals("{}", json, "There should have been no document returned");
+    }
+
+    public static void firstByFieldsNoMatch(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        checkFirstByFieldsNoMatch(jsonFirstByFields(db.getConn(), TEST_TABLE, List.of(Field.equal("value", "absent"))));
+    }
+
+    public static void writeFirstByFieldsNoMatch(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonFirstByFields(db.getConn(), TEST_TABLE, writer, List.of(Field.equal("value", "absent")));
+        checkFirstByFieldsNoMatch(output.toString());
+    }
+
+    private static void checkFirstByContainsMatchOne(String json) throws DocumentException {
         switch (Configuration.dialect()) {
             case SQLITE:
                 assertEquals(JsonDocument.one, json, "An incorrect document was returned");
@@ -337,9 +582,20 @@ final public class JsonFunctions {
         }
     }
 
-    public static void firstByContainsMatchMany(ThrowawayDatabase db) throws DocumentException {
+    public static void firstByContainsMatchOne(ThrowawayDatabase db) throws DocumentException {
         JsonDocument.load(db);
-        final String json = jsonFirstByContains(db.getConn(), TEST_TABLE, Map.of("value", "purple"));
+        checkFirstByContainsMatchOne(jsonFirstByContains(db.getConn(), TEST_TABLE, Map.of("value", "FIRST!")));
+    }
+
+    public static void writeFirstByContainsMatchOne(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonFirstByContains(db.getConn(), TEST_TABLE, writer, Map.of("value", "FIRST!"));
+        checkFirstByContainsMatchOne(output.toString());
+    }
+
+    private static void checkFirstByContainsMatchMany(String json) throws DocumentException {
         switch (Configuration.dialect()) {
             case SQLITE:
                 assertTrue(json.contains(JsonDocument.four) || json.contains(JsonDocument.five),
@@ -352,10 +608,20 @@ final public class JsonFunctions {
         }
     }
 
-    public static void firstByContainsMatchOrdered(ThrowawayDatabase db) throws DocumentException {
+    public static void firstByContainsMatchMany(ThrowawayDatabase db) throws DocumentException {
         JsonDocument.load(db);
-        final String json = jsonFirstByContains(db.getConn(), TEST_TABLE, Map.of("value", "purple"),
+        checkFirstByContainsMatchMany(jsonFirstByContains(db.getConn(), TEST_TABLE, Map.of("value", "purple")));
-                List.of(Field.named("sub.bar NULLS FIRST")));
+    }
+
+    public static void writeFirstByContainsMatchMany(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonFirstByContains(db.getConn(), TEST_TABLE, writer, Map.of("value", "purple"));
+        checkFirstByContainsMatchMany(output.toString());
+    }
+
+    private static void checkFirstByContainsMatchOrdered(String json) throws DocumentException {
         switch (Configuration.dialect()) {
             case SQLITE:
                 assertEquals(JsonDocument.five, json, "An incorrect document was returned");
@@ -367,15 +633,39 @@ final public class JsonFunctions {
         }
     }
 
-    public static void firstByContainsNoMatch(ThrowawayDatabase db) throws DocumentException {
+    public static void firstByContainsMatchOrdered(ThrowawayDatabase db) throws DocumentException {
         JsonDocument.load(db);
-        assertEquals("{}", jsonFirstByContains(db.getConn(), TEST_TABLE, Map.of("value", "indigo")),
+        checkFirstByContainsMatchOrdered(jsonFirstByContains(db.getConn(), TEST_TABLE, Map.of("value", "purple"),
-                "There should have been no document returned");
+                List.of(Field.named("sub.bar NULLS FIRST"))));
     }
 
-    public static void firstByJsonPathMatchOne(ThrowawayDatabase db) throws DocumentException {
+    public static void writeFirstByContainsMatchOrdered(ThrowawayDatabase db) throws DocumentException {
         JsonDocument.load(db);
-        final String json = jsonFirstByJsonPath(db.getConn(), TEST_TABLE, "$.numValue ? (@ == 10)");
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonFirstByContains(db.getConn(), TEST_TABLE, writer, Map.of("value", "purple"),
+                List.of(Field.named("sub.bar NULLS FIRST")));
+        checkFirstByContainsMatchOrdered(output.toString());
+    }
+
+    private static void checkFirstByContainsNoMatch(String json) {
+        assertEquals("{}", json, "There should have been no document returned");
+    }
+
+    public static void firstByContainsNoMatch(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        checkFirstByContainsNoMatch(jsonFirstByContains(db.getConn(), TEST_TABLE, Map.of("value", "indigo")));
+    }
+
+    public static void writeFirstByContainsNoMatch(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonFirstByContains(db.getConn(), TEST_TABLE, writer, Map.of("value", "indigo"));
+        checkFirstByContainsNoMatch(output.toString());
+    }
+
+    private static void checkFirstByJsonPathMatchOne(String json) throws DocumentException {
         switch (Configuration.dialect()) {
             case SQLITE:
                 assertEquals(JsonDocument.two, json, "An incorrect document was returned");
@@ -386,9 +676,20 @@ final public class JsonFunctions {
         }
     }
 
-    public static void firstByJsonPathMatchMany(ThrowawayDatabase db) throws DocumentException {
+    public static void firstByJsonPathMatchOne(ThrowawayDatabase db) throws DocumentException {
         JsonDocument.load(db);
-        final String json = jsonFirstByJsonPath(db.getConn(), TEST_TABLE, "$.numValue ? (@ > 10)");
+        checkFirstByJsonPathMatchOne(jsonFirstByJsonPath(db.getConn(), TEST_TABLE, "$.numValue ? (@ == 10)"));
+    }
+
+    public static void writeFirstByJsonPathMatchOne(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonFirstByJsonPath(db.getConn(), TEST_TABLE, writer, "$.numValue ? (@ == 10)");
+        checkFirstByJsonPathMatchOne(output.toString());
+    }
+
+    private static void checkFirstByJsonPathMatchMany(String json) throws DocumentException {
         switch (Configuration.dialect()) {
             case SQLITE:
                 assertTrue(json.contains(JsonDocument.four) || json.contains(JsonDocument.five),
@@ -401,10 +702,20 @@ final public class JsonFunctions {
         }
     }
 
-    public static void firstByJsonPathMatchOrdered(ThrowawayDatabase db) throws DocumentException {
+    public static void firstByJsonPathMatchMany(ThrowawayDatabase db) throws DocumentException {
         JsonDocument.load(db);
-        final String json = jsonFirstByJsonPath(db.getConn(), TEST_TABLE, "$.numValue ? (@ > 10)",
+        checkFirstByJsonPathMatchMany(jsonFirstByJsonPath(db.getConn(), TEST_TABLE, "$.numValue ? (@ > 10)"));
-                List.of(Field.named("id DESC")));
+    }
+
+    public static void writeFirstByJsonPathMatchMany(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonFirstByJsonPath(db.getConn(), TEST_TABLE, writer, "$.numValue ? (@ > 10)");
+        checkFirstByJsonPathMatchMany(output.toString());
+    }
+
+    private static void checkFirstByJsonPathMatchOrdered(String json) throws DocumentException {
         switch (Configuration.dialect()) {
             case SQLITE:
                 assertEquals(JsonDocument.four, json, "An incorrect document was returned");
@@ -416,9 +727,35 @@ final public class JsonFunctions {
         }
     }
 
+    public static void firstByJsonPathMatchOrdered(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        checkFirstByJsonPathMatchOrdered(jsonFirstByJsonPath(db.getConn(), TEST_TABLE, "$.numValue ? (@ > 10)",
+                List.of(Field.named("id DESC"))));
+    }
+
+    public static void writeFirstByJsonPathMatchOrdered(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonFirstByJsonPath(db.getConn(), TEST_TABLE, writer, "$.numValue ? (@ > 10)",
+                List.of(Field.named("id DESC")));
+        checkFirstByJsonPathMatchOrdered(output.toString());
+    }
+
+    private static void checkFirstByJsonPathNoMatch(String json) {
+        assertEquals("{}", json, "There should have been no document returned");
+    }
+
     public static void firstByJsonPathNoMatch(ThrowawayDatabase db) throws DocumentException {
         JsonDocument.load(db);
-        assertEquals("{}", jsonFirstByJsonPath(db.getConn(), TEST_TABLE, "$.numValue ? (@ > 100)"),
+        checkFirstByJsonPathNoMatch(jsonFirstByJsonPath(db.getConn(), TEST_TABLE, "$.numValue ? (@ > 100)"));
-                "There should have been no document returned");
+    }
+
+    public static void writeFirstByJsonPathNoMatch(ThrowawayDatabase db) throws DocumentException {
+        JsonDocument.load(db);
+        final StringWriter output = new StringWriter();
+        final PrintWriter writer = new PrintWriter(output);
+        writeJsonFirstByJsonPath(db.getConn(), TEST_TABLE, writer, "$.numValue ? (@ > 100)");
+        checkFirstByJsonPathNoMatch(output.toString());
     }
 }

src/core/src/test/java/solutions/bitbadger/documents/core/tests/java/integration/PostgreSQLJsonIT.java

@@ -242,4 +242,236 @@ final public class PostgreSQLJsonIT {
             JsonFunctions.firstByJsonPathNoMatch(db);
         }
     }
+
+    @Test
+    @DisplayName("writeAll retrieves all documents")
+    public void writeAllDefault() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeAllDefault(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeAll succeeds with an empty table")
+    public void writeAllEmpty() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeAllEmpty(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeById retrieves a document via a string ID")
+    public void writeByIdString() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeByIdString(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeById retrieves a document via a numeric ID")
+    public void writeByIdNumber() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeByIdNumber(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeById returns null when a matching ID is not found")
+    public void writeByIdNotFound() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeByIdNotFound(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeByFields retrieves matching documents")
+    public void writeByFieldsMatch() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeByFieldsMatch(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeByFields retrieves ordered matching documents")
+    public void writeByFieldsMatchOrdered() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeByFieldsMatchOrdered(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeByFields retrieves matching documents with a numeric IN clause")
+    public void writeByFieldsMatchNumIn() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeByFieldsMatchNumIn(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeByFields succeeds when no documents match")
+    public void writeByFieldsNoMatch() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeByFieldsNoMatch(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeByFields retrieves matching documents with an IN_ARRAY comparison")
+    public void writeByFieldsMatchInArray() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeByFieldsMatchInArray(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeByFields succeeds when no documents match an IN_ARRAY comparison")
+    public void writeByFieldsNoMatchInArray() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeByFieldsNoMatchInArray(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeByContains retrieves matching documents")
+    public void writeByContainsMatch() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeByContainsMatch(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeByContains retrieves ordered matching documents")
+    public void writeByContainsMatchOrdered() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeByContainsMatchOrdered(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeByContains succeeds when no documents match")
+    public void writeByContainsNoMatch() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeByContainsNoMatch(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeByJsonPath retrieves matching documents")
+    public void writeByJsonPathMatch() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeByJsonPathMatch(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeByJsonPath retrieves ordered matching documents")
+    public void writeByJsonPathMatchOrdered() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeByJsonPathMatchOrdered(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeByJsonPath succeeds when no documents match")
+    public void writeByJsonPathNoMatch() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeByJsonPathNoMatch(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeFirstByFields retrieves a matching document")
+    public void writeFirstByFieldsMatchOne() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeFirstByFieldsMatchOne(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeFirstByFields retrieves a matching document among many")
+    public void writeFirstByFieldsMatchMany() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeFirstByFieldsMatchMany(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeFirstByFields retrieves a matching document among many (ordered)")
+    public void writeFirstByFieldsMatchOrdered() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeFirstByFieldsMatchOrdered(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeFirstByFields returns null when no document matches")
+    public void writeFirstByFieldsNoMatch() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeFirstByFieldsNoMatch(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeFirstByContains retrieves a matching document")
+    public void writeFirstByContainsMatchOne() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeFirstByContainsMatchOne(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeFirstByContains retrieves a matching document among many")
+    public void writeFirstByContainsMatchMany() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeFirstByContainsMatchMany(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeFirstByContains retrieves a matching document among many (ordered)")
+    public void writeFirstByContainsMatchOrdered() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeFirstByContainsMatchOrdered(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeFirstByContains returns null when no document matches")
+    public void writeFirstByContainsNoMatch() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeFirstByContainsNoMatch(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeFirstByJsonPath retrieves a matching document")
+    public void writeFirstByJsonPathMatchOne() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeFirstByJsonPathMatchOne(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeFirstByJsonPath retrieves a matching document among many")
+    public void writeFirstByJsonPathMatchMany() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeFirstByJsonPathMatchMany(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeFirstByJsonPath retrieves a matching document among many (ordered)")
+    public void writeFirstByJsonPathMatchOrdered() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeFirstByJsonPathMatchOrdered(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeFirstByJsonPath returns null when no document matches")
+    public void writeFirstByJsonPathNoMatch() throws DocumentException {
+        try (PgDB db = new PgDB()) {
+            JsonFunctions.writeFirstByJsonPathNoMatch(db);
+        }
+    }
 }

src/core/src/test/java/solutions/bitbadger/documents/core/tests/java/integration/SQLiteJsonIT.java

@@ -164,4 +164,156 @@ final public class SQLiteJsonIT {
             assertThrows(DocumentException.class, () -> JsonFunctions.firstByJsonPathMatchOne(db));
         }
     }
+
+    @Test
+    @DisplayName("writeAll retrieves all documents")
+    public void writeAllDefault() throws DocumentException {
+        try (SQLiteDB db = new SQLiteDB()) {
+            JsonFunctions.writeAllDefault(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeAll succeeds with an empty table")
+    public void writeAllEmpty() throws DocumentException {
+        try (SQLiteDB db = new SQLiteDB()) {
+            JsonFunctions.writeAllEmpty(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeById retrieves a document via a string ID")
+    public void writeByIdString() throws DocumentException {
+        try (SQLiteDB db = new SQLiteDB()) {
+            JsonFunctions.writeByIdString(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeById retrieves a document via a numeric ID")
+    public void writeByIdNumber() throws DocumentException {
+        try (SQLiteDB db = new SQLiteDB()) {
+            JsonFunctions.writeByIdNumber(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeById returns null when a matching ID is not found")
+    public void writeByIdNotFound() throws DocumentException {
+        try (SQLiteDB db = new SQLiteDB()) {
+            JsonFunctions.writeByIdNotFound(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeByFields retrieves matching documents")
+    public void writeByFieldsMatch() throws DocumentException {
+        try (SQLiteDB db = new SQLiteDB()) {
+            JsonFunctions.writeByFieldsMatch(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeByFields retrieves ordered matching documents")
+    public void writeByFieldsMatchOrdered() throws DocumentException {
+        try (SQLiteDB db = new SQLiteDB()) {
+            JsonFunctions.writeByFieldsMatchOrdered(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeByFields retrieves matching documents with a numeric IN clause")
+    public void writeByFieldsMatchNumIn() throws DocumentException {
+        try (SQLiteDB db = new SQLiteDB()) {
+            JsonFunctions.writeByFieldsMatchNumIn(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeByFields succeeds when no documents match")
+    public void writeByFieldsNoMatch() throws DocumentException {
+        try (SQLiteDB db = new SQLiteDB()) {
+            JsonFunctions.writeByFieldsNoMatch(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeByFields retrieves matching documents with an IN_ARRAY comparison")
+    public void writeByFieldsMatchInArray() throws DocumentException {
+        try (SQLiteDB db = new SQLiteDB()) {
+            JsonFunctions.writeByFieldsMatchInArray(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeByFields succeeds when no documents match an IN_ARRAY comparison")
+    public void writeByFieldsNoMatchInArray() throws DocumentException {
+        try (SQLiteDB db = new SQLiteDB()) {
+            JsonFunctions.writeByFieldsNoMatchInArray(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeByContains fails")
+    public void writeByContainsFails() {
+        try (SQLiteDB db = new SQLiteDB()) {
+            assertThrows(DocumentException.class, () -> JsonFunctions.writeByContainsMatch(db));
+        }
+    }
+
+    @Test
+    @DisplayName("writeByJsonPath fails")
+    public void writeByJsonPathFails() {
+        try (SQLiteDB db = new SQLiteDB()) {
+            assertThrows(DocumentException.class, () -> JsonFunctions.writeByJsonPathMatch(db));
+        }
+    }
+
+    @Test
+    @DisplayName("writeFirstByFields retrieves a matching document")
+    public void writeFirstByFieldsMatchOne() throws DocumentException {
+        try (SQLiteDB db = new SQLiteDB()) {
+            JsonFunctions.writeFirstByFieldsMatchOne(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeFirstByFields retrieves a matching document among many")
+    public void writeFirstByFieldsMatchMany() throws DocumentException {
+        try (SQLiteDB db = new SQLiteDB()) {
+            JsonFunctions.writeFirstByFieldsMatchMany(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeFirstByFields retrieves a matching document among many (ordered)")
+    public void writeFirstByFieldsMatchOrdered() throws DocumentException {
+        try (SQLiteDB db = new SQLiteDB()) {
+            JsonFunctions.writeFirstByFieldsMatchOrdered(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeFirstByFields returns null when no document matches")
+    public void writeFirstByFieldsNoMatch() throws DocumentException {
+        try (SQLiteDB db = new SQLiteDB()) {
+            JsonFunctions.writeFirstByFieldsNoMatch(db);
+        }
+    }
+
+    @Test
+    @DisplayName("writeFirstByContains fails")
+    public void writeFirstByContainsFails() {
+        try (SQLiteDB db = new SQLiteDB()) {
+            assertThrows(DocumentException.class, () -> JsonFunctions.writeFirstByContainsMatchOne(db));
+        }
+    }
+
+    @Test
+    @DisplayName("writeFirstByJsonPath fails")
+    public void writeFirstByJsonPathFails() {
+        try (SQLiteDB db = new SQLiteDB()) {
+            assertThrows(DocumentException.class, () -> JsonFunctions.writeFirstByJsonPathMatchOne(db));
+        }
+    }
 }

src/core/src/test/kotlin/integration/PgDB.kt

@@ -2,24 +2,17 @@ package solutions.bitbadger.documents.core.tests.integration
 
 import solutions.bitbadger.documents.*
 import solutions.bitbadger.documents.core.tests.TEST_TABLE
-import solutions.bitbadger.documents.java.DocumentConfig
 import solutions.bitbadger.documents.java.Results
 import solutions.bitbadger.documents.java.extensions.*
 
 /**
  * A wrapper for a throwaway PostgreSQL database
  */
-class PgDB : ThrowawayDatabase {
+class PgDB : ThrowawayDatabase() {
-
-    private var dbName = ""
 
     init {
-        DocumentConfig.serializer = JacksonDocumentSerializer()
-        dbName = "throwaway_${AutoId.generateRandomString(8)}"
         Configuration.connectionString = connString("postgres")
-        Configuration.dbConn().use {
+        Configuration.dbConn().use { it.customNonQuery("CREATE DATABASE $dbName") }
-            it.customNonQuery("CREATE DATABASE $dbName")
-        }
         Configuration.connectionString = connString(dbName)
     }
 
@@ -32,9 +25,7 @@ class PgDB : ThrowawayDatabase {
     override fun close() {
         conn.close()
         Configuration.connectionString = connString("postgres")
-        Configuration.dbConn().use {
+        Configuration.dbConn().use { it.customNonQuery("DROP DATABASE $dbName") }
-            it.customNonQuery("DROP DATABASE $dbName")
-        }
         Configuration.connectionString = null
     }
 

src/core/src/test/kotlin/integration/SQLiteDB.kt

@@ -2,7 +2,6 @@ package solutions.bitbadger.documents.core.tests.integration
 
 import solutions.bitbadger.documents.*
 import solutions.bitbadger.documents.core.tests.TEST_TABLE
-import solutions.bitbadger.documents.java.DocumentConfig
 import solutions.bitbadger.documents.java.Results
 import solutions.bitbadger.documents.java.extensions.*
 import java.io.File
@@ -10,13 +9,9 @@ import java.io.File
 /**
  * A wrapper for a throwaway SQLite database
  */
-class SQLiteDB : ThrowawayDatabase {
+class SQLiteDB : ThrowawayDatabase() {
-
-    private var dbName = ""
 
     init {
-        DocumentConfig.serializer = JacksonDocumentSerializer()
-        dbName = "test-db-${AutoId.generateRandomString(8)}.db"
         Configuration.connectionString = "jdbc:sqlite:$dbName"
     }
 

src/core/src/test/kotlin/integration/ThrowawayDatabase.kt

@@ -1,14 +1,23 @@
 package solutions.bitbadger.documents.core.tests.integration
 
+import solutions.bitbadger.documents.AutoId
+import solutions.bitbadger.documents.java.DocumentConfig
 import java.sql.Connection
 
 /**
  * Common interface for PostgreSQL and SQLite throwaway databases
  */
-interface ThrowawayDatabase : AutoCloseable {
+abstract class ThrowawayDatabase : AutoCloseable {
+
+    /** The name of the throwaway database */
+    protected val dbName = "throwaway_${AutoId.generateRandomString(8)}"
+
+    init {
+        DocumentConfig.serializer = JacksonDocumentSerializer()
+    }
 
     /** The database connection for the throwaway database */
-    val conn: Connection
+    abstract val conn: Connection
 
     /**
      * Determine if a database object exists
@@ -16,5 +25,5 @@ interface ThrowawayDatabase : AutoCloseable {
      * @param name The name of the object whose existence should be checked
      * @return True if the object exists, false if not
      */
-    fun dbObjectExists(name: String): Boolean
+    abstract fun dbObjectExists(name: String): Boolean
 }