About Assertive

Assertive is a free, open source library available on NuGet for easily writing test assertions using the power of the C# language and aims to be the easiest possible way to write assertions while still providing useful and contextual error information. It's not a test framework of itself, it's meant to be used in conjunction with a test framework like xUnit, NUnit, TUnit or MSTest.

Assert(() => order.Status == OrderStatus.Paid && order.Items.All(i => i.Quantity > 0));

Assertive does away with a long list of possible assertion methods or "fluent" assertion chaining and only provides a single Assert.That method (or just Assert() if you add using static Assertive.DSL).

Installation

dotnet add package Assertive

Or add to your project file:

<PackageReference Include="Assertive" Version="0.20.0" />

For snapshot testing with xUnit, also add:

dotnet add package Assertive.xUnit

What it looks like

With Assertive, instead of:

Assert.NotNull(payment);
Assert.Equal(50, payment.Amount);

You just write:

Assert(() => payment != null && payment.Amount == 50);

Or even just:

Assert(() => payment.Amount == 50);

As the null check isn't necessary.

If the assertion fails you will get this output in your test runner:

Using the DSL

There are two ways to write assertions with Assertive:

// Using the Assert class directly
Assert.That(() => payment.Amount == 50);

// Using the DSL for a more concise syntax
using static Assertive.DSL;

Assert(() => payment.Amount == 50);

The using static Assertive.DSL import allows you to write Assert() instead of Assert.That(). Both are functionally identical, so use whichever style you prefer.

How is this different from using Assert.IsTrue?

While Assert.IsTrue(a == b) would have the same result for a passing test, it will give you an opaque error message about false not being true or something along those lines when the test fails.

Because Assertive accepts an expression it will analyze the expression and output an error message like this:

Assertive has a number of built-in patterns that it recognizes, which currently consists of:

Boolean check (Assert(() => success))
Equality comparison (Assert(() => a == b))
Numerical comparisons (Assert(() => a >= b))
Null checks (Assert(() => value != null) or Assert(() => creditBalance.HasValue) or Assert(() => value is object))
Size and length checks (Assert(() => customers.Count(c => c.Age > 50) > 0)) or Assert(() => name.Length < 50))
Collection existence checks (Assert(() => customers.Any(c => c.Age <= 40)) or Assert(() => customers.All(c => c.IsVerified)))
Collection contains checks (Assert(() => result.Contains("test")))
Collection equality comparison (Assert(() => seq1.SequenceEqual(seq2)))
String contains/starts with/ends with checks (Assert(() => name.StartsWith("John")))
Reference equality checks (Assert(() => ReferenceEquals(a, b)))
Type checks (Assert(() => value is string))

When there is no matching pattern for your assertion, it will simply report the assertion that failed plus whatever useful information can be distilled from the assertion.

You can also define your own custom patterns.

Features

Multiple assertions

It's possible to write multiple related assertions in the same statement, which makes for clearer and shorter code.

For example:

var list = new List<string>()
{
    "bar"
};

Assert(() => list.Count == 1 && list[0].StartsWith("foo"));

This assertion would fail with the message:

Short-circuiting works as you would expect, if the first assertion fails then the second one is not evaluated.

Likewise, it's possible to use a bitwise AND (&) to force evaluation of both sides.

Exception assertions

To assert that code throws an exception, use Assert.Throws:

// Assert that any exception is thrown
var ex = Assert.Throws(() => SomeMethodThatThrows());

// Assert that a specific exception type is thrown
var ex = Assert.Throws<ArgumentException>(() => Validate(null));

// Assert exception type and validate the exception
var ex = Assert.Throws<ArgumentException>(
    () => Validate(null),
    e => e.ParamName == "input"
);

The thrown exception is returned, so you can perform additional assertions on it:

var ex = Assert.Throws<InvalidOperationException>(() => Process());
Assert(() => ex.Message.Contains("not initialized"));

For async code, use the async overloads:

var ex = await Assert.Throws<HttpRequestException>(
    async () => await client.GetAsync("https://invalid.url")
);

If the code doesn't throw (or throws the wrong exception type), Assertive reports exactly what happened:

Assert.Throws<ArgumentException>(() => Validate("valid input"));
// Fails with: Expected ArgumentException but no exception was thrown.

Assert.Throws<ArgumentException>(() => ThrowsInvalidOperation());
// Fails with: Expected ArgumentException but InvalidOperationException was thrown.

