BypassComparersForSubsequentOnDifference (#1739)

Author: SimonCropp

docs/comparer.md

@@ -42,6 +42,35 @@ The returned `CompareResult.NotEqual` takes an optional message that will be ren
 **If an input is split into multiple files, and a text file fails, then all subsequent binary comparisons will revert to the default comparison.**
 
 
+### Bypass comparers for derived targets
+
+When a converter splits an input into multiple targets, for example a source document plus derived outputs such as rendered images or extracted text, a lenient comparer on a derived target can mask a real change in the source. Setting `BypassComparersForSubsequentOnDifference` on the source target ensures that, when the source differs from its verified file, all subsequent targets skip their registered comparers and fall back to exact comparison:
+
+<!-- snippet: BypassComparersForSubsequentOnDifference -->
+<a id='snippet-BypassComparersForSubsequentOnDifference'></a>
+```cs
+// A converter that emits a canonical source document alongside derived targets (eg rendered pages).
+// The source is flagged so that, when it differs, the derived targets skip their (potentially lenient)
+// comparers and fall back to exact comparison, ensuring a real change in the source is never masked.
+public static ConversionResult ConvertDocument(Stream document, IReadOnlyDictionary<string, object> context)
+{
+    Target[] targets =
+    [
+        new("docx", document)
+        {
+            BypassComparersForSubsequentOnDifference = true
+        },
+        new("png", RenderPage(document))
+    ];
+    return new(info: null, targets);
+}
+```
+<sup><a href='/src/Verify.Tests/Snippets/BypassComparerSnippets.cs#L5-L23' title='Snippet source file'>snippet source</a> | <a href='#snippet-BypassComparersForSubsequentOnDifference' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+The flag must be set on the source target, and that target must precede the derived targets in the conversion result.
+
+
 ### Instance comparer
 
 <!-- snippet: InstanceComparer -->

docs/mdsource/comparer.source.md

@@ -16,6 +16,15 @@ The returned `CompareResult.NotEqual` takes an optional message that will be ren
 **If an input is split into multiple files, and a text file fails, then all subsequent binary comparisons will revert to the default comparison.**
 
 
+### Bypass comparers for derived targets
+
+When a converter splits an input into multiple targets, for example a source document plus derived outputs such as rendered images or extracted text, a lenient comparer on a derived target can mask a real change in the source. Setting `BypassComparersForSubsequentOnDifference` on the source target ensures that, when the source differs from its verified file, all subsequent targets skip their registered comparers and fall back to exact comparison:
+
+snippet: BypassComparersForSubsequentOnDifference
+
+The flag must be set on the source target, and that target must precede the derived targets in the conversion result.
+
+
 ### Instance comparer
 
 snippet: InstanceComparer

src/Verify.Tests/Comparer/BypassComparerTests.SourceDiffers_DerivedComparerBypassed.verified.bypassderived

@@ -0,0 +1 @@
+derived-other

src/Verify.Tests/Comparer/BypassComparerTests.SourceDiffers_DerivedComparerBypassed.verified.bypasssource

@@ -0,0 +1 @@
+source-other

src/Verify.Tests/Comparer/BypassComparerTests.SourceDiffers_DerivedComparerBypassed.verified.txt

@@ -0,0 +1 @@
+null

src/Verify.Tests/Comparer/BypassComparerTests.SourceEqual_DerivedComparerUsed.verified.bypassderived

@@ -0,0 +1 @@
+derived-other

src/Verify.Tests/Comparer/BypassComparerTests.SourceEqual_DerivedComparerUsed.verified.bypasssource

@@ -0,0 +1 @@
+source-content

src/Verify.Tests/Comparer/BypassComparerTests.SourceEqual_DerivedComparerUsed.verified.txt

@@ -0,0 +1 @@
+null

src/Verify.Tests/Comparer/BypassComparerTests.cs

@@ -0,0 +1,48 @@
+public class BypassComparerTests
+{
+    // Mimics a converter that emits a canonical source target (eg a document) alongside a derived
+    // target (eg a rendered image) whose comparer can mask a real difference in the source.
+    static Target[] BuildTargets() =>
+    [
+        new("bypasssource", new MemoryStream("source-content"u8.ToArray()))
+        {
+            BypassComparersForSubsequentOnDifference = true
+        },
+        new("bypassderived", new MemoryStream("derived-content"u8.ToArray()))
+    ];
+
+    static int derivedCompareCount;
+
+    // A comparer that masks every difference by always reporting equal.
+    static Task<CompareResult> MaskingDerivedComparer(Stream received, Stream verified, IReadOnlyDictionary<string, object> context)
+    {
+        derivedCompareCount++;
+        return Task.FromResult(CompareResult.Equal);
+    }
+
+    [Fact]
+    public async Task SourceEqual_DerivedComparerUsed()
+    {
+        derivedCompareCount = 0;
+        // The source matches its verified file, so no bypass is triggered and the derived comparer
+        // runs and masks the difference in the derived target.
+        await Verify(null, BuildTargets())
+            .UseStreamComparer(MaskingDerivedComparer, "bypassderived")
+            .DisableDiff();
+        Assert.Equal(1, derivedCompareCount);
+    }
+
+    [Fact]
+    public async Task SourceDiffers_DerivedComparerBypassed()
+    {
+        derivedCompareCount = 0;
+        // The source differs from its verified file. Because it is flagged, the derived comparer is
+        // bypassed (never invoked) and the otherwise-masked derived difference is surfaced.
+        var exception = await Assert.ThrowsAsync<VerifyException>(
+            () => Verify(null, BuildTargets())
+                .UseStreamComparer(MaskingDerivedComparer, "bypassderived")
+                .DisableDiff());
+        Assert.Equal(0, derivedCompareCount);
+        Assert.Contains("bypassderived", exception.Message);
+    }
+}

src/Verify.Tests/Snippets/BypassComparerSnippets.cs

@@ -0,0 +1,29 @@
+#if DEBUG
+
+public class BypassComparerSnippets
+{
+    #region BypassComparersForSubsequentOnDifference
+
+    // A converter that emits a canonical source document alongside derived targets (eg rendered pages).
+    // The source is flagged so that, when it differs, the derived targets skip their (potentially lenient)
+    // comparers and fall back to exact comparison, ensuring a real change in the source is never masked.
+    public static ConversionResult ConvertDocument(Stream document, IReadOnlyDictionary<string, object> context)
+    {
+        Target[] targets =
+        [
+            new("docx", document)
+            {
+                BypassComparersForSubsequentOnDifference = true
+            },
+            new("png", RenderPage(document))
+        ];
+        return new(info: null, targets);
+    }
+
+    #endregion
+
+    static Stream RenderPage(Stream document) =>
+        new MemoryStream();
+}
+
+#endif