Assert.AddValueFormatter Method

Definition

Namespace:
Microsoft.VisualStudio.TestTools.UnitTesting
Assembly:
MSTest.TestFramework.dll
Package:
MSTest.TestFramework v4.3.0

Overloads

Name Description
AddValueFormatter(Func<Func<Object,String>,Func<Object,String>>)

Registers a chain-of-responsibility value-formatter factory. The factory receives the next formatter in the chain and returns a new formatter; the returned formatter should either produce a string for the values it handles or delegate to next for the values it does not handle. The registration is scoped to the current asynchronous flow and is removed when the returned IDisposable is disposed.
AddValueFormatter<T>(Func<T,String>)

Registers a custom formatter that controls how values of T are rendered inside structured assertion failure messages. The registration is scoped to the current asynchronous flow (backed by AsyncLocal<T>) and is removed when the returned IDisposable is disposed.

AddValueFormatter(Func<Func<Object,String>,Func<Object,String>>)

Source:
Assert.AddValueFormatter.cs

Registers a chain-of-responsibility value-formatter factory. The factory receives the next formatter in the chain and returns a new formatter; the returned formatter should either produce a string for the values it handles or delegate to next for the values it does not handle. The registration is scoped to the current asynchronous flow and is removed when the returned IDisposable is disposed.

public static IDisposable AddValueFormatter(Func<Func<object?,string>,Func<object?,string>> factory);
[System.Diagnostics.CodeAnalysis.Experimental("MSTESTEXP", UrlFormat="https://aka.ms/mstest/diagnostics#{0}")]
public static IDisposable AddValueFormatter(Func<Func<object?,string>,Func<object?,string>> factory);
static member AddValueFormatter : Func<Func<obj, string>, Func<obj, string>> -> IDisposable
[<System.Diagnostics.CodeAnalysis.Experimental("MSTESTEXP", UrlFormat="https://aka.ms/mstest/diagnostics#{0}")>]
static member AddValueFormatter : Func<Func<obj, string>, Func<obj, string>> -> IDisposable
Public Shared Function AddValueFormatter (factory As Func(Of Func(Of Object, String), Func(Of Object, String))) As IDisposable

Parameters

factory
Func<Func<Object,String>,Func<Object,String>>

A function that receives the next formatter in the chain and returns a formatter to install ahead of it.

Returns

IDisposable

An IDisposable whose disposal removes the registration.

Attributes
ExperimentalAttribute

Exceptions

ArgumentNullException

factory is null.

Remarks

Use this overload when you need to inspect more than a single type (for example to render any object that implements a marker interface) or when you need explicit control over delegation to next. For the common "format a specific type" case prefer AddValueFormatter<T>(Func<T,String>).

factory is the chain builder, not the formatter itself: it is invoked every time a value is rendered while the registration is active (the chain is rebuilt per render so that out-of-order disposal of other registrations is honored), not just once at registration time. Keep it cheap and side-effect free; perform any expensive setup outside the factory and have it return a formatter that closes over the precomputed state.

Applies to

AddValueFormatter<T>(Func<T,String>)

Source:
Assert.AddValueFormatter.cs

Registers a custom formatter that controls how values of T are rendered inside structured assertion failure messages. The registration is scoped to the current asynchronous flow (backed by AsyncLocal<T>) and is removed when the returned IDisposable is disposed.

public static IDisposable AddValueFormatter<T>(Func<T,string?> formatter);
[System.Diagnostics.CodeAnalysis.Experimental("MSTESTEXP", UrlFormat="https://aka.ms/mstest/diagnostics#{0}")]
public static IDisposable AddValueFormatter<T>(Func<T,string?> formatter);
static member AddValueFormatter : Func<'T, string> -> IDisposable
[<System.Diagnostics.CodeAnalysis.Experimental("MSTESTEXP", UrlFormat="https://aka.ms/mstest/diagnostics#{0}")>]
static member AddValueFormatter : Func<'T, string> -> IDisposable
Public Shared Function AddValueFormatter(Of T) (formatter As Func(Of T, String)) As IDisposable

Type Parameters

T

The type whose rendered representation should be customized.

Parameters

formatter
Func<T,String>

A function that returns the string representation to use, or null to fall through to the next registered formatter (or the built-in renderer when no other formatter handles the value).

Returns

IDisposable

An IDisposable whose disposal removes the registration.

Attributes
ExperimentalAttribute

Exceptions

ArgumentNullException

formatter is null.

Examples

[TestMethod]
public void DateTimeFailureShowsKind()
{
    using var _ = Assert.AddValueFormatter<DateTime>(dt => $"{dt:O} [{dt.Kind}]");
    Assert.AreEqual(DateTime.UtcNow, DateTime.Now);
}

Remarks

Formatters affect only how values are rendered in failure messages. They do not change equality comparisons performed by assertions such as Assert.AreEqual. To customize equality, use the existing IEqualityComparer<T> overloads.

Registrations stack newest-first: the most recently registered formatter is consulted first. A formatter returning null defers to the next formatter, and ultimately to the built-in renderer. null values are always rendered as "null" by the built-in renderer and are never passed to user formatters.

Common registration sites and their effective scope:

  • Inside a [TestMethod]: that test method (and its async continuations).
  • [TestInitialize]: each test in the containing class.
  • [ClassInitialize]: all tests in the containing class.
  • [AssemblyInitialize]: all tests in the containing assembly.

Applies to