I wrote a .NET assertion library to understand assertion libraries

spearzy — Tue, 05 May 2026 16:32:35 +0000

I have been working on a .NET assertion library called Axiom Assertions.

It started as a way to learn how assertion libraries work, then grew into an experiment around deterministic output, batching, analyzers, and AI-focused test assertions.

The repo is here:

https://github.com/spearzy/Axiom-Assertions

This did not start as a plan to overthrow every assertion library in .NET. That would be a bit much. The ecosystem already has good tools, and most teams quite reasonably do not wake up looking for a new way to write Should().

The real reason was simpler: I wanted to understand how assertion libraries work by writing one myself.

At some point, reading the docs for existing libraries only gets you so far. You can use an assertion library for years and still not really think about how much work is hiding behind a nice failure message. Formatting values, comparing collections, showing diffs, supporting equivalency, deciding when to fail fast, deciding when to collect failures, making APIs feel natural without turning them into soup. There is a lot going on.

So I built one. As one does, when curiosity gets out of hand.

What I built

I built Axiom Assertions, which is a fluent assertion library for .NET tests.

The basic usage is intentionally familiar:

using Axiom.Assertions;

user.Name.Should().NotBeNull();
user.Email.Should().Contain("@");

That part is not meant to be clever.

Where I wanted to experiment was in a few specific areas: deterministic failure output, explicit batching, analyzer-backed migration help, and optional assertion packages for things like JSON, HTTP responses, vectors, and retrieval tests.

I also wanted those areas to be split sensibly. If you only need the core assertion library, you should not have to pull in every extra package just because it exists.

Why deterministic output mattered to me

One thing I wanted to explore was stable failure output.

Test failures are already annoying. They become more annoying when the output is noisy, inconsistent, hard to diff, or awkward to read in CI. A failure message should help you understand what broke, not give you a small formatting puzzle just for fun.

There are already assertion libraries that focus heavily on readable failure messages. Shouldly, for example, has always had that as one of its main strengths.

Axiom is not trying to say those tools are wrong. It is more of an experiment in making stable, predictable output one of the design constraints from the start.

That means thinking about questions like:

will this message stay readable in CI?
will the output be stable enough for code review?
can repeated failures be compared without noise?
are collections and structured values shown in a predictable way?
does the output help, or is it just technically correct?

“Technically correct” is fine for a compiler. It is, howver, less charming in a failed test at 5:10pm.

Explicit batching

Another area I wanted to explore was grouped assertions.

Sometimes fail-fast is exactly right. If the first condition fails, there is no point continuing.

Other times, especially when checking a larger object or response, it is useful to collect several failures at once. If a user profile has five fields wrong, I would rather see all five in one run than fix them one at a time like some sort of unit testing advent calendar.

Axiom has an explicit batching API:

using Axiom.Assertions;
using Axiom.Core;

using var batch = Assert.Batch("profile");

user.Name.Should().StartWith("A");
user.Email.Should().Contain("@");
user.Roles.Should().Contain("admin");

The goal is to make grouped assertions intentional. Not hidden, not magical, just clear at the call site.

The AI testing bit

The other reason Axiom grew beyond a learning project was that I wanted to play with assertions for AI-adjacent code.

A lot of test libraries are very good at normal application assertions: strings, collections, numbers, exceptions, objects, HTTP responses, and so on.

But newer systems often involve embeddings, similarity, ranking, retrieval, and “close enough” comparisons. Plain equality is usually the wrong tool there. If you are testing retrieval results or vector similarity, you often care about things like top-k ranking, dot products, cosine similarity, or mean reciprocal rank.

So Axiom has an optional vectors package:

using Axiom.Assertions;
using Axiom.Vectors;

embedding.Should().HaveDotProductWith(
    expected,
    expectedDotProduct: 1f,
    tolerance: 0.001f);

results.Should().ContainInTopK("doc-7", 2);

queries.Should().HaveMeanReciprocalRank(
    expectedMeanReciprocalRank: 0.75);

This is probably the most experimental part of the project, but also the part I find most interesting.

Testing AI-ish code often gets vague very quickly. I wanted to see what a more explicit assertion API might look like for those cases.

Optional packages

Axiom is split into a main package and a few optional ones.

dotnet add package Axiom.Assertions
dotnet add package Axiom.Json
dotnet add package Axiom.Http
dotnet add package Axiom.Vectors

The idea is that the main assertion library should not need to carry every possible assertion type. If a project needs JSON assertions, add JSON. If it needs HTTP assertions, add HTTP. If it needs vector or retrieval assertions, add those.

If it does not need them, fine. Not every test project needs to bring a suitcase.

What I am looking for

The project is usable, but still early in adoption.

I am mainly looking for feedback from people who write a lot of .NET tests, especially around:

whether the failure output is actually readable
whether the batching API feels useful
whether the package split makes sense
whether the vector and retrieval assertions match real testing needs
what would stop someone from trying this in a small test project

I am not expecting anyone to rewrite a whole test suite for fun. That is how people end up in meetings.

Trying it in a small test project, looking through the docs, or opening an issue with something confusing would all be useful.

Links

Repository:

https://github.com/spearzy/Axiom-Assertions

Docs:

https://spearzy.github.io/Axiom-Assertions/

NuGet:

https://www.nuget.org/packages/Axiom.Assertions

If you have opinions about assertion libraries, test failure output, or testing vector/retrieval-heavy code in .NET, I would genuinely like to hear them.

If Axiom looks useful, interesting, or worth keeping an eye on, a star on the repo would be appreciated. It helps other .NET developers find the project and gives me a useful signal that the idea is worth continuing.

The creation of this article was supported by the use of AI.

DEV Community: spearzy