Snapshot testing

Inspired by the snapshot testing of Verify Assertive also supports snapshot testing of objects. What this means is that you simply call Assert(myObject); (or Assert.Snapshot if not using using static Assertive.DSL) and a snapshot is made of the object (in JSON format) and is compared to a stored snapshot from a previous execution. If they still match, the test passes and otherwise it fails.

The first time you add a snapshot assertion, no expected.json file exists yet for the assertion. If you have a diff tool like WinMerge installed, you can integrate with the excellent DiffEngine and register it like this:

Configuration.Snapshots.LaunchDiffTool = (actual, expected) =>
{
    DiffRunner.Launch(actual, expected);
};

A window will pop up with the actual file and the expected file (or an empty one if one doesn't exist yet) and if the actual.json file matches your expectations, you can copy the contents of the actual.json file to expected.json and commit it to version control.

Configuration

You can change the global configuration of snapshot testing with the Assertive.Config.Configuration.Snapshots property.

You can also create a test specific copy and pass it to Assert:

Assert(obj, Configuration.Snapshots with { ExcludeNullValues = true });

Expected files

By default, the expected file is created in the same directory as the test itself and has this format:

<Class>.<Test>#<Expression>_<Counter>.expected.json

So when you have this test:

public class CustomerTests
{
    [Fact]
    public async Task GetCustomer_works()
    {
        var fetchedCustomer = await GetCustomer(1);
        Assert(fetchedCustomer);
    }
}

The file name will end up being:

CustomerTests.GetCustomer_works#fetchedCustomer_1.expected.json

If you have multiple assertions on the same fetchedCustomer (if you make any modifications for example) then a _2 file will be created and so on.

In case you want to modify this, you can alter the <Expression> part like so:

Assert(fetchedCustomer, "myAssertion");

And the file created will be:

CustomerTests.GetCustomer_works#myAssertion.expected.json

Normalization

Normalization can be used to change volatile values such as identifiers, Guids, dates and times into constant ones. By default, Guid and various built-in date types are normalized. So in the output snapshot, a Guid like "c8f33fe6-a30e-42ed-8283-b51a5eced158" will simply become "{Guid}".

This can be changed with:

Configuration.Snapshots.Normalization.NormalizeGuid = false;
Configuration.Snapshots.Normalization.NormalizeDateTime = false;

More advanced configuration is also possible:

Configuration.Snapshots.Normalization.ValueRenderer = (property, obj, value) =>
{
    if (property.Name.Contains("Id"))
    {
        return "{Id}";
    }

    return value;
};

This approach lets you easily stabilize test outputs.

Placeholders

Instead of normalizing the actual.json, you can also work with placeholders in the expected.json (or any mix of the two).

Say you have this actual.json:

{
    "ProductId" : "8731580994818888942",
    "Price" : 34.99
}

Assuming both are volatile (so changing every test run) you could add a normalizer for all decimal properties, or add a very specific exclusion for this test, or you could define the expected.json like this:

{
    "ProductId" : "@@productid",
    "Price" : "@@price" 
}

Anything after @@ is arbitrary and up to you. As long as actual and expected both have the property, it will be considered a match. You can configure the placeholder prefix with Configuration.Snapshots.Normalization.PlaceholderPrefix and it defaults to "@@".

Advanced placeholders

Say you have this snapshot:

{
    "ProductId" : "8731580994818888942",
    "BeforePrice" : 34.99,
    "AfterPrice" : 34.99,
    "TaxAmount" : 3.50,
    "DiscountAmount" : 0
}

In this imagined scenario, it's important that BeforePrice and AfterPrice are the same, simply replacing both with a constant placeholder would not be good enough. To support this, you can tag each distinct value with a number to indicate two of the same placeholder type should have the same value:

{
    "ProductId" : "@@productid",
    "BeforePrice" : "@@price#1", 
    "AfterPrice" : "@@price#1",
    "TaxAmount" : "@@price#2",
    "DiscountAmount" : 0
}

To go even further, you can register a validator for each placeholder type:

Configuration.Snapshots.Normalization
  .RegisterPlaceholderValidator("price", value => 
    decimal.TryParse(value, out var price) && price > 0, "Price must be a positive number.");

Advanced configuration

Several additional options are available for fine-tuning snapshot behavior:

Ignoring properties:

Configuration.Snapshots.ShouldIgnore = (property, obj, value) =>
{
    // Ignore all properties ending with "Id"
    return property.Name.EndsWith("Id");
};

Handling extraneous properties:

When the actual object has properties that don't exist in the expected snapshot, you can control the behavior:

// Fail the test (default)
Configuration.Snapshots.ExtraneousProperties = (name, value) => 
    ExtraneousPropertiesOptions.Disallow;

// Ignore extra properties
Configuration.Snapshots.ExtraneousProperties = (name, value) => 
    ExtraneousPropertiesOptions.Ignore;

// Auto-update the expected file with new properties
Configuration.Snapshots.ExtraneousProperties = (name, value) => 
    ExtraneousPropertiesOptions.AutomaticUpdate;

Custom exception rendering:

When a property getter throws an exception during serialization:

Configuration.Snapshots.ExceptionRenderer = (property, obj, exception) =>
{
    return $"<{exception.GetType().Name}>";
};

Custom expected file location:

Configuration.Snapshots.ExpectedFileDirectoryResolver = (testMethod, sourceFile) =>
{
    // Store all snapshots in a central __snapshots__ folder
    return Path.Combine(sourceFile.DirectoryName!, "__snapshots__");
};

Bulk snapshot regeneration:

When you need to regenerate all expected files (e.g., after a major refactoring):

Configuration.Snapshots.TreatAllSnapshotsAsCorrect = true;

This will overwrite ALL expected files with actual values - both new and existing. Remember to set it back to false after regenerating. Then, simply check the diff in whatever source-control tool you use to check that the new expected files match your assumptions.

Auto-accepting new snapshots only:

When writing new tests (especially useful for AI agents and automated workflows), you can auto-accept new snapshots while still failing on changes to existing ones:

Configuration.Snapshots.AcceptNewSnapshots = true;

Unlike TreatAllSnapshotsAsCorrect, this only affects new snapshots where no expected file exists yet. Existing snapshots are still compared normally - changes to existing snapshots will still fail the test.

New snapshot workflow:

When a snapshot assertion fails because no expected file exists, Assertive:

Shows the expected file path in the error message
Shows the actual JSON value that needs to be saved
Creates an empty expected file (so the directory structure exists)

To accept a new snapshot, copy the actual JSON from the error message to the expected file.

Exception handling

Assertive has special handling of certain common exceptions that occur when writing tests, providing immediate feedback on what caused the exception without having to attach the debugger or dig through stacktraces.

NullReferenceExceptions

When a NullReferenceException occurs somewhere within your assertion (because the thing you thought wasn't going to be null was in fact null) Assertive will try to find the cause of that exception by looking at what you dereferenced and what part of that was null or returned null.

Example:

Foo foo = new Foo();
      
Assert(() => foo.Bar.Value.Length == 1);

Assuming foo.Bar was not initialized, this assertion will fail with a message of:

NullReferenceException caused by accessing Value on foo.Bar which was null.

Likewise, an ArgumentNullException caused by calling a LINQ method such as Where on an IEnumerable<T> that is null is handled in the same way.

Because of this, you can omit null checks in your assertions while still getting helpful error messages.

IndexOutOfRangeException

When an IndexOutOfRangeException is thrown because you access an array or list index that is out of bounds, Assertive will try to find the cause of the exception by looking at where you accessed an index that was out of bounds.

Example:

int[] data = GetData();
      
var start = GetStartIndex();

Assert(() => data[start] > 0)

Assuming data only has a length of 2 but GetStartIndex() returned 4, this will fail with a message of:

IndexOutOfRangeException caused by accessing index start (value: 4) on data, actual length was 2.

InvalidOperationException caused by Single/First

If you have a sequence that you thought was only going to contain one item but in fact contained multiple, or if you have a sequence that you thought was going to contain something but that was actually empty, an InvalidOperationException will be thrown. Assertive will try to find the cause of this exception and report the contents of the sequence.

Example:

var names = GetNames();

Assert(() => names.Single() == "Bob");

Message if names is empty:

However if names has more than one element:

KeyNotFoundException

When a KeyNotFoundException is thrown because you access a dictionary key that doesn't exist, Assertive will identify the missing key and show the available keys in the dictionary.

Example:

var dict = new Dictionary<string, int>
{
    ["foo"] = 1,
    ["bar"] = 2
};

var key = "missing";

Assert(() => dict[key] == 3);