start laying foundations for dealing with asymmetric C# examples

toptobes · toptobes · commit 28396bab12c7 · 2026-02-19T21:20:59.000-08:00
diff --git a/src/main/java/com/dtsx/docs/core/planner/meta/snapshot/SnapshotSourcesParser.java b/src/main/java/com/dtsx/docs/core/planner/meta/snapshot/SnapshotSourcesParser.java
@@ -66,7 +66,7 @@ public static List<SnapshotSource> parseSources(SnapshotsConfig config) {
             sources.add(parser.apply(source, params));
         }
 
-        return sources.stream().sorted().toList();
+        return sources;
     }
 
     private static <M> BiFunction<String, Map<String, Object>, SnapshotSource> mk(BiFunction<String, M, SnapshotSource> constructor, TypeReference<M> typeRef) {
diff --git a/src/main/java/com/dtsx/docs/core/runner/drivers/ClientDriver.java b/src/main/java/com/dtsx/docs/core/runner/drivers/ClientDriver.java
@@ -7,6 +7,7 @@
 import com.dtsx.docs.core.runner.ExecutionEnvironment.TestFileModifierFlags;
 import com.dtsx.docs.core.runner.RunException;
 import com.dtsx.docs.core.runner.drivers.impls.*;
+import com.dtsx.docs.core.runner.tests.snapshots.verifier.Snapshot;
 import com.dtsx.docs.lib.ExternalPrograms.ExternalProgram;
 import com.dtsx.docs.lib.ExternalPrograms.RunResult;
 import lombok.AllArgsConstructor;
@@ -15,10 +16,7 @@
 
 import java.nio.file.Files;
 import java.nio.file.Path;
-import java.util.ArrayList;
-import java.util.Iterator;
-import java.util.List;
-import java.util.Map;
+import java.util.*;
 import java.util.function.Function;
 
 ///  A pluggable driver for setting up and running clients of different languages.
@@ -110,7 +108,11 @@ public abstract class ClientDriver {
     /// @return the execution result with exit code and output
     public abstract RunResult executeScript(BaseScriptRunnerCtx ctx, ExecutionEnvironment execEnv, Map<String, String> envVars);
 
-    protected void replaceArtifactPlaceholder(ExecutionEnvironment execEnv, String file) {
+    public HashMap<Snapshot, Set<Path>> reduceSnapshots(HashMap<Snapshot, Set<Path>> snapshots) {
+        return snapshots;
+    }
+
+    protected final void replaceArtifactPlaceholder(ExecutionEnvironment execEnv, String file) {
         val path = execEnv.envDir().resolve(file);
 
         try {
@@ -122,7 +124,7 @@ protected void replaceArtifactPlaceholder(ExecutionEnvironment execEnv, String f
         }
     }
 
-    protected String artifact() {
+    protected final String artifact() {
         if (artifact == null) {
             throw new RunException("Attempted to access artifact for driver that does not use one: " + language() + ". Did *someone* forget to set a default artifact in ClientLanguage?");
         }
diff --git a/src/main/java/com/dtsx/docs/core/runner/tests/results/TestOutcome.java b/src/main/java/com/dtsx/docs/core/runner/tests/results/TestOutcome.java
@@ -1,5 +1,6 @@
 package com.dtsx.docs.core.runner.tests.results;
 
+import com.dtsx.docs.core.runner.tests.snapshots.verifier.Snapshot;
 import com.dtsx.docs.lib.CliLogger;
 import com.dtsx.docs.core.planner.TestRoot;
 import com.dtsx.docs.core.runner.drivers.ClientLanguage;
@@ -32,24 +33,24 @@ enum DryPassed implements TestOutcome {
     enum Mismatch implements TestOutcome {
         INSTANCE;
 
-        public Mismatch alsoLog(TestRoot testRoot, ClientLanguage language, Map<String, Set<Path>> differingSnapshots) {
+        public Mismatch alsoLog(TestRoot testRoot, ClientLanguage language, Map<Snapshot, Set<Path>> differingSnapshots) {
             val extra = new StringBuilder("Differing snapshots found for the following files:\n");
 
-            for (val entry : differingSnapshots.entrySet()) {
-                extra.append("Snapshot:\n").append(entry.getKey()).append("\nFiles:\n");
+            differingSnapshots.forEach((snapshot, paths) -> {
+                extra.append("Snapshot:\n").append(snapshot).append("\nFiles:\n");
 
-                for (val path : entry.getValue()) {
+                for (val path : paths) {
                     extra.append(" - ").append(path).append("\n");
                 }
-            }
+            });
 
             logResult(testRoot, language, this, extra.toString());
             return this;
         }
     }
 
     record FailedToVerify(Optional<Path> expected) implements TestOutcome {
-        public FailedToVerify alsoLog(TestRoot testRoot, ClientLanguage language, String actualSnapshot) {
+        public FailedToVerify alsoLog(TestRoot testRoot, ClientLanguage language, Snapshot actualSnapshot) {
             val prefix = expected
                 .map((path) -> "Expected snapshot file: " + path)
                 .orElse("No approved snapshot file found.");
diff --git a/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/sources/SnapshotSource.java b/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/sources/SnapshotSource.java
@@ -5,30 +5,25 @@
 import com.dtsx.docs.core.planner.fixtures.FixtureMetadata;
 import com.dtsx.docs.core.runner.PlaceholderVars;
 import com.dtsx.docs.core.runner.drivers.ClientDriver;
+import com.dtsx.docs.core.runner.tests.snapshots.verifier.Snapshot.SnapshotPart;
 import com.dtsx.docs.core.runner.tests.snapshots.sources.output.OutputCaptureSource;
 import com.dtsx.docs.core.runner.tests.snapshots.sources.records.RecordSource;
-import com.dtsx.docs.core.runner.tests.snapshots.verifier.SnapshotVerifier;
 import com.dtsx.docs.lib.ExternalPrograms.RunResult;
-import lombok.Getter;
+import lombok.EqualsAndHashCode;
 import lombok.RequiredArgsConstructor;
 
 import java.util.Optional;
 import java.util.function.Supplier;
 
-/// Represents a pluggable source of snapshots based on the run output, or the database state.
-///
-/// @see RecordSource
-/// @see OutputCaptureSource
 @RequiredArgsConstructor
 public abstract class SnapshotSource implements Comparable<SnapshotSource> {
-    @Getter
     protected final String name;
 
-    /// Returns just a string containing the snapshot for this source.
-    /// Any header/footer or delimiting information is added by the caller.
-    ///
-    /// @see SnapshotVerifier
-    public abstract String mkSnapshot(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md);
+    public SnapshotPart mkSnapshot(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {
+        return new SnapshotPart(name, mkSnapshotImpl(ctx, driver, res, md));
+    }
+
+    protected abstract String mkSnapshotImpl(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md);
 
     @Override
     public int compareTo(SnapshotSource other) {
diff --git a/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/sources/output/OutputCaptureSource.java b/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/sources/output/OutputCaptureSource.java
@@ -13,7 +13,7 @@ public OutputCaptureSource(String name, Void ignored) {
     }
 
     @Override
-    public String mkSnapshot(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {
+    public String mkSnapshotImpl(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {
         return SnapshotSourceUtils.extractOutput(name, res);
     }
 }
diff --git a/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/sources/output/OutputJsonifySource.java b/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/sources/output/OutputJsonifySource.java
@@ -24,7 +24,7 @@ public OutputJsonifySource(String name, OutputJsonifySourceMeta meta) {
     }
 
     @Override
-    public String mkSnapshot(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {
+    public String mkSnapshotImpl(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {
         val output = SnapshotSourceUtils.extractOutput(name, res);
         val rawJsonLines = driver.preprocessToJson(ctx, meta, output);
 
diff --git a/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/sources/output/OutputMatchesSource.java b/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/sources/output/OutputMatchesSource.java
@@ -20,7 +20,7 @@ public OutputMatchesSource(String name, OutputMatchesSourceMeta meta) {
     }
 
     @Override
-    public String mkSnapshot(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {
+    public String mkSnapshotImpl(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {
         val output = SnapshotSourceUtils.extractOutput(name, res);
 
         if (regex.matcher(output).matches()) {
diff --git a/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/sources/records/RecordSource.java b/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/sources/records/RecordSource.java
@@ -106,7 +106,7 @@ private Projection[] buildProjection(Map<String, Object> projectionMap) {
     protected abstract Stream<Map<String, Object>> streamRecords(TestCtx ctx, String name, String keyspace);
 
     @Override
-    public String mkSnapshot(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {
+    public String mkSnapshotImpl(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {
         val schemaObjName = resolveName("schema object name", md, driver, overrideName, () -> extractSchemaObjectName(md));
         val schemaObjKeyspace = resolveName("keyspace", md, driver, overrideKeyspace, () -> Optional.of(md.keyspaceName()));
 
diff --git a/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/sources/schema/definitions/SchemaObjectDefinitionSource.java b/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/sources/schema/definitions/SchemaObjectDefinitionSource.java
@@ -28,7 +28,7 @@ public SchemaObjectDefinitionSource(String name, WithNameAndKeyspace nameAndKeys
     protected abstract Object getDefinition(TestCtx ctx, String name, String keyspace);
 
     @Override
-    public String mkSnapshot(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {
+    public String mkSnapshotImpl(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {
         val schemaObjName = resolveName("schema object name", md, driver, overrideName, () -> extractSchemaObjectName(md));
         val schemaObjKeyspace = resolveName("keyspace", md, driver, overrideKeyspace, () -> Optional.of(md.keyspaceName()));
 
diff --git a/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/sources/schema/definitions/TableIndexDefinitionsSource.java b/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/sources/schema/definitions/TableIndexDefinitionsSource.java
@@ -33,7 +33,7 @@ public TableIndexDefinitionsSource(String name, TableIndexDefinitionSourceMeta m
     }
 
     @Override
-    public String mkSnapshot(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {
+    public String mkSnapshotImpl(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {
         val tableName = resolveName("table name", md, driver, overrideName, md::tableName);
 
         val table = DataAPIUtils.getTable(
diff --git a/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/sources/schema/definitions/UdtDefinitionsSource.java b/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/sources/schema/definitions/UdtDefinitionsSource.java
@@ -33,7 +33,7 @@ public UdtDefinitionsSource(String name, UdtDefinitionSourceMeta meta) {
     record TypeDescriptor(String udtName, Object definition) {}
 
     @Override
-    public String mkSnapshot(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {
+    public String mkSnapshotImpl(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {
         val database = DataAPIUtils.getDatabase(
             ctx.connectionInfo(),
             overrideKeyspace.orElse(md.keyspaceName())
diff --git a/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/sources/schema/names/NamesSource.java b/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/sources/schema/names/NamesSource.java
@@ -26,7 +26,7 @@ public NamesSource(String name, WithKeyspace keyspace) {
     public abstract List<String> names(Database db, ClientDriver driver, FixtureMetadata md);
 
     @Override
-    public String mkSnapshot(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {
+    public String mkSnapshotImpl(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {
         val db = DataAPIUtils.getDatabase(
             ctx.connectionInfo(),
             this.keyspace.orElse(md.keyspaceName())
diff --git a/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/verifier/Snapshot.java b/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/verifier/Snapshot.java
@@ -0,0 +1,43 @@
+package com.dtsx.docs.core.runner.tests.snapshots.verifier;
+
+import lombok.AccessLevel;
+import lombok.EqualsAndHashCode;
+import lombok.RequiredArgsConstructor;
+import lombok.val;
+import org.approvaltests.core.Scrubber;
+
+import java.util.List;
+
+@EqualsAndHashCode
+@RequiredArgsConstructor(access = AccessLevel.PRIVATE)
+public class Snapshot {
+    private final List<SnapshotPart> parts;
+
+    public static Snapshot fromParts(Scrubber scrubber, List<SnapshotPart> parts) {
+        return new Snapshot(
+            parts.stream()
+                .map(p -> new SnapshotPart(p.name, scrubber.scrub(p.content)))
+                .sorted()
+                .toList()
+        );
+    }
+
+    public record SnapshotPart(String name, String content) implements Comparable<SnapshotPart> {
+        @Override
+        public int compareTo(SnapshotPart other) {
+            return this.name.compareTo(other.name); // ensures snapshot part ordering is always deterministic
+        }
+    }
+
+    @Override
+    public String toString() {
+        val sb = new StringBuilder();
+
+        for (val part : parts) {
+            sb.append("---").append(part.name).append("---\n");
+            sb.append(part.content).append("\n");
+        }
+
+        return sb.substring(0, sb.length() - 1);
+    }
+}
diff --git a/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/verifier/SnapshotVerifier.java b/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/verifier/SnapshotVerifier.java
@@ -9,6 +9,7 @@
 import com.dtsx.docs.core.runner.tests.results.TestOutcome;
 import com.dtsx.docs.core.runner.tests.results.TestOutcome.FailedToVerify;
 import com.dtsx.docs.core.runner.tests.snapshots.sources.SnapshotSource;
+import com.dtsx.docs.core.runner.tests.snapshots.verifier.scrubbers.ObjectIdScrubber;
 import com.dtsx.docs.core.runner.tests.strategies.execution.ExecutionStrategy.TestResetter;
 import com.dtsx.docs.lib.CliLogger;
 import com.dtsx.docs.lib.ExternalPrograms.RunResult;
@@ -20,15 +21,13 @@
 import org.approvaltests.core.Scrubber;
 import org.approvaltests.scrubbers.GuidScrubber;
 import org.approvaltests.scrubbers.MultiScrubber;
-import org.approvaltests.scrubbers.RegExScrubber;
 
 import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.time.Instant;
 import java.util.*;
 import java.util.function.Function;
-import java.util.regex.Pattern;
 
 import static com.dtsx.docs.core.runner.tests.VerifyMode.DRY_RUN;
 import static com.dtsx.docs.core.runner.tests.VerifyMode.NORMAL;
@@ -53,7 +52,7 @@ public TestOutcome verify(ClientDriver driver, TestRoot testRoot, FixtureMetadat
             return TestOutcome.DryPassed.INSTANCE;
         }
 
-        val snapshots = new HashMap<String, Set<Path>>();
+        var snapshots = new HashMap<Snapshot, Set<Path>>();
 
         for (val filePath : filesForLang) {
             for (var i = 0; true; i++) {
@@ -77,6 +76,8 @@ public TestOutcome verify(ClientDriver driver, TestRoot testRoot, FixtureMetadat
             }
         }
 
+        snapshots = driver.reduceSnapshots(snapshots);
+
         if (snapshots.size() > 1) {
             return TestOutcome.Mismatch.Mismatch.Mismatch.Mismatch.Mismatch.Mismatch.Mismatch.Mismatch.INSTANCE.alsoLog(testRoot, driver.language(), snapshots);
         }
@@ -85,21 +86,16 @@ public TestOutcome verify(ClientDriver driver, TestRoot testRoot, FixtureMetadat
         return verifySnapshot(driver, testRoot, snapshot);
     }
 
-    private String mkSnapshot(ClientDriver driver, FixtureMetadata md, RunResult result) {
-        val sb = new StringBuilder();
-
-        for (val source : snapshotSources) {
-            val snapshot = source.mkSnapshot(ctx, driver, result, md);
-            sb.append("---").append(source.name().toLowerCase()).append("---\n");
-            sb.append(snapshot).append("\n");
-        }
+    private Snapshot mkSnapshot(ClientDriver driver, FixtureMetadata md, RunResult result) {
+        val parts = snapshotSources.stream()
+            .map(s -> s.mkSnapshot(ctx, driver, result, md))
+            .toList();
 
-        val snapshot = sb.deleteCharAt(sb.length() - 1).toString().trim();
-        return SCRUBBER.scrub(snapshot);
+        return Snapshot.fromParts(SCRUBBER, parts);
     }
 
     // TODO maybe cache approved test file contents' hashes + client artifacts so we don't re-verify unchanged tests?
-    private TestOutcome verifySnapshot(ClientDriver driver, TestRoot testRoot, String snapshot) {
+    private TestOutcome verifySnapshot(ClientDriver driver, TestRoot testRoot, Snapshot snapshot) {
         val namer = mkNamer(driver.language(), testRoot);
         val options = mkApprovalOptions(namer);
 
@@ -139,12 +135,4 @@ private static void updateLastModified(Path snapshotsFolder) {
             CliLogger.exception("Failed to update " + LAST_MODIFIED_FILE + " in snapshots folder '" + snapshotsFolder + "'", e);
         }
     }
-
-    public static class ObjectIdScrubber extends RegExScrubber {
-        public static final Pattern OBJECT_ID_PATTERN = Pattern.compile("[a-fA-F0-9]{24}");
-
-        public ObjectIdScrubber() {
-            super(OBJECT_ID_PATTERN, n -> "objectId_" + n);
-        }
-    }
 }
diff --git a/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/verifier/scrubbers/ObjectIdScrubber.java b/src/main/java/com/dtsx/docs/core/runner/tests/snapshots/verifier/scrubbers/ObjectIdScrubber.java
@@ -0,0 +1,13 @@
+package com.dtsx.docs.core.runner.tests.snapshots.verifier.scrubbers;
+
+import org.approvaltests.scrubbers.RegExScrubber;
+
+import java.util.regex.Pattern;
+
+public class ObjectIdScrubber extends RegExScrubber {
+    public static final Pattern OBJECT_ID_PATTERN = Pattern.compile("[a-fA-F0-9]{24}");
+
+    public ObjectIdScrubber() {
+        super(OBJECT_ID_PATTERN, n -> "objectId_" + n);
+    }
+}

Original file line number	Diff line number	Diff line change
`@@ -66,7 +66,7 @@ public static List<SnapshotSource> parseSources(SnapshotsConfig config) {`
`66`	`66`	`sources.add(parser.apply(source, params));`
`67`	`67`	`}`
`68`	`68`
`69`		`- return sources.stream().sorted().toList();`
	`69`	`+ return sources;`
`70`	`70`	`}`
`71`	`71`
`72`	`72`	`private static <M> BiFunction<String, Map<String, Object>, SnapshotSource> mk(BiFunction<String, M, SnapshotSource> constructor, TypeReference<M> typeRef) {`
Original file line number	Diff line number	Diff line change
`@@ -13,7 +13,7 @@ public OutputCaptureSource(String name, Void ignored) {`
`13`	`13`	`}`
`14`	`14`
`15`	`15`	`@Override`
`16`		`- public String mkSnapshot(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {`
	`16`	`+ public String mkSnapshotImpl(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {`
`17`	`17`	`return SnapshotSourceUtils.extractOutput(name, res);`
`18`	`18`	`}`
`19`	`19`	`}`
Original file line number	Diff line number	Diff line change
`@@ -24,7 +24,7 @@ public OutputJsonifySource(String name, OutputJsonifySourceMeta meta) {`
`24`	`24`	`}`
`25`	`25`
`26`	`26`	`@Override`
`27`		`- public String mkSnapshot(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {`
	`27`	`+ public String mkSnapshotImpl(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {`
`28`	`28`	`val output = SnapshotSourceUtils.extractOutput(name, res);`
`29`	`29`	`val rawJsonLines = driver.preprocessToJson(ctx, meta, output);`
`30`	`30`
Original file line number	Diff line number	Diff line change
`@@ -20,7 +20,7 @@ public OutputMatchesSource(String name, OutputMatchesSourceMeta meta) {`
`20`	`20`	`}`
`21`	`21`
`22`	`22`	`@Override`
`23`		`- public String mkSnapshot(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {`
	`23`	`+ public String mkSnapshotImpl(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {`
`24`	`24`	`val output = SnapshotSourceUtils.extractOutput(name, res);`
`25`	`25`
`26`	`26`	`if (regex.matcher(output).matches()) {`
Original file line number	Diff line number	Diff line change
`@@ -33,7 +33,7 @@ public TableIndexDefinitionsSource(String name, TableIndexDefinitionSourceMeta m`
`33`	`33`	`}`
`34`	`34`
`35`	`35`	`@Override`
`36`		`- public String mkSnapshot(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {`
	`36`	`+ public String mkSnapshotImpl(TestCtx ctx, ClientDriver driver, RunResult res, FixtureMetadata md) {`
`37`	`37`	`val tableName = resolveName("table name", md, driver, overrideName, md::tableName);`
`38`	`38`
`39`	`39`	`val table = DataAPIUtils.getTable(`