readme.source.md

Verify

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.

Part of the .NET Foundation

NuGet packages

• https://nuget.org/packages/Verify.Xunit/
• https://nuget.org/packages/Verify.NUnit/
• https://nuget.org/packages/Verify.MSTest/

Snapshot management

• ReSharper test runner support
• Rider test runner support
• In the Windows Tray via DiffEngineTray
• Via the clipboard.

Usage

Class being tested

Given a class to be tested:

snippet: ClassBeingTested

xUnit

Support for xUnit

snippet: SampleTestXunit

• Verify Xunit Intro

NUnit

Support for NUnit

snippet: SampleTestNUnit

MSTest

Support for MSTest

snippet: SampleTestMSTest

Initial Verification

When the test is initially run will fail with:

First verification. Sample.Test.verified.txt not found.
Verification command has been copied to the clipboard.

The clipboard will contain the following:

cmd /c move /Y "C:\Code\Sample\Sample.Test.received.txt" "C:\Code\Sample\Sample.Test.verified.txt"

Notes:

• More Clipboard info.
• An alternative to using the clipboard is the DiffEngineTray tool.

If a Diff Tool is detected it will display the diff:

To verify the result:

• Execute the command from the clipboard, or
• Use the diff tool to accept the changes, or
• Manually copy the text to the new file

Verified result

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

snippet: Verify.Xunit.Tests/Snippets/Sample.Test.verified.txt

Subsequent Verification

If the implementation of ClassBeingTested changes:

snippet: ClassBeingTestedChanged

And the test is re run it will fail with

Verification command has been copied to the clipboard.
Assert.Equal() Failure
                                  ↓ (pos 21)
Expected: ···\n  GivenNames: 'John',\n  FamilyName: 'Smith',\n  Spouse: 'Jill···
Actual:   ···\n  GivenNames: 'John James',\n  FamilyName: 'Smith',\n  Spouse:···
                                  ↑ (pos 21)

The clipboard will again contain the following:

cmd /c move /Y "C:\Code\Sample\Sample.Test.received.txt" "C:\Code\Sample\Sample.Test.verified.txt"

See also: Clipboard

The Diff Tool is will display the diff:

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.

VerifyJson

VerifyJson performs the following actions

• Convert to JToken (if necessary).
• Apply ignore member by name for keys.
• PrettyPrint the resulting text.

snippet: VerifyJson

Results in:

snippet: SerializationTests.VerifyJsonString.verified.txt

Received and Verified

• All *.verified.* files should be committed to source control.
• All *.received.* files should be excluded from source control.

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

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:

• Updates all Verify.*packages in isolation
• Re-run all tests.
• If there are changes, ensure they look correct given the release notes. If the changes do not look correct, raise an issue.
• Accept those changes.

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

Videos

• Verify Xunit Intro

Extensions

• Verify.AngleSharp: Html verification utilities via AngleSharp.
• Verify.Aspose: Verification of documents (pdf, docx, xslx, and pptx) via Aspose.
• Verify.Blazor: Verification of Blazor Component via bunit or via raw Blazor rendering.
• Verify.Cosmos: Verification of Azure CosmosDB.
• Verify.DiffPlex: Comparison of text via DiffPlex.
• Verify.EntityFramework: Verification of EntityFramework bits.
• Verify.HeadlessBrowsers: Verification of Web UIs using Playwright, Puppeteer Sharp, or Selenium.
• Verify.ICSharpCode.Decompiler: Comparison of assemblies and types via ICSharpCode.Decompiler.
• Verify.ImageMagick: Verification and comparison of images via Magick.NET.
• Verify.ImageSharp: Verification of images via ImageSharp.
• Verify.NServiceBus: Verify NServiceBus Test Contexts.
• Verify.NodaTime: Support for NodaTime.
• Verify.Phash: Comparison of documents via Phash.
• Verify.RavenDb: Verification of RavenDb bits.
• Verify.SqlServer: Verification of SqlServer bits.
• Verify.SourceGenerators: Verification of C# Source Generators.
• Verify.Web: Verification of web bits.
• Verify.WinForms: Verification of WinForms UIs.
• Verify.Xamarin: Verification of Xamarin UIs.
• Verify.Xaml: Verification of Xaml UIs.
• Spectre.Verify.Extensions: Add an attribute driven file naming convention to Verify.

More Documentation

include: doc-index

Alternatives

Projects/tools that may be a better alternative to Verify

• ApprovalTests
• Snapshooter
• Snapper
• Polaroider

Icon

Helmet designed by Leonidas Ikonomou from The Noun Project.