Organising a Test Suite

A suite of eight hundred tests has an interface, and the interface is the list of names that appear when something fails.

That list is usually all anyone reads. Nobody opens a test file because the build went red — they read the failing names, form a hypothesis, and only then open a file. If the names do not support that, every failure costs ten minutes before the work starts.

This lesson is about two things that decide whether the list is useful: what each test is called, and whether tests can influence each other. The second matters because a test that fails for something another test did produces a name that is actively misleading.

// A suite named after methods
Failed OrderServiceTests.SubmitTest
Failed OrderServiceTests.SubmitTest2
Failed OrderServiceTests.TestTotals

// The same suite, named after scenarios and expectations
Failed Submit_WhenOrderIsAlreadySubmitted_Throws
Failed Submit_WhenOrderHasNoLines_Throws
Failed CreateOrder_WithThreeItemsAtTwentyFive_SetsTotalToSeventyFive

• The first report says something is wrong with submitting orders. You know the area and nothing else, so the next step is opening three files.
• The second report is a diagnosis. Two rejection rules and one calculation have broken together, which points at a shared change — probably to how an order's lines are read — and you can form that hypothesis without opening anything.
• The pattern is method, scenario, expectation. Underscores separate the three parts because they make the boundaries visible in a long name; a team that prefers a different separator loses nothing as long as all three parts are there.
• Long names are correct here. A test name is read far more often than it is typed, and it is never called from other code, so the usual pressure towards short identifiers does not apply.
• SubmitTest2 deserves a specific mention. A number in a test name means somebody needed a second scenario and did not say what it was. Whatever distinguishes it from the first is the name.

Shared setup couples tests without saying so, and the instinct behind it is the same instinct that serves you well in production code. Removing duplication from tests is the main source of unexplained failures in test suites.

The reason is that a test is a self-contained description of one scenario. When setup moves out of it and into something shared, the description becomes incomplete, and worse, mutable — two tests can now change the same object, and the second one to run sees the first one's changes.

xUnit helps here by default and it is worth knowing exactly how. It creates a new instance of the test class for every test, so instance fields and the constructor are per-test setup and cannot leak. Static fields, IClassFixture and collection fixtures are the deliberate exceptions, and each one is a decision to share.

public class OrderServiceTests
{
    // 1. Per-test setup. A new instance of this class is created for every
    //    test, so nothing here can leak between them.
    private readonly InMemoryOrderRepository _repository = new();
    private readonly OrderService _service;

    public OrderServiceTests() => _service = new OrderService(_repository);

    // 2. Shared, and safe, because it is immutable and derived per call.
    private static Order ADraftOrder() => new OrderBuilder().Build();

    // 3. Shared and mutable — the problem case.
    private static readonly Order TheOrder = new OrderBuilder().Build();

    [Fact]
    public void Submit_WhenOrderIsDraft_SetsStatusToSubmitted()
    {
        _service.Submit(TheOrder);                       // mutates TheOrder
        Assert.Equal(OrderStatus.Submitted, TheOrder.Status);
    }

    [Fact]
    public void AddDiscount_OnADraftOrder_ReducesTheTotal()
    {
        _service.AddDiscount(TheOrder, 10);              // may now be submitted
        Assert.Equal(180m, TheOrder.Total);
    }
}

• The fields in section 1 look shared and are not. xUnit constructs the class again for each test, so each test gets its own repository and service. This is the cheapest correct way to remove setup duplication in xUnit, and it is the one to reach for first.
• The helper method in section 2 is safe because it returns a new order on every call. Sharing a factory is fine; sharing an instance is not.
• The static field in section 3 is the failure. Both tests act on the same order, so the result depends on which ran first — and xUnit gives no ordering guarantee, which means the outcome can differ between machines and between runs.
• The failure this produces is the worst kind to debug: each test passes when run alone. Running a single test to investigate makes the symptom disappear, which sends people looking for a problem in the runner.
• If you need genuinely expensive shared setup, such as a database container, use IClassFixture and share only things that are read, never written. Anything a test mutates belongs to that test.