Shouldly

Visit Website

Introduction

Shouldly is an assertion framework for .NET whose main idea is better failure messages. When map.IdOnDisk.ShouldBe(1) fails, Shouldly prints the actual source code of the assertion, for example “map.IdOnDisk should be 1 but was 2”, instead of a generic “expected 1 but was 2”. That makes failures understandable without opening the test.

Assertions are extension methods such as ShouldBe, ShouldNotBeNull, ShouldContain, ShouldBeEmpty, ShouldBeGreaterThan, ShouldStartWith, ShouldThrow<T>() and ShouldThrowAsync<T>(). ShouldSatisfyAllConditions groups several checks and reports all failures, and ShouldMatchApproved supports approval-style tests that compare output against an approved file. Shouldly is a lighter, permissively licensed alternative to Fluent Assertions, and has drawn renewed interest since that library’s licence change. The latest release is 4.3.0 (23 January 2025), with ongoing commits in November 2026.

The source code is at shouldly/shouldly on GitHub under the BSD-3-Clause licence, with about 3,400 stars; the most recent commit was on 11 November 2026.

Features

1. Source-aware messages: Failures show the expression being asserted.
2. Simple API: ShouldBe, ShouldContain, ShouldThrow and more.
3. Grouped conditions: ShouldSatisfyAllConditions.
4. Approval testing: ShouldMatchApproved for output snapshots.

Pros

1. Free to use: Open source under the BSD-3-Clause licence, so the core tool costs nothing to use.
2. Actively maintained: The repository had commits as recent as 11 November 2026.
3. Community: About 3,400 GitHub stars.

Cons

1. Smaller API than Fluent Assertions: Fewer specialised assertions for complex graphs.
2. Release cadence: The last tagged release is from January 2025.

Usage and Links (Example)

using Shouldly;

[Fact]
public void CalculatesTotals()
{
    var cart = new Cart();
    cart.Add(new Item("apple", 2));

    cart.Total.ShouldBe(2);
    cart.Items.ShouldContain(i => i.Name == "apple");
    Should.Throw<InvalidOperationException>(() => cart.Checkout(paymentMethod: null));
}

Resources:

• Shouldly website
• GitHub repository

Pricing

Shouldly is free and open source under the BSD-3-Clause licence.

Recommended for?

1. .NET teams wanting clear failure messages with a simple, permissive library.
2. Teams moving away from Fluent Assertions because of licensing.

Conclusion

Shouldly delivers simple assertions with some of the most helpful failure messages in .NET, under a permissive licence.