Tests that read clearly and fail helpfully.

using OmniAssert;

public sealed record User(int Id, string Email, bool IsActive);

public class UserTests
{
    [Fact]
    public void Should_validate_user()
    {
        var user = new User(42, "ada@example.com", true);

        user.Id.Must().BeGreaterThan(0);
        user.Email.Must().Contain("@");
        user.Email.Must().EndWith(".com");
        user.IsActive.Must().BeTrue();
    }
}

Assertions and exceptions together

Combine value checks with exception assertions on the same test. Failure messages include the expression under test and the actual value.

using OmniAssert;

public class OrderServiceTests
{
    [Fact]
    public void CreateOrder_with_invalid_email_fails()
    {
        var email = "not-an-email";

        email.Must().NotBeNullOrEmpty();
        email.Must().Contain("@");

        var ex = (() => OrderService.Create(email)).Throws<ArgumentException>();
        ex.WithMessageContaining("invalid email");
    }
}

Installation

<ItemGroup>
  <PackageReference Include="OmniAssert" Version="2.3.0" />
  <PackageReference Include="OmniAssert.Extensions" Version="2.3.0" />
</ItemGroup>

Namespaces

Quick examples

using OmniAssert;
using OmniAssert.Extensions.Web;
using OmniAssert.Extensions.Financials;
using OmniAssert.Extensions.Security;
using OmniAssert.Extensions.Regional;

// Web
"user@acme.com".Must().BeEmailAddress();
"https://api.example.com/v1".Must().BeUrl();
"{\"id\":1}".Must().BeJson();

// Financial
"978-0-306-40615-7".Must().BeIsbn();
"GB29NWBK60161331926819".Must().BeIban();

// Security
"MyP@ssw0rd!".Must().BeStrongPassword(minLength: 12);
token.Must().BeJwt();

// Regional
"+2348012345678".Must().BeNigerianPhoneNumber();
"0022728153".Must().BeNigerianBankAccountNumber("058");

Web, network & communications

String extensions unless noted. Use core Uri assertions (HaveScheme, HaveHost, …) when you already have a parsed Uri object; use Extensions BeUrl() to validate string format before parsing.

HTTP response assertions

Use HttpResponseMessage.Must() from OmniAssert.Extensions.Web:

using var response = await client.GetAsync("/api/users");
response.Must().BeSuccessStatusCode();
response.Must().HaveContentType("application/json");

404.Must().BeHttpStatusCode(404);

Financial & industry identifiers

Security, authentication & cryptography

Regional, demographic & business rules

Failure messages & soft assertions

Extensions use the same VerificationFlow as core OmniAssert. Failures are prefixed with Verification failed: and include the captured expression (for example email) and the actual value. Inside an AssertionScope, failures are collected and reported together.

Extensions FAQ

Explicit outcomes with Ensure.Succeed() and Ensure.Fail()

Use Ensure.Succeed() when a test must pass without performing checks — for example a placeholder while behaviour is still being defined, or a branch that documents intentional no-op behaviour. Use Ensure.Fail() when a code path should never run, or when you need to abort a test with a clear message before v3-style guard assertions exist.

[Fact]
public void Placeholder_until_feature_lands()
{
    // Documents that the test harness is wired; replace with real checks later.
    Ensure.Succeed();
}

