Skip to content

Getting Started

Install Axiom.Assertions

Most test projects should install Axiom.Assertions.

dotnet add package Axiom.Assertions

That gives you:

  • the fluent Should() API
  • Axiom.Core transitively
  • bundled Axiom analyzers/code fixes
  • framework-native failure behavior by default for xUnit, NUnit, and MSTest

You do not need AxiomSetup.cs just to start using Axiom Assertions.

Start Using It

using Axiom.Assertions;
using Axiom.Core;

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

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

That default install path also bundles the Axiom analyzers/code fixes automatically, so common diagnostics light up without a second package.

Starter consumer projects are available in the repository if you want a minimal xUnit, NUnit, or MSTest example wired to the normal Axiom.Assertions install path:

Optional Packages

Use these when a project needs more than the default Axiom.Assertions package.

Install Use it when
Axiom.Json You want structural JSON equivalency and simple JSON path assertions.
Axiom.Http You want deterministic HttpResponseMessage assertions for exact status codes, headers, content types, JSON bodies, and ProblemDetails-style API responses.
Axiom.Vectors You want vector, embedding, and retrieval-focused assertions.
Axiom.Analyzers You only want diagnostics/code fixes without the runtime assertion library.
Axiom.Core You want low-level batching, formatting, or configuration primitives without the full fluent assertion surface.

Install optional runtime add-ons only in projects that need that surface:

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

Axiom.Analyzers and Axiom.Core are advanced or special-case installs. Most test projects do not need to reference them directly.

Optional Configuration

For most teams, there is no required setup step. Install Axiom.Assertions, write assertions, and Axiom will use native xUnit, NUnit, or MSTest assertion exceptions automatically when it detects those frameworks.

Add shared setup only when you want custom defaults across a test project:

using System;
using Axiom.Assertions.Configuration;
public static class AxiomSetup
{
    public static void Apply()
    {
        AxiomSettings.Configure(options =>
        {
            options.Core.RegexMatchTimeout = TimeSpan.FromMilliseconds(500);

            options.Equivalency.RequireStrictRuntimeTypes = false;
            options.Equivalency.FailOnMissingMembers = false;
            options.Equivalency.FailOnExtraMembers = false;
        });
    }
}

Call AxiomSetup.Apply() once from your test framework startup when you want those shared defaults:

  • xUnit: fixture constructor
  • NUnit: [SetUpFixture] + [OneTimeSetUp]
  • MSTest: [AssemblyInitialize]

You only need setup/configuration when you want custom defaults such as:

  • equivalency defaults
  • custom comparer provider
  • custom value formatter
  • custom regex timeout
  • explicit failure-strategy override
  • shared reusable modules

For shared defaults, prefer AxiomSettings.Configure(...). AxiomServices.Configure(...) and EquivalencyDefaults.Configure(...) remain available for lower-level or isolated configuration.

Async And Equivalency Examples

Task<string> rollout = Task.FromResult("pricing-api");
var continuation = await rollout.Should().SucceedWithin(TimeSpan.FromMilliseconds(50));
continuation.WhoseResult.Should().Be("pricing-api");

actual.Should().BeEquivalentTo(expected, options =>
{
    options.RequireStrictRuntimeTypes = false;
    options.CollectionOrder = EquivalencyCollectionOrder.Any;
});

Vector Example

using Axiom.Vectors;

embedding.Should().HaveDimension(1536);
embedding.Should().HaveCosineSimilarityWith(expected).AtLeast(0.995f);

JSON Example

using Axiom.Json;

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

actualJson.Should().BeJsonEquivalentTo(expectedJson);
actualJson.Should().HaveJsonStringAtPath("$.name", "Ada");
actualJson.Should().HaveJsonPath("$.roles[1]");

HTTP Example

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

Next Steps