F!! Better help message for circular references in Gson

Author: ScottBob

approvaltests-tests/src/test/java/org/approvaltests/Circular.java

@@ -0,0 +1,18 @@
+package org.approvaltests;
+
+public class Circular {
+    Circular parent;
+    String label;
+
+    public Circular(Circular parent, String label) {
+        this.parent = parent;
+        this.label = label;
+    }
+
+    public static Circular getIndirectCircularReference() {
+        Circular level1 = new Circular(null, "middle");
+        Circular level2 = new Circular(level1, "child");
+        level1.parent = level2;
+        return level1;
+    }
+}

approvaltests-tests/src/test/java/org/approvaltests/DocumentHelpersTest.listAllVerifyFunctions.approved.md

@@ -50,8 +50,8 @@
  * CombinationApprovals. [verifyBestCoveringPairs ](https://github.com/approvals/ApprovalTests.Java/blob/master/approvaltests/src/main/java/org/approvaltests/combinations/CombinationApprovals.java#L290-L293) (Function7,Object[],Object[],Object[],Object[],Object[],Object[],Object[])  
  * CombinationApprovals. [verifyBestCoveringPairs ](https://github.com/approvals/ApprovalTests.Java/blob/master/approvaltests/src/main/java/org/approvaltests/combinations/CombinationApprovals.java#L308-L311) (Function8,Object[],Object[],Object[],Object[],Object[],Object[],Object[],Object[])  
  * CombinationApprovals. [verifyBestCoveringPairs ](https://github.com/approvals/ApprovalTests.Java/blob/master/approvaltests/src/main/java/org/approvaltests/combinations/CombinationApprovals.java#L326-L329) (Function9,Object[],Object[],Object[],Object[],Object[],Object[],Object[],Object[],Object[])  
- * JsonApprovals. [verifyAsJson ](https://github.com/approvals/ApprovalTests.Java/blob/master/approvaltests/src/main/java/org/approvaltests/JsonApprovals.java#L25-L28) (Object)  
- * JsonApprovals. [verifyAsJson ](https://github.com/approvals/ApprovalTests.Java/blob/master/approvaltests/src/main/java/org/approvaltests/JsonApprovals.java#L29-L32) (Object,Function1)  
- * JsonApprovals. [verifyJson ](https://github.com/approvals/ApprovalTests.Java/blob/master/approvaltests/src/main/java/org/approvaltests/JsonApprovals.java#L17-L20) (String)  
+ * JsonApprovals. [verifyAsJson ](https://github.com/approvals/ApprovalTests.Java/blob/master/approvaltests/src/main/java/org/approvaltests/JsonApprovals.java#L26-L29) (Object)  
+ * JsonApprovals. [verifyAsJson ](https://github.com/approvals/ApprovalTests.Java/blob/master/approvaltests/src/main/java/org/approvaltests/JsonApprovals.java#L30-L33) (Object,Function1)  
+ * JsonApprovals. [verifyJson ](https://github.com/approvals/ApprovalTests.Java/blob/master/approvaltests/src/main/java/org/approvaltests/JsonApprovals.java#L18-L21) (String)  
  * JsonJacksonApprovals. [verifyAsJson ](https://github.com/approvals/ApprovalTests.Java/blob/master/approvaltests/src/main/java/org/approvaltests/JsonJacksonApprovals.java#L10-L13) (Object)  
  * VelocityApprovals. [verify ](https://github.com/approvals/ApprovalTests.Java/blob/master/approvaltests/src/main/java/org/approvaltests/velocity/VelocityApprovals.java#L16-L19) (ContextAware)  

approvaltests-tests/src/test/java/org/approvaltests/JsonFormattingTest.java

@@ -7,6 +7,14 @@
 
 public class JsonFormattingTest
 {
+  @Test
+  public void testGsonCircular()
+  {
+    Approvals.verifyException(() -> {
+      JsonApprovals.verifyAsJson(Circular.getIndirectCircularReference());
+    });
+  }
+
   @Test
   public void testBasicFormatting()
   {

approvaltests-tests/src/test/java/org/approvaltests/JsonFormattingTest.testGsonCircular.approved.txt

@@ -0,0 +1,5 @@
+java.lang.RuntimeException: Circular reference found.
+Gson does not handle circular references.
+Consider:
+  1. Using XStream (JsonXstreamApprovals)
+  2. Remove the circular reference.

approvaltests-tests/src/test/java/org/approvaltests/JsonXstreamApprovalTest.java

@@ -2,24 +2,20 @@
 
 import org.junit.jupiter.api.Test;
 
-import java.time.Instant;
-
 public class JsonXstreamApprovalTest
 {
+  @Test
+  public void testXstreamCircular()
+  {
+    Circular middle = Circular.getIndirectCircularReference();
+    JsonXstreamApprovals.verifyAsJson(middle);
+  }
   @Test
   public void testBasicFormatting()
   {
-    Circular c = new Circular();
-    JsonXtreamApprovals.verifyAsJson(c);
+    Circular c = new Circular(null, "Label");
+    c.parent = c;
+    JsonXstreamApprovals.verifyAsJson(c);
   }
 
-  public static class Circular {
-    Circular parent;
-    String label;
-
-    public Circular() {
-      this.parent = this;
-      this.label = "Label";
-    }
-  }
 }

approvaltests-tests/src/test/java/org/approvaltests/JsonXstreamApprovalTest.testBasicFormatting.approved.json

@@ -1,4 +1,4 @@
-{"org.approvaltests.JsonXstreamApprovalTest$Circular": {
+{"org.approvaltests.Circular": {
   "parent": {
     "@reference": ".."
   },

approvaltests-tests/src/test/java/org/approvaltests/JsonXstreamApprovalTest.testXstreamCircular.approved.json

@@ -0,0 +1,9 @@
+{"org.approvaltests.Circular": {
+  "parent": {
+    "parent": {
+      "@reference": "../.."
+    },
+    "label": "child"
+  },
+  "label": "middle"
+}}

approvaltests-util/src/main/java/com/spun/util/JsonUtils.java

@@ -41,10 +41,14 @@ public static <T> String asJsonWithBuilder(Object o, Function1<T, T> gsonBuilder
   }
   public static <T> String asJson(Object o, Function1<GsonBuilder, GsonBuilder> gsonBuilder)
   {
-    GsonBuilder builder = new GsonBuilder().setPrettyPrinting();
-    builder = addHandlingForDateObjects(builder);
-    Gson gson = gsonBuilder.call(builder).create();
-    return gson.toJson(o);
+    try {
+      GsonBuilder builder = new GsonBuilder().setPrettyPrinting();
+      builder = addHandlingForDateObjects(builder);
+      Gson gson = gsonBuilder.call(builder).create();
+      return gson.toJson(o);
+    } catch (StackOverflowError e) {
+      throw new RuntimeException("Circular reference found.\nGson does not handle circular references.\nConsider:\n  1. Using XStream (JsonXstreamApprovals)\n  2. Remove the circular reference.", e);
+    }
   }
   private static GsonBuilder addHandlingForDateObjects(GsonBuilder builder)
   {

approvaltests/src/main/java/org/approvaltests/JsonApprovals.java

@@ -1,6 +1,7 @@
 package org.approvaltests;
 
 import com.google.gson.GsonBuilder;
+import com.spun.util.FormattedException;
 import com.spun.util.JsonUtils;
 import org.approvaltests.core.Options;
 import org.lambda.functions.Function1;
@@ -28,7 +29,7 @@ public static void verifyAsJson(Object o, Function1<GsonBuilder, GsonBuilder> gs
   }
   public static void verifyAsJson(Object o, Function1<GsonBuilder, GsonBuilder> gsonBuilder, Options options)
   {
-    Approvals.verify(JsonUtils.asJson(o, gsonBuilder), options.forFile().withExtension(".json"));
+      Approvals.verify(JsonUtils.asJson(o, gsonBuilder), options.forFile().withExtension(".json"));
   }
   // begin-snippet: verify_as_json
   public static void verifyAsJson(Object o, Options options)

approvaltests/src/main/java/org/approvaltests/JsonXtreamApprovals.java renamed to approvaltests/src/main/java/org/approvaltests/JsonXstreamApprovals.java

@@ -1,16 +1,15 @@
 package org.approvaltests;
 
 import com.thoughtworks.xstream.XStream;
-import com.thoughtworks.xstream.io.json.JettisonMappedXmlDriver;
 import com.thoughtworks.xstream.io.json.JsonHierarchicalStreamDriver;
-import com.thoughtworks.xstream.io.xml.PrettyPrintWriter;
 import org.approvaltests.core.Options;
 
-import java.io.BufferedOutputStream;
-import java.io.BufferedWriter;
-import java.io.StringWriter;
-
-public class JsonXtreamApprovals
+/**
+ * Requires (XStream)[https://mvnrepository.com/artifact/com.thoughtworks.xstream/xstream]
+ * Requires (Jettison)[https://mvnrepository.com/artifact/org.codehaus.jettison/jettison]
+ * Requires (Camel-XStream)[https://mvnrepository.com/artifact/org.apache.camel/camel-xstream]
+ */
+public class JsonXstreamApprovals
 {
   public static void verifyAsJson(Object o)
   {