Shouldly Assertion Framework - Open Source Sponsorship

At Duende Software, we value open-source software and the contributors who dedicate their time and passion to providing solutions for the development community. Many of our engineering team contribute to .NET’s open source software (OSS) ecosystem, with over 50+ million downloads and counting of packages directly authored by our team members.

As a community, sharing reusable functionality helps the community succeed. Still, it comes at a cost to maintainers that can make it unsustainable, whether in time spent, financial costs, or other burdens.

We want to help those maintainers ease the burden of developing OSS software and managing a growing community because when they succeed, we all succeed in delivering solutions. This is why, next to directly contributing to .NET projects, we also want to sponsor and promote Open Source projects actively. Each quarter, the Duende team nominates and votes on projects they wish to support.

We’re happy to announce the first recipient of such sponsorship: Shouldly.

At Duende Software, we are using Shouldly in the test suites of all our products, including IdentityServer and the Backend For Frontend (BFF) Security Framework - we’re big fans! Let’s look at how you can get started with Shouldly.

Shouldly - Better and more descriptive test assertions

Shouldly is an assertion framework that alters the standard assertion convention in tests to provide developers with a much more natural API and better error messages in case of test failure.

Assert.That(map.IndexOfValue("boo"), Is.EqualTo(2));
// -> Expected 2 but was -1

map.IndexOfValue("boo").ShouldBe(2);
// -> map.IndexOfValue("boo") should be 2 but was -1

Shouldly also offers several logical operations that would otherwise require many developers to recreate the same task. Helper functions around equality, string comparisons, and collection assertions make writing tests a joy. They also have excellent documentation available.

Shouldly is also testing framework agnostic, supporting the most popular test frameworks, NUnit, XUnit, and MSTest. The flexibility makes it simple to add and start using a new test suite or a mature, long-term one.

To start with Shouldly, you must install the NuGet package to an existing test project.

dotnet add package Shouldly

Once installed, you can write your first Shouldly tests.

using Shouldly;

public class Tests
{
    [Fact]
    public void Duende_is_awesome()
    {
        const string duende = "Awesome";
        duende.ShouldBe("Awesome");
    }

    [Fact]
    public void Duende_should_be_like_awesome()
    {
        Duende duende = new("Awesome");
        Duende expected = new("Awesome");
        duende.ShouldBeEquivalentTo(expected);
    }
    
    public record Duende(string Adjective);
}

We have two tests here: one compares strings, while the other uses record types to check equivalency between objects. Both tests are readable and easy to maintain.

[Fact]
public void Sponsorship_should_be_250_dollars_a_month()
{
    var expected = 3_000.00; // USD
    var amount = 250.00; // USD
    var months = 12;

    (amount * months).ShouldBe(expected);
}

You can also read number-based assertions more quickly, and for exceptions, we get a formatted output that is also easier to read. I switched the expected value to 1000, knowing I’d see an error.

amount * months
    should be
1000d
    but was
3000d
   at Tests.Sponsorship_should_be_250_dollars_a_month() in 

Also, one of the more commonly needed assertions in line-of-business applications is the logical comparison of two reference types.

[Fact]
public void Person_should_be_khalid()
{
    Person expected = new("Khalid", 41);
    Person actual = new("Khalid", 41);
    
    actual.ShouldBeEquivalentTo(expected);
}

public class Person(string name, int age)
{
    public string Name { get; set; } = name;
    public int Age { get; set; } = age;
}

Equivalency helpers are a lifesaver when dealing with APIs, serialization, and data transfer object code.

Sponsorship Terms

To help the Shouldly maintainers with their wonderful project, Duende will sponsor Shouldly for the next 12 months for $250/mo or $3000 over the next year. The sponsorship will help the team cover costs or make investments in growing their project.

If you use Shouldly, we encourage you also to sponsor the project, whether financial contributions, documentation, or bug reports. Every little bit helps. Thank you for your consideration.

Conclusion

Again, we’d like to thank Shouldly and hope you join us in congratulating them on receiving Duende’s Open Source Sponsorship. It’s a fantastic project, and you should give it a try.

Our Duende Open Source Sponsorship program aims to help OSS projects and help us continue being good community citizens. We may be nostalgic about OSS, but wouldn’t be where we are without it.