Axiom Assertions for .NET

Axiom.Assertions

Axiom Assertions is a fluent assertion library for .NET tests. It focuses on deterministic failure output, explicit batch aggregation, configurable equivalency, analyzer-backed migration help, and optional JSON, HTTP/API, vector, and retrieval assertions.

Target frameworks: net8.0, net9.0, and net10.0.

Docs site: spearzy.github.io/Axiom-Assertions

Install

Most test projects should install Axiom.Assertions:

dotnet add package Axiom.Assertions

Axiom.Assertions gives you the main Should() API, pulls in Axiom.Core, and bundles the Axiom analyzers/code fixes automatically.

Optional add-ons:

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

Advanced or special-case installs:

dotnet add package Axiom.Core
dotnet add package Axiom.Analyzers

If you are not sure which package to install, start with Axiom.Assertions and add the optional packages only when the test suite needs them.

Examples

Basic assertions and batch aggregation:

using Axiom.Assertions;
using Axiom.Core;

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

using var batch = Assert.Batch("profile");
user.Name.Should().StartWith("A");
user.Roles.Should().Contain("admin");

Structural equivalency:

using Axiom.Assertions.Equivalency;

actual.Should().BeEquivalentTo(expected, options =>
{
    options.CollectionOrder = EquivalencyCollectionOrder.Any;
    options.IgnorePath("actual.UpdatedAt");
});

Vectors and retrieval/ranking:

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);

JSON:

using Axiom.Json;

var actualJson = """{ "id": 1, "name": "Bob", "roles": ["admin", "author"] }""";
var expectedJson = """{ "roles": ["admin", "author"], "name": "Bob", "id": 1.0 }""";

actualJson.Should().BeJsonEquivalentTo(expectedJson);
actualJson.Should().HaveJsonStringAtPath("$.name", "Bob");

HTTP and API responses:

using System.Net;
using System.Net.Http;
using System.Text;
using Axiom.Http;

using var response = new HttpResponseMessage(HttpStatusCode.BadRequest)
{
    Content = new StringContent(
        """{ "title": "Validation failed", "status": 400 }""",
        Encoding.UTF8,
        "application/problem+json")
};

response.Should().HaveStatusCode(HttpStatusCode.BadRequest);
response.Should().HaveProblemDetailsTitle("Validation failed");

Packages

Package	Use it when you want...
Axiom.Assertions	the main fluent assertion library for most test projects
Axiom.Json	optional JSON assertions on top of Axiom.Assertions
Axiom.Http	optional HttpResponseMessage assertions on top of Axiom.Assertions
Axiom.Vectors	optional vector, embedding, and ranked retrieval assertions on top of Axiom.Assertions
Axiom.Core	advanced low-level primitives such as Batch, formatting, and configuration without the full assertion surface
Axiom.Analyzers	special-case diagnostics and code fixes without the runtime assertion library

Why Axiom

• Deterministic messages that stay stable in CI and code review.
• Explicit multi-assertion aggregation with Batch.
• Strong equivalency support with configurable defaults.
• Analyzer support bundled into the normal Axiom.Assertions install path.
• Optional HTTP/API response assertions without pushing that surface into every test project.
• Optional vector and retrieval assertions without complicating the core package.

Docs

Use the docs site for the full guides and reference:

• Getting Started
• Starter Projects
• Compatibility Matrix
• Assertion Reference
• Migration Guide
• xUnit migration walkthrough
• NUnit migration walkthrough
• MSTest migration walkthrough
• Axiom vs FluentAssertions side-by-side guide
• Axiom vs Shouldly side-by-side guide
• .NET assertion library
• Equivalency Guide
• JSON Guide
• HTTP/API Guide
• Vectors Guide
• Vector assertions for AI and retrieval tests in .NET
• Analyzers Guide
• Benchmarks

Project Status

Axiom is versioned and released with semantic versioning and has a full docs site, test suite, analyzers, and package distribution. It is still early in adoption, so issues and small repros are especially useful when something feels unclear or missing.