[Fact]
public void Should_reject_unsupported_platform()
{
    if (!RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
    {
        Ensure.Fail("This integration test runs on Linux CI agents only.");
    }

    service.RunLinuxOnlyWorkflow();
}

Inside an AssertionScope, Ensure.Fail() is collected like any other failure and reported when the scope is disposed — it does not throw immediately.

using (new AssertionScope())
{
    customer.Id.Must().BeGreaterThan(0);
    Ensure.Fail("billing address not yet validated");
    // Both failures are reported together when the scope ends
}

Soft assertions with AssertionScope

using (new AssertionScope())
{
    user.Name.Must().Be("John");
    user.Age.Must().Be(30);
    user.Email.Must().Contain("@");
}

Deep object comparison

BeEquivalentTo compares object graphs recursively and reports the path where values diverge. On collections it treats sequences as multisets — same elements in any order. Use BeSequenceEqual when order matters. Pass EquivalenceOptions to relax string case and nested collection order instead of inventing a separate “quasi-equivalent” API.

var expected = new InvoiceDto
{
    Number = "INV-2026-001",
    Lines =
    [
        new InvoiceLineDto("Consulting", 2, 750m),
        new InvoiceLineDto("Support", 1, 125m)
    ]
};

var actual = await client.GetInvoiceAsync("INV-2026-001");
actual.Must().BeEquivalentTo(expected);

// Case-insensitive strings + order-insensitive nested sequences
actual.Must().BeEquivalentTo(expected, new EquivalenceOptions
{
    IgnoreCase = true,
    IgnoreCollectionOrder = true
});

Collection sets and bounds

roles.Must().BeSubsetOf(allRoles);
permissions.Must().BeSupersetOf(requiredPermissions);
tags.Must().ContainOnly(allowedTags);
batch.Must().HaveCountBetween(1, 100);

Collections, predicates, and ordering

results.Must().HaveCount(documents.Count);
results.Must().BeUnique();
results.Must().AllSatisfy(r => r.Score > 0);
results.Must().AnySatisfy(r => r.Title.Contains("OmniAssert"));
results.Must().NoneSatisfy(r => r.Status == "Failed");
results.Must().BeInDescendingOrder(r => r.Score);

Exception and asynchronous assertions

Action syncAct = () => parser.Parse("");
syncAct.Throws<ArgumentException>()
    .WithMessageContaining("input");

Func<Task> asyncAct = () => service.CreateUserAsync(invalidRequest);
await asyncAct.ThrowsAsync<ValidationException>();

await TimeSpan.FromSeconds(2).CompleteWithin(
    () => service.RebuildProjectionAsync());

Compile-time boolean diagnostics

The bundled Roslyn generator rewrites supported Ensure.Expression(...) call sites at compile time. Legacy VerifyExpression() call sites are still intercepted for compatibility. When active, a bare identifier such as Ensure.Expression(flag) becomes flag.Must(expression).BeTrue(), and compound expressions capture operand snapshots on failure.

var count = orders.Count;
var limit = 10;
var hasPriorityOrder = orders.Any(o => o.Priority == Priority.High);

Ensure.Expression(count > 0 && count <= limit && hasPriorityOrder);

File system and URI checks

"appsettings.test.json".FileExists().HaveContent(expectedJson);
"artifacts".DirectoryExists().BeEmpty();

var callback = new Uri("https://github.com/bolorundurowb/OmniAssert");
callback.Must().HaveScheme("https");
callback.Must().HaveHost("github.com");

Preferred patterns

// Avoid
(count < limit).Must().BeTrue();

// Prefer
count.Must().BeLessThan(limit);

// Avoid
results.Must().HaveCount(0);

// Prefer
results.Must().BeEmpty();

// Avoid
(path.Contains('/')).Must().BeFalse();

// Prefer
path.Must().NotContain('/');

// When a single comparison assertion does not apply
Ensure.Expression(x > 0 && count < limit && hasPriority);

• Nullable collections: list.Must().BeNull() or list.Must().NotBeNull() — no (object?) cast needed.
• Apply OA001–OA004 code fixes via the light bulb, or Fix all occurrences in Solution for batch migration.

Summary of changes

Methods that never used a To prefix in v1 are unchanged — for example ContainKey, HaveHost, AllSatisfy, and file helpers like HaveContent.

Entry point: Assert → Ensure

v1 used a static class named Assert, which conflicts with NUnit, xUnit, and other frameworks.

// v1
OmniAssert.Assert.VerifyExpression(condition);

// v2 (legacy extension — still works with warnings)
Ensure.VerifyExpression(condition);

// v2 (recommended)
Ensure.Expression(condition);

Fluent chain: Verify() → Must()

// v1
count.Verify().ToBeGreaterThan(0);
user.Email.Verify().ToContain("@");

// v2
count.Must().BeGreaterThan(0);
user.Email.Must().Contain("@");

Assertion grammar: drop the To prefix

General rules:

• ToXxx(...) → Xxx(...) — e.g. ToBeFalse() → BeFalse()
• NotToXxx(...) → NotXxx(...) — e.g. NotToBeNull() → NotBeNull()

What did not change

• VerifyNullable(...) — nullable entry point (e.g. value.VerifyNullable().BeNull())
• Exception extensions — (...).Throws<T>(), NotThrow(), ThrowsAsync<T>()
• File/directory helpers — "path".FileExists().HaveContent(...)
• AssertionScope — soft assertions behave the same
• WithMessage / WithInnerException<T> — exception chaining
• Ensure.Succeed() / Ensure.Fail(...) — explicit pass and forced failure (new in v2; legacy Assert.Succeed / Assert.Fail delegate to these)

Booleans: Must() vs Ensure.Expression()

// Fluent (v2)
isValid.Must().BeTrue();

// Expression style (recommended for compound conditions)
Ensure.Expression(x > 0 && count < limit);

// Legacy extension (deprecated — removed in v3)
(x > 0 && count < limit).VerifyExpression();

When interceptors are enabled, Ensure.Expression(flag) is rewritten at compile time to flag.Must(expression).BeTrue(). Legacy VerifyExpression() call sites are still intercepted for compatibility.

Automated migration (Roslyn analyzers)

The OmniAssert NuGet package includes OmniAssert.Analyzers.dll — no extra package reference is required.

Style analyzers OA005–OA007 are documented in the assertion style section.

Applying fixes

1. Build the solution so analyzers load from the package.
2. Open a file with legacy syntax (light bulb on OA001–OA004).
3. Choose Migrate to Ensure/Must/Be* syntax, or Fix all occurrences in Solution.

// Before
Assert.Throws<InvalidOperationException>(() => act());
value.Verify().ToBeFalse();
items.Verify().NotToBeNull();
(x > y).VerifyExpression();

// After
Ensure.Throws<InvalidOperationException>(() => act());
value.Must().BeFalse();
items.Must().NotBeNull();
Ensure.Expression(x > y);

Framework name collisions

If you used Expect to avoid clashing with NUnit’s Assert, prefer Ensure in v2. The Expect wrapper remains in v2 but will be removed in v3.

// v1
Expect.Throws<ArgumentException>(() => act());

// v2
Ensure.Throws<ArgumentException>(() => act());
// or
((Action)act).Throws<ArgumentException>();

Recommended migration steps

1. Upgrade the OmniAssert package to v2.x (latest: 2.3.0).
2. Build and review OA001–OA004 warnings.
3. Run code fixes (per file or fix all in solution).
4. Search for remaining .Verify(), .ToBe, VerifyExpression, or OmniAssert.Assert usages.
5. Run tests and confirm failure messages still read as expected.
6. Optionally treat warnings as errors until migration is complete.

<PropertyGroup>
  <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  <WarningsNotAsErrors>OA001;OA002;OA003;OA004</WarningsNotAsErrors>
</PropertyGroup>