Unit testing with xUnit

Why automated tests?

You change the GST calculation for one product type and accidentally break it for all others. Without tests you find out from an angry customer. With tests, you run one command and see within seconds that 3 of 120 checks fail, and exactly which ones. Tests let teams change code without fear, and most .NET jobs expect you to write them.

Setting up a test project

dotnet new sln -n Billing
dotnet new classlib -o Billing.Core
dotnet new xunit -o Billing.Tests
dotnet sln add Billing.Core Billing.Tests
dotnet add Billing.Tests reference Billing.Core
dotnet test

xUnit v3 is the newest major version of xUnit; check xunit.net for its current templates. [Fact], [Theory], [InlineData] and the Assert methods shown here work the same way in v2 and v3. MSTest and NUnit are other popular .NET test frameworks with very similar ideas.

The code under test

namespace Billing.Core;

public static class GstCalculator
{
    public static decimal AddGst(decimal amount, decimal ratePercent)
    {
        if (amount < 0) throw new ArgumentOutOfRangeException(nameof(amount), "Amount cannot be negative");
        return Math.Round(amount + amount * ratePercent / 100, 2, MidpointRounding.AwayFromZero);
    }
}

Your first tests: Arrange, Act, Assert

using Billing.Core;

namespace Billing.Tests;

public class GstCalculatorTests
{
    [Fact]
    public void AddGst_18Percent_AddsTax()
    {
        // Arrange
        decimal amount = 1000m;

        // Act
        decimal total = GstCalculator.AddGst(amount, 18);

        // Assert
        Assert.Equal(1180m, total);
    }

    [Fact]
    public void AddGst_NegativeAmount_Throws()
    {
        Assert.Throws<ArgumentOutOfRangeException>(() => GstCalculator.AddGst(-1m, 18));
    }
}

Theories: one test, many inputs

[Theory]
[InlineData(100, 5, 105)]
[InlineData(100, 12, 112)]
[InlineData(0, 18, 0)]
[InlineData(99.99, 18, 117.99)]
public void AddGst_VariousRates(double amount, double rate, double expected)
{
    Assert.Equal((decimal)expected, GstCalculator.AddGst((decimal)amount, (decimal)rate));
}

Useful assertions

Testing async code

[Fact]
public async Task LoadAsync_ReturnsSavedItems()
{
    var store = new InMemoryStore();
    await store.SaveAsync("pen");

    var items = await store.LoadAsync();

    Assert.Contains("pen", items);
}

What makes a good unit test

• Fast: milliseconds. No real network, database or sleeping.
• Independent: each test sets up its own data. xUnit creates a new instance of the test class for every test, so fields do not leak between tests.
• Repeatable: same result every run. Avoid DateTime.Now and random numbers without a fixed seed.
• One behaviour per test: when it fails, you know what broke.
• Tests behaviour, not private details: test what the public method promises.

Common mistakes and fixes

• A test with no Assert: it always passes and proves nothing.
• Testing with real time: a test that checks "today is a weekday" fails every Saturday. Inject the time (next topic).
• Big tests that check ten things: split them.
• Ignoring failing tests: a red test means something is wrong. Fix the code or the test, do not skip it silently.