exception-message-format.md

Exception Message Format

When a Verify test fails, the exception message is designed to be machine-parsable. This enables tooling (IDE extensions, CI integrations, diff tools) to programmatically extract file paths and take action on verification failures.

Message Structure

The message has two parts: a file listing followed by optional file content.

File Listing

The first line is always the directory:

Directory: /path/to/test/project

Then zero or more categorized sections, each listing file pairs:

• New - a .received. file exists with no corresponding .verified. file (first test run or new test).
• NotEqual - both files exist but content differs.
• Delete - a .verified. file exists that is no longer produced by any test.
• Equal - both files exist and match (included for completeness when other categories are present).
• InlineNew - an inline snapshot with no expected value yet.
• InlineNotEqual - an inline snapshot whose expected value differs from the result.

Inline entries use a different shape: a Source: line with the absolute source file path and 1 based line number (path:line), followed by optional absolute staged file paths:

InlineNotEqual:
  - Source: /path/to/MyTests.cs:12
    Received: /path/to/obj/VerifyInline/def.received.txt
    Expected: /path/to/obj/VerifyInline/def.expected.txt
    Patch: /path/to/obj/VerifyInline/def.inlinepatch

The staged path lines are omitted when staging was unavailable (build server, or the project does not consume Verify's build props). The Patch: file is readable via the DiffEngine InlinePatchFile API.

File Content

After the file listing, a FileContent: section includes the text content of new and not-equal files. This section is only present when there are text-based new or not-equal files. Binary files are listed in the file listing but their content is not included.

Example: All Categories

Directory: {ProjectDirectory}
New:
  - Received: MyTests.Test1.received.txt
    Verified: MyTests.Test1.verified.txt
NotEqual:
  - Received: MyTests.Test2.received.txt
    Verified: MyTests.Test2.verified.txt
Delete:
  - MyTests.OldTest.verified.txt
Equal:
  - Received: MyTests.Test3.received.txt
    Verified: MyTests.Test3.verified.txt

FileContent:

New:

Received: MyTests.Test1.received.txt
the new content

NotEqual:

Received: MyTests.Test2.received.txt
received text
Verified: MyTests.Test2.verified.txt
verified text

^{snippet source | anchor}

Inline snapshot examples

Directory: {ProjectDirectory}
InlineNew:
  - Source: {ProjectDirectory}MyTests.cs:10
    Received: {ProjectDirectory}obj/VerifyInline/abc.received.txt
    Expected: {ProjectDirectory}obj/VerifyInline/abc.expected.txt
    Patch: {ProjectDirectory}obj/VerifyInline/abc.inlinepatch

FileContent:

InlineNew:

Source: {ProjectDirectory}MyTests.cs:10
Received:
the new content

^{snippet source | anchor}

Directory: {ProjectDirectory}
InlineNotEqual:
  - Source: {ProjectDirectory}MyTests.cs:12
    Received: {ProjectDirectory}obj/VerifyInline/def.received.txt
    Expected: {ProjectDirectory}obj/VerifyInline/def.expected.txt
    Patch: {ProjectDirectory}obj/VerifyInline/def.inlinepatch
Delete:
  - MyTests.OldTest.verified.txt

FileContent:

InlineNotEqual:

Source: {ProjectDirectory}MyTests.cs:12
Received:
received text
Expected:
expected text

^{snippet source | anchor}

Only the first target of a verification is inlined, so one message can carry an inline section and the file sections for the remaining targets together:

Directory: {ProjectDirectory}
InlineNotEqual:
  - Source: {ProjectDirectory}MyTests.cs:14
NotEqual:
  - Received: MyTests.Test1#01.received.txt
    Verified: MyTests.Test1#01.verified.txt
Delete:
  - MyTests.OldTest.verified.txt

FileContent:

InlineNotEqual:

Source: {ProjectDirectory}MyTests.cs:14
Received:
inline received
Expected:
inline expected

NotEqual:

Received: MyTests.Test1#01.received.txt
received text
Verified: MyTests.Test1#01.verified.txt
verified text

^{snippet source | anchor}

NotEqual with Comparer Message

When a custom comparer provides a message, the content section uses Compare Result: instead of inline file content:

Directory: {ProjectDirectory}
NotEqual:
  - Received: MyTests.Test1.received.txt
    Verified: MyTests.Test1.verified.txt

FileContent:

NotEqual:

Received: MyTests.Test1.received.txt
Verified: MyTests.Test1.verified.txt
Compare Result:
The comparer reported a difference

^{snippet source | anchor}

Content Omission

The FileContent: section can be suppressed globally:

public static class ModuleInitializer
{
    [ModuleInitializer]
    public static void Init() =>
        VerifierSettings.OmitContentFromException();
}

^{snippet source | anchor}

This is useful in CI environments where only the file paths are needed.

Parsing Exception Messages

The Verify.ExceptionParsing NuGet package provides a parser for this format.

Usage

static Result ParseExceptionMessage(string exceptionMessage)
{
    var result = Parser.Parse(exceptionMessage);

    // result.New: files with no corresponding .verified. file
    // result.NotEqual: files where .received. differs from .verified.
    // result.Delete: .verified. files no longer produced by any test
    // result.Equal: files where .received. matches .verified.

    foreach (var file in result.NotEqual)
    {
        Debug.WriteLine($"Received: {file.Received}");
        Debug.WriteLine($"Verified: {file.Verified}");
    }

    return result;
}

^{snippet source | anchor}

The Result contains:

• New - list of FilePair (received and verified paths).
• NotEqual - list of FilePair.
• Delete - list of file paths.
• Equal - list of FilePair.
• InlineNew - list of InlineEntry (source file, line, and optional staged paths).
• InlineNotEqual - list of InlineEntry.

Test Framework Prefixes

Different test frameworks prepend different prefixes to the exception message. The parser handles these automatically:

• NUnit: VerifyException : Directory: ...
• MSTest: Test method ... threw exception:\nVerifyException: Directory: ...
• Other frameworks: Directory: ...