Merge branch 'main' of https://github.com/VerifyTests/Verify

Author: SimonCropp

docs/converter.md

@@ -206,6 +206,43 @@ return new(
 <!-- endSnippet -->
 
 
+## Excluding targets
+
+Some converters emit the source document (for example a `pdf`, `docx`, or `xlsx`) alongside the info file and the derived targets. That source document is then committed as a `.verified.{extension}` file. Where the document is large, or where its bytes cannot be made deterministic, it can be excluded from the snapshot. The info file and the derived targets continue to verify.
+
+`ExcludeTargets` takes one or more extensions, and drops every matching target:
+
+<!-- snippet: ExcludeTargets -->
+<a id='snippet-ExcludeTargets'></a>
+```cs
+[Fact]
+public Task ExcludeConverterSourceTarget() =>
+    Verify(new MemoryStream("source-document"u8.ToArray()), "excludesource")
+        .ExcludeTargets("excludesource");
+```
+<sup><a href='/src/Verify.Tests/Converters/ExcludeTargetsTests.cs#L67-L74' title='Snippet source file'>snippet source</a> | <a href='#snippet-ExcludeTargets' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+Any existing verified file for an excluded extension is then reported as pending deletion.
+
+To exclude an extension for every test, call `ExcludeTargets` on `VerifierSettings` at initialization:
+
+<!-- snippet: StaticExcludeTargets -->
+<a id='snippet-StaticExcludeTargets'></a>
+```cs
+public static class ModuleInitializer
+{
+    [ModuleInitializer]
+    public static void Init() =>
+        VerifierSettings.ExcludeTargets("pdf");
+}
+```
+<sup><a href='/src/ModuleInitDocs/ExcludeTargets.cs#L3-L12' title='Snippet source file'>snippet source</a> | <a href='#snippet-StaticExcludeTargets' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+Excluding every target of a verification is an error, since a verification requires at least one target.
+
+
 ## Shipping
 
 Converters can be shipped as NuGet packages:

docs/mdsource/converter.source.md

@@ -70,6 +70,23 @@ If cleanup needs to occur after verification a callback can be passes to `Conver
 snippet: ConversionResultWithCleanup
 
 
+## Excluding targets
+
+Some converters emit the source document (for example a `pdf`, `docx`, or `xlsx`) alongside the info file and the derived targets. That source document is then committed as a `.verified.{extension}` file. Where the document is large, or where its bytes cannot be made deterministic, it can be excluded from the snapshot. The info file and the derived targets continue to verify.
+
+`ExcludeTargets` takes one or more extensions, and drops every matching target:
+
+snippet: ExcludeTargets
+
+Any existing verified file for an excluded extension is then reported as pending deletion.
+
+To exclude an extension for every test, call `ExcludeTargets` on `VerifierSettings` at initialization:
+
+snippet: StaticExcludeTargets
+
+Excluding every target of a verification is an error, since a verification requires at least one target.
+
+
 ## Shipping
 
 Converters can be shipped as NuGet packages:

src/ModuleInitDocs/ExcludeTargets.cs

@@ -0,0 +1,13 @@
+public class ExcludeTargets
+{
+    #region StaticExcludeTargets
+
+    public static class ModuleInitializer
+    {
+        [ModuleInitializer]
+        public static void Init() =>
+            VerifierSettings.ExcludeTargets("pdf");
+    }
+
+    #endregion
+}

src/StaticSettingsTests/ExcludeTargetsTests.GlobalExclusionAppliesToAllVerifications.verified.txt

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

src/StaticSettingsTests/ExcludeTargetsTests.cs

@@ -0,0 +1,20 @@
+public class ExcludeTargetsTests :
+    BaseTest
+{
+    [Fact]
+    public async Task GlobalExclusionAppliesToAllVerifications()
+    {
+        VerifierSettings.ExcludeTargets("excludedbin");
+        Target[] targets = [new("excludedbin", new MemoryStream("binary-content"u8.ToArray()))];
+        var result = await Verify(null, targets)
+            .DisableDiff();
+        Assert.Single(result.Files);
+    }
+
+    [Fact]
+    public void AfterVerifyHasBeenRunThrows()
+    {
+        InnerVerifier.verifyHasBeenRun = true;
+        Assert.Throws<Exception>(() => VerifierSettings.ExcludeTargets("excludedbin"));
+    }
+}

src/Verify.Tests/Converters/ExcludeTargetsTests.ExcludeConverterSourceTarget.verified.txt

@@ -0,0 +1 @@
+derived from source

src/Verify.Tests/Converters/ExcludeTargetsTests.ExcludeFileConverterSourceTarget.verified.txt

@@ -0,0 +1 @@
+the info

src/Verify.Tests/Converters/ExcludeTargetsTests.ExcludeStreamTarget.verified.txt

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

src/Verify.Tests/Converters/ExcludeTargetsTests.ExcludedStreamIsDisposed.verified.txt

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

src/Verify.Tests/Converters/ExcludeTargetsTests.ExtensionMatchIsCaseInsensitive.verified.txt

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