Home

Awesome

<!-- GENERATED FILE - DO NOT EDIT This file was generated by [MarkdownSnippets](https://github.com/SimonCropp/MarkdownSnippets). Source File: /readme.source.md To change this file edit the source file and then run MarkdownSnippets. -->

<img src='/src/icon.png' height='30px'> Verify

Discussions Build status NuGet Status NuGet Status NuGet Status NuGet Status NuGet Status NuGet Status NuGet Status NuGet Status

Verify is a snapshot tool that simplifies the assertion of complex data models and documents.

Verify is called on the test result during the assertion phase. It serializes that result and stores it in a file that matches the test name. On the next test execution, the result is again serialized and compared to the existing file. The test will fail if the two snapshots do not match: either the change is unexpected, or the reference snapshot needs to be updated to the new result.

See Milestones for release notes.

Requirements

Getting started wizard

Get customized instructions for the specific combination of Operating System, IDE, Test Framework, and Build Server.

Start wizard.

NuGet packages

Snapshot management

Accepting or declining a snapshot file is part of the core workflow of Verify. There are several ways to do this and the approach(s) selected is a personal preference.

Usage

ImplicitUsings

All examples use Implicit Usings. Ensure <ImplicitUsings> is set to enable to ensure examples compile correctly.<!-- include: implicit-usings. path: /docs/mdsource/implicit-usings.include.md -->

<ImplicitUsings>enable</ImplicitUsings>

If ImplicitUsings are not enabled, substitute usages of Verify() with Verifier.Verify().<!-- endInclude -->

Class being tested

Given a class to be tested:

<!-- snippet: ClassBeingTested -->

<a id='snippet-ClassBeingTested'></a>

public static class ClassBeingTested
{
    public static Person FindPerson() =>
        new()
        {
            Id = new("ebced679-45d3-4653-8791-3d969c4a986c"),
            Title = Title.Mr,
            GivenNames = "John",
            FamilyName = "Smith",
            Spouse = "Jill",
            Children =
            [
                "Sam",
                "Mary"
            ],
            Address = new()
            {
                Street = "4 Puddle Lane",
                Country = "USA"
            }
        };
}

<sup><a href='/src/TargetLibrary/ClassBeingTested.cs#L1-L26' title='Snippet source file'>snippet source</a> | <a href='#snippet-ClassBeingTested' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

NUnit

Support for NUnit

<!-- snippet: SampleTestNUnit -->

<a id='snippet-SampleTestNUnit'></a>

[TestFixture]
public class Sample
{
    [Test]
    public Task Test()
    {
        var person = ClassBeingTested.FindPerson();
        return Verify(person);
    }
}

<sup><a href='/src/Verify.NUnit.Tests/Snippets/Sample.cs#L1-L14' title='Snippet source file'>snippet source</a> | <a href='#snippet-SampleTestNUnit' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

xUnit

Support for xUnit

<!-- snippet: SampleTestXunit -->

<a id='snippet-SampleTestXunit'></a>

public class Sample
{
    [Fact]
    public Task Test()
    {
        var person = ClassBeingTested.FindPerson();
        return Verify(person);
    }
}

<sup><a href='/src/Verify.Xunit.Tests/Snippets/Sample.cs#L1-L13' title='Snippet source file'>snippet source</a> | <a href='#snippet-SampleTestXunit' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

xUnitV3

Support for xUnitV3

<!-- snippet: SampleTestXunitV3 -->

<a id='snippet-SampleTestXunitV3'></a>

public class Sample
{
    [Fact]
    public Task Test()
    {
        var person = ClassBeingTested.FindPerson();
        return Verify(person);
    }
}

<sup><a href='/src/Verify.XunitV3.Tests/Snippets/Sample.cs#L1-L13' title='Snippet source file'>snippet source</a> | <a href='#snippet-SampleTestXunitV3' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

Fixie

Support for Fixie

<!-- snippet: SampleTestFixie -->

<a id='snippet-SampleTestFixie'></a>

public class Sample
{
    public Task Test()
    {
        var person = ClassBeingTested.FindPerson();
        return Verify(person);
    }
}

<sup><a href='/src/Verify.Fixie.Tests/Snippets/Sample.cs#L1-L12' title='Snippet source file'>snippet source</a> | <a href='#snippet-SampleTestFixie' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

Fixie is less opinionated than other test frameworks. As such it leaves up to the consumer how to configure test execution.<!-- include: fixie-convention. path: /docs/mdsource/fixie-convention.include.md -->

To enable Verify the ITestProject and IExecution interfaces need to be used.

Requirements:

An example implementation of the above:

<!-- snippet: TestProject.cs -->

<a id='snippet-TestProject.cs'></a>

public class TestProject :
    ITestProject,
    IExecution
{
    public void Configure(TestConfiguration configuration, TestEnvironment environment)
    {
        VerifierSettings.AssignTargetAssembly(environment.Assembly);
        configuration.Conventions.Add<DefaultDiscovery, TestProject>();
    }

    public async Task Run(TestSuite testSuite)
    {
        foreach (var testClass in testSuite.TestClasses)
        {
            foreach (var test in testClass.Tests)
            {
                if (test.HasParameters)
                {
                    foreach (var parameters in test
                                 .GetAll<TestCase>()
                                 .Select(_ => _.Parameters))
                    {
                        using (ExecutionState.Set(testClass, test, parameters))
                        {
                            await test.Run(parameters);
                        }
                    }
                }
                else
                {
                    using (ExecutionState.Set(testClass, test, null))
                    {
                        await test.Run();
                    }
                }
            }
        }
    }
}

<sup><a href='/src/Verify.Fixie.Tests/FixieSetup/TestProject.cs#L1-L39' title='Snippet source file'>snippet source</a> | <a href='#snippet-TestProject.cs' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet --> <!-- endInclude -->

Expecto

Support for Expecto

<!-- snippet: SampleTestExpecto -->

<a id='snippet-SampleTestExpecto'></a>

open Expecto
open VerifyTests
open VerifyExpecto

[<Tests>]
let tests =
    testTask "findPerson" {
        let person = ClassBeingTested.FindPerson()
        do! Verifier.Verify("findPerson", person).ToTask()
    }

<sup><a href='/src/Verify.Expecto.FSharpTests/Tests.fs#L2-L13' title='Snippet source file'>snippet source</a> | <a href='#snippet-SampleTestExpecto' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

Caveats

Due to the nature of the Expecto implementation, the following APIs in Verify are not supported.

TUnit

Support for TUnit

<!-- snippet: SampleTestTUnit -->

<a id='snippet-SampleTestTUnit'></a>

public class Sample
{
    [Test]
    public Task Test()
    {
        var person = ClassBeingTested.FindPerson();
        return Verify(person);
    }
}

<sup><a href='/src/Verify.TUnit.Tests/Snippets/Sample.cs#L1-L13' title='Snippet source file'>snippet source</a> | <a href='#snippet-SampleTestTUnit' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

MSTest

Support for MSTest

<!-- snippet: SampleTestMSTest -->

<a id='snippet-SampleTestMSTest'></a>

[TestClass]
public partial class Sample
{
    [TestMethod]
    public Task Test()
    {
        var person = ClassBeingTested.FindPerson();
        return Verify(person);
    }
}

<sup><a href='/src/Verify.MSTest.Tests/Snippets/Sample.cs#L1-L14' title='Snippet source file'>snippet source</a> | <a href='#snippet-SampleTestMSTest' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

Marking tests as 'Using Verify'

The MSTest implementation leverages a Source Generator and requires test classes to opt in to being processed by the Source Generator.<!-- include: mstest-marker. path: /docs/mdsource/mstest-marker.include.md -->

Add the UsesVerifyAttribute.

For all test classes in an assembly:

[assembly: UsesVerify]

For a specific a test class:

[UsesVerify]

Or inherit from VerifyBase:

<!-- snippet: VerifyBaseUsage.cs -->

<a id='snippet-VerifyBaseUsage.cs'></a>

[TestClass]
public class VerifyBaseUsage :
    VerifyBase
{
    [TestMethod]
    public Task Simple() =>
        Verify("The content");
}

<sup><a href='/src/Verify.MSTest.Tests/VerifyBaseUsage.cs#L1-L8' title='Snippet source file'>snippet source</a> | <a href='#snippet-VerifyBaseUsage.cs' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet --> <!-- endInclude -->

Initial Verification

No existing .verified. file.

graph TD
run(Run test and<br/>create Received file)
failTest(Fail Test<br/>and show Diff)
closeDiff(Close Diff)
run-->failTest
shouldAccept{Accept ?}
failTest-->shouldAccept
accept(Move Received<br/>to Verified)
shouldAccept-- Yes -->accept
discard(Discard<br/>Received)
shouldAccept-- No -->discard
accept-->closeDiff
discard-->closeDiff

When the test is initially run will fail. If a Diff Tool is detected it will display the diff.

InitialDiff

To verify the result:

Verified result

This will result in the Sample.Test.verified.txt being created:

<!-- snippet: Verify.Xunit.Tests/Snippets/Sample.Test.verified.txt -->

<a id='snippet-Verify.Xunit.Tests/Snippets/Sample.Test.verified.txt'></a>

{
  GivenNames: John,
  FamilyName: Smith,
  Spouse: Jill,
  Address: {
    Street: 4 Puddle Lane,
    Country: USA
  },
  Children: [
    Sam,
    Mary
  ],
  Id: Guid_1
}

<sup><a href='/src/Verify.Xunit.Tests/Snippets/Sample.Test.verified.txt#L1-L14' title='Snippet source file'>snippet source</a> | <a href='#snippet-Verify.Xunit.Tests/Snippets/Sample.Test.verified.txt' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

Subsequent Verification

Existing .verified. file.

graph TD
run(Run test and<br/>create Received file)
closeDiff(Close Diff)
failTest(Fail Test<br/>and show Diff)
run-->isSame
shouldAccept{Accept ?}
failTest-->shouldAccept
accept(Move Received<br/>to Verified)
shouldAccept-- Yes -->accept
discard(Discard<br/>Received)
shouldAccept-- No -->discard

isSame{Compare<br/>Verified +<br/>Received}
passTest(Pass Test and<br/>discard Received)
isSame-- Same --> passTest
isSame-- Different --> failTest
accept-->closeDiff
discard-->closeDiff

If the implementation of ClassBeingTested changes:

<!-- snippet: ClassBeingTestedChanged -->

<a id='snippet-ClassBeingTestedChanged'></a>

public static class ClassBeingTested
{
    public static Person FindPerson() =>
        new()
        {
            Id = new("ebced679-45d3-4653-8791-3d969c4a986c"),
            Title = Title.Mr,
            // Middle name added
            GivenNames = "John James",
            FamilyName = "Smith",
            Spouse = "Jill",
            Children =
            [
                "Sam",
                "Mary"
            ],
            Address = new()
            {
                // Address changed
                Street = "64 Barnett Street",
                Country = "USA"
            }
        };
}

<sup><a href='/src/TargetLibrary/ClassBeingTestedChanged.cs#L3-L30' title='Snippet source file'>snippet source</a> | <a href='#snippet-ClassBeingTestedChanged' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

And the test is re run it will fail.

The Diff Tool will display the diff:

SecondDiff

The same approach can be used to verify the results and the change to Sample.Test.verified.txt is committed to source control along with the change to ClassBeingTested.

Async

Verify() has overloads that accept Task<T>, ValueTask<T>, and IAsyncEnumerable<T>. These are awaited before verification.

There is also an overload that accepts Func<Task<T>>, which works well with async lambda expressions:

<!-- snippet: VerifyFuncOfTaskOfT -->

<a id='snippet-VerifyFuncOfTaskOfT'></a>

await Verify(
    async () => new
    {
        Foo = await repo.GetFoo(id),
        Bars = await repo.GetBars(id)
    });

<sup><a href='/src/Verify.Tests/Snippets/Snippets.cs#L157-L166' title='Snippet source file'>snippet source</a> | <a href='#snippet-VerifyFuncOfTaskOfT' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

VerifyJson

VerifyJson performs the following actions

<!-- snippet: VerifyJson -->

<a id='snippet-VerifyJson'></a>

[Fact]
public Task VerifyJsonString()
{
    var json = "{'key': {'msg': 'No action taken'}}";
    return VerifyJson(json);
}

[Fact]
public Task VerifyJsonStream()
{
    var json = "{'key': {'msg': 'No action taken'}}";
    var stream = new MemoryStream(Encoding.UTF8.GetBytes(json));
    return VerifyJson(stream);
}

[Fact]
public Task VerifyJsonJToken()
{
    var json = "{'key': {'msg': 'No action taken'}}";
    var target = JToken.Parse(json);
    return Verify(target);
}

<sup><a href='/src/Verify.Tests/JsonTests.cs#L183-L208' title='Snippet source file'>snippet source</a> | <a href='#snippet-VerifyJson' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

Results in a .txt file:

<!-- snippet: JsonTests.VerifyJsonString.verified.txt -->

<a id='snippet-JsonTests.VerifyJsonString.verified.txt'></a>

{
  key: {
    msg: No action taken
  }
}

<sup><a href='/src/Verify.Tests/JsonTests.VerifyJsonString.verified.txt#L1-L5' title='Snippet source file'>snippet source</a> | <a href='#snippet-JsonTests.VerifyJsonString.verified.txt' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

Conventions

Source control Includes/Excludes

eg. add the following to .gitignore

*.received.*

If using UseSplitModeForUniqueDirectory also include:

*.received/

All *.verified.* files should be committed to source control.<!-- endInclude -->

Text file settings

Text variants of verified and received have the following characteristics:<!-- include: text-file-settings. path: /docs/mdsource/text-file-settings.include.md -->

This manifests in several ways:

Source control settings

All text extensions of *.verified.* should have:

eg add the following to .gitattributes

*.verified.txt text eol=lf working-tree-encoding=UTF-8
*.verified.xml text eol=lf working-tree-encoding=UTF-8
*.verified.json text eol=lf working-tree-encoding=UTF-8

EditorConfig settings

If modifying text verified/received files in an editor, it is desirable for the editor to respect the above conventions. For EditorConfig enabled the following can be used:

# Verify settings
[*.{received,verified}.{json,txt,xml}]
charset = "utf-8-bom"
end_of_line = lf
indent_size = unset
indent_style = unset
insert_final_newline = false
tab_width = unset
trim_trailing_whitespace = false

Note that the above are suggested for subset of text extension. Add others as required based on the text file types being verified.<!-- endInclude -->

Conventions check

The above conventions can be checked by calling VerifyChecks.Run() in a test

MSTest

<!-- snippet: VerifyChecksMSTest -->

<a id='snippet-VerifyChecksMSTest'></a>

[TestClass]
public partial class VerifyChecksTests
{
    [TestMethod]
    public Task Run() =>
        VerifyChecks.Run();
}

<sup><a href='/src/Verify.MSTest.Tests/VerifyChecksTests.cs#L2-L10' title='Snippet source file'>snippet source</a> | <a href='#snippet-VerifyChecksMSTest' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

Expecto

<!-- snippet: VerifyChecksExpecto -->

<a id='snippet-VerifyChecksExpecto'></a>

public class VerifyChecksTests
{
    [Tests]
    public static Test verifyChecksTest = Runner.TestCase(
        nameof(verifyChecksTest),
        () => VerifyChecks.Run(typeof(VerifyChecksTests).Assembly));
}

<sup><a href='/src/Verify.Expecto.Tests/VerifyChecksTests.cs#L1-L9' title='Snippet source file'>snippet source</a> | <a href='#snippet-VerifyChecksExpecto' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

Fixie

<!-- snippet: VerifyChecksFixie -->

<a id='snippet-VerifyChecksFixie'></a>

public class VerifyChecksTests
{
    public Task Run() =>
        VerifyChecks.Run(GetType().Assembly);
}

<sup><a href='/src/Verify.Fixie.Tests/VerifyChecksTests.cs#L2-L8' title='Snippet source file'>snippet source</a> | <a href='#snippet-VerifyChecksFixie' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

Xunit

<!-- snippet: VerifyChecksXunit -->

<a id='snippet-VerifyChecksXunit'></a>

public class VerifyChecksTests
{
    [Fact]
    public Task Run() =>
        VerifyChecks.Run();
}

<sup><a href='/src/Verify.Xunit.Tests/VerifyChecksTests.cs#L2-L9' title='Snippet source file'>snippet source</a> | <a href='#snippet-VerifyChecksXunit' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

XunitV3

<!-- snippet: VerifyChecksXunitV3 -->

<a id='snippet-VerifyChecksXunitV3'></a>

public class VerifyChecksTests
{
    [Fact]
    public Task Run() =>
        VerifyChecks.Run();
}

<sup><a href='/src/Verify.XunitV3.Tests/VerifyChecksTests.cs#L2-L9' title='Snippet source file'>snippet source</a> | <a href='#snippet-VerifyChecksXunitV3' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

NUnit

<!-- snippet: VerifyChecksNUnit -->

<a id='snippet-VerifyChecksNUnit'></a>

[TestFixture]
public class VerifyChecksTests
{
    [Test]
    public Task Run() =>
        VerifyChecks.Run();
}

<sup><a href='/src/Verify.NUnit.Tests/VerifyChecksTests.cs#L2-L10' title='Snippet source file'>snippet source</a> | <a href='#snippet-VerifyChecksNUnit' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

TUnit

<!-- snippet: VerifyChecksTUnit -->

<a id='snippet-VerifyChecksTUnit'></a>

public class VerifyChecksTests
{
    [Test]
    public Task Run() =>
        VerifyChecks.Run();
}

<sup><a href='/src/Verify.TUnit.Tests/VerifyChecksTests.cs#L2-L9' title='Snippet source file'>snippet source</a> | <a href='#snippet-VerifyChecksTUnit' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

Static settings

Most settings are available at the both global level and at the instance level.

When modifying settings at the both global level it should be done using a Module Initializer:

<!-- snippet: StaticSettings.cs -->

<a id='snippet-StaticSettings.cs'></a>

public class StaticSettings
{
    [Fact]
    public Task Test() =>
        Verify("String to verify");
}

public static class StaticSettingsUsage
{
    [ModuleInitializer]
    public static void Initialize() =>
        VerifierSettings.AddScrubber(_ => _.Replace("String to verify", "new value"));
}

<sup><a href='/src/Verify.Tests/StaticSettings.cs#L1-L13' title='Snippet source file'>snippet source</a> | <a href='#snippet-StaticSettings.cs' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

VerifyResult

In some scenarios it can be helpful to get access to the resulting *.verified.* files after a successful run. For example to do an explicit check for contains or not-contains in the resulting text. To allow this all Verify methods return a VerifyResult.

<!-- snippet: VerifyResult -->

<a id='snippet-VerifyResult'></a>

var result = await Verify(
    new
    {
        Property = "Value To Check"
    });
Assert.Contains("Value To Check", result.Text);

<sup><a href='/src/Verify.Tests/Tests.cs#L410-L419' title='Snippet source file'>snippet source</a> | <a href='#snippet-VerifyResult' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

If using Verifier.Throws, the resulting Exception will also be accessible

<!-- snippet: ExceptionResult -->

<a id='snippet-ExceptionResult'></a>

var result = await Throws(MethodThatThrows);
Assert.NotNull(result.Exception);

<sup><a href='/src/Verify.Tests/ThrowsTests.cs#L172-L177' title='Snippet source file'>snippet source</a> | <a href='#snippet-ExceptionResult' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

CurrentFile

Utility for finding paths based on the current file.

<!-- snippet: CurrentFile.cs -->

<a id='snippet-CurrentFile.cs'></a>

using IOPath = System.IO.Path;

namespace VerifyTests;

public static class CurrentFile
{
    public static string Path([CallerFilePath] string file = "") =>
        file;

    public static string Directory([CallerFilePath] string file = "") =>
        IOPath.GetDirectoryName(file)!;

    public static string Relative(string relative, [CallerFilePath] string file = "")
    {
        var directory = IOPath.GetDirectoryName(file)!;
        return IOPath.Combine(directory, relative);
    }
}

<sup><a href='/src/Verify/CurrentFile.cs#L1-L18' title='Snippet source file'>snippet source</a> | <a href='#snippet-CurrentFile.cs' title='Start of snippet'>anchor</a></sup>

<!-- endSnippet -->

Versioning

Verify follows Semantic Versioning. The same applies for extensions to Verify. Small changes in the resulting snapshot files may be deployed in a minor version. As such nuget updates to Verify.* should be done as follows:

Snapshot changes do not trigger a major version change to avoid causing Diamond dependency issues for downstream extensions.

Unit testing inside virtualized environment

Unit tests referencing Verify (including unit tests within this repository as well as any other code referencing Verify) can be run and debugged on a local virtualized environment supported by Visual Studio Remote Testing. Initial configurations have been added for WSL and net 7.0 linux docker via testenvironments.json (for third party code, the file needs to be copied or recreated next to the .sln solution file for solution to leverage the functionality).

Upon opening the Tests Explorer the advanced environments are available in the GUI:

TestExplorerEnvironments

This readme will not discuss definitive list of details for proper setup of the environments instead refer the following information sources and warn about particular gotchas:

Media

Blogs

Podcasts

Videos

Extensions

More Documentation

Icon

Helmet designed by Leonidas Ikonomou from The Noun Project.