OmniAssert 2.0.0

There is a newer version of this package available.
See the version list below for details.

dotnet add package OmniAssert --version 2.0.0

NuGet\Install-Package OmniAssert -Version 2.0.0

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="OmniAssert" Version="2.0.0" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="OmniAssert" Version="2.0.0" />
                    

                            Directory.Packages.props

<PackageReference Include="OmniAssert" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add OmniAssert --version 2.0.0

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: OmniAssert, 2.0.0"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package OmniAssert@2.0.0

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=OmniAssert&version=2.0.0
                    

                            Install as a Cake Addin

#tool nuget:?package=OmniAssert&version=2.0.0
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

<div align="center"> <img src="https://raw.githubusercontent.com/bolorundurowb/OmniAssert/refs/heads/master/assets/omni-assert-logo.svg" alt="omni assert logo" /> <h1 align="center">Omni Assert</h1> </div>

OmniAssert is a modern, fluent assertion library for .NET 10 and C# 14. Write tests that read like plain English and get rich failure messages with actual values, captured expressions, and optional compile-time boolean diagnostics.

OmniAssert was built with substantial help from AI-assisted coding tools. If you use it in production, security-sensitive, or compliance-heavy environments, review the implementation and apply your organisation’s supply-chain policies.

Documentation

For installation, the full assertion API, soft assertions, object diffing, compile-time interceptors, and the v1 → v2 migration guide, see the OmniAssert documentation.

Key features

Fluent API — user.Email.Must().Contain("@") reads naturally across strings, numbers, collections, objects, exceptions, files, dates, spans, and nullable values
Deep object comparison — BeEquivalentTo compares object graphs recursively with hierarchical diffs
Soft assertions — AssertionScope collects multiple failures and reports them together
Compile-time diagnostics — optional Roslyn interceptors capture operand values when boolean expressions fail
Automated v1 migration — bundled analyzers (OA001–OA003) with code fixes and fix-all-in-solution support

Quick start

<ItemGroup>
  <PackageReference Include="OmniAssert" Version="2.0.0" />
</ItemGroup>

using OmniAssert;

[Fact]
public void Should_validate_user()
{
    user.Id.Must().BeGreaterThan(0);
    user.Email.Must().Contain("@");
    user.IsActive.Must().BeTrue();
}

Basic example

A minimal xUnit test showing the usual flow: assert values with .Must(), then verify an action throws the expected exception.

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

When an assertion fails, the message includes the expression under test (for example email) and the actual value—not just “assertion failed.”

For requirements, every assertion type, exception testing, interceptors, and upgrading from v1, see the documentation.

Contributing

See CONTRIBUTING.md for development setup and pull request guidance.

License

This project is licensed under the GNU General Public License v3.0. See LICENSE.

Product	Compatible and additional computed target framework versions.
.NET	net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net10.0
- No dependencies.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on OmniAssert:

Package	Downloads
OmniAssert.Extensions Domain-specific fluent assertions for web, financial, security, and regional validation — companion to OmniAssert.	293

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
2.3.0	509	6/26/2026
2.2.0	135	6/26/2026
2.1.0	137	6/25/2026
2.0.0	143	6/24/2026
1.3.0	157	6/7/2026
1.2.0	188	5/26/2026
1.1.2	123	5/18/2026
1.1.1	128	5/17/2026
1.1.0	134	5/17/2026
1.0.1	125	5/17/2026
1.0.0	126	5/16/2026
1.0.0-beta.1	74	5/7/2026
1.0.0-beta.0	74	5/6/2026
1.0.0-alpha.1	67	5/5/2026

v2.0.0
   - Introduced Ensure as the primary static entry point; legacy Assert remains as an obsolete compatibility wrapper.
   - Replaced fluent .Verify() with .Must(); assertion grammar now uses Be*, Not*, Have*, and related names instead of To* / NotTo* (for example BeTrue(), NotBeNull(), HaveCount()).
   - Legacy v1 syntax still compiles in v2 with [Obsolete] warnings; Assert, .Verify(), To* / NotTo* wrappers, and Expect will be removed in v3.0. See MIGRATION.md (included in the package).
   - Added OmniAssert.Analyzers with OA001–OA003 diagnostics and code fixes to migrate Assert → Ensure, .Verify() → .Must(), and legacy fluent names automatically.
   - Updated the compile-time interceptor source generator to emit Ensure.Must(...).BeTrue() instead of Assert.Verify(...).ToBeTrue().
   - VerifyExpression, VerifyNullable, exception extensions, file/directory helpers, and AssertionScope are unchanged in v2.
   - Added Ensure.Succeed() and Ensure.Fail() for explicit pass/no-op and forced failure scenarios (NUnit-style Assert.Succeed / Assert.Fail).

   v1.3.0
   - Added direct equality assertions ToBe and NotToBe to DateTimeAssertions and DateTimeOffsetAssertions.
   - Added bool ToBe(expected) overload to BoolAssertions for universal ShouldBe-style ergonomics.
   - Added Func<object?> and Func<Task<object?>> overloads for Throws/NotThrow/ThrowsAsync/NotThrowAsync so expression-bodied lambdas that return values work without statement-body casts.
   - Added Expect static class as an alternative, NUnit-friendly entry point for exception assertions when Assert is ambiguous or shadowed.

   v1.2.0
   - Added ToBeWhiteSpace, NotToBeWhiteSpace, NotToBeNullOrWhiteSpace, and NotToBeNullOrEmpty to StringAssertions.

   v1.1.2
   - Added ToBeNull() and NotToBeNull() assertions to DictionaryAssertions.
   - Added ToHaveCount(n) assertion to DictionaryAssertions.

   v1.1.1
   - Added NotContainValue to the Dictionary assertions
   - Fix float numeric comparisons

   v1.1.0
   - Added ToBeNull() and NotToBeNull() assertions to ObjectAssertions.
   - Added NotToBeOfType<T>() and NotToBeAssignableTo<T>() assertions to ObjectAssertions.

   v1.0.1
   - Added ToBe(expected) for identity/reference equality checks to Collection, Dictionary, Guid, Uri, and Object assertions.
   - Enhanced null safety in CollectionAssertions and DictionaryAssertions to provide descriptive failures instead of NullReferenceException.
   - Added WithMessageIgnoringCase to ExceptionAssertions for flexible message verification.
   - Improved failure diagnostics with recursive collection content formatting (up to 10 items) in OmniAssertionException.
   - Standardized ANSI color highlighting across all numeric, date, and time assertions for consistent terminal output.
   - Unified VerifyExpression failure path with fluent assertions via VerificationFlow.Fail.
   - Optimized source generator by removing unreachable code and reducing redundant parentheses in rewritten expressions.