Pinning Tests: Making Unfamiliar C# Code Safe to Change

public sealed class DeliveryCalculator
{
    public decimal Calculate(
        decimal subtotal,
        string countryCode,
        bool preferredCustomer)
    {
        decimal charge = 5m;

        if (subtotal > 100m)
        {
            charge = 0m;
        }
        else
        {
            if (countryCode != "IE")
            {
                charge += 7.50m;
            }

            if (preferredCustomer)
            {
                charge /= 2m;
            }
        }

        return decimal.Round(charge, 2);
    }
}

public sealed class DeliveryCalculatorPinningTests
{
    public static TheoryData<decimal, string, bool, decimal> CapturedCases =>
        new()
        {
            { 0m, "IE", false, 5m },
            { 100m, "IE", false, 5m },
            { 100.01m, "IE", false, 0m },
            { 50m, "IE", true, 2.50m },
            { 50m, "GB", false, 12.50m },
            { 50m, "GB", true, 6.25m },
            { 50m, "ie", false, 12.50m },
            { 150m, "GB", false, 0m }
        };

    [Theory]
    [MemberData(nameof(CapturedCases))]
    public void Calculate_preserves_captured_delivery_charges(
        decimal subtotal,
        string countryCode,
        bool preferredCustomer,
        decimal capturedCharge)
    {
        var calculator = new DeliveryCalculator();

        var actual = calculator.Calculate(
            subtotal,
            countryCode,
            preferredCustomer);

        Assert.Equal(capturedCharge, actual);
    }
}

The expected values are fixed observations. The test doesn't reproduce the delivery calculation to work out its own answer.

That would weaken the baseline. If the test repeated the same conditions as the production code, the same mistake could be introduced in both places. If it called the implementation under test to generate its expected value on every run, it would simply compare the code with itself.

Run these tests against the original implementation before changing it. Otherwise, you're capturing the behaviour of the refactor and losing the comparison you wanted.

Refactor with the baseline in place

With the captured cases passing, the implementation can be simplified:

public sealed class DeliveryCalculator
{
    public decimal Calculate(
        decimal subtotal,
        string countryCode,
        bool preferredCustomer)
    {
        if (subtotal > 100m)
        {
            return 0m;
        }

        var charge = countryCode == "IE" ? 5m : 12.50m;

        if (preferredCustomer)
        {
            charge /= 2m;
        }

        return decimal.Round(charge, 2);
    }
}

The structure has changed, while the captured results remain the same. The tests don't care that the nested condition disappeared or that the surcharge became a choice between two amounts.

If I change > to >=, the €100 case fails. If I make the country comparison case-insensitive, the lowercase case fails. Those failures identify observable changes that might otherwise disappear inside a cleanup diff.

Passing these eight cases doesn't prove that every possible input behaves identically. Confidence depends on the cases chosen and the scope of the change. For a larger calculation, I might compare both implementations over a broader, deterministic set of generated inputs as well.

Choose cases around decisions

The most useful inputs tend to sit near branches and boundaries. For a threshold, capture values below it, at it and above it. For interacting conditions, capture combinations that reveal their order.

Here, the overseas order above €100 shows that the free-delivery decision takes precedence over the destination charge. The preferred overseas customer shows that the discount applies after the surcharge.

Historical support cases and unusual production inputs can also provide valuable examples, provided any captured data is sanitised. They often expose behaviour that a handful of ordinary inputs would miss.

Be selective about invalid inputs. If a boundary already rejects negative order totals before this calculator runs, a large collection of negative-value tests may add little protection to the change you're making. If this calculator owns that validation, its handling belongs in the baseline.

Capture effects as well as return values

Many operations do more than return a number. A handler might update a record, publish a message and then acknowledge the input. A report generator might return a file whose column order is consumed by another system.

The baseline needs to include the observable effects relevant to the change. A matching return value won't reveal that an outgoing message lost a field or a database update stopped happening.

Choose assertions at the boundary where the effect can be observed. That might mean reading the resulting database state in an integration test, examining messages collected by a test publisher, or checking the generated file.

Avoid pinning every internal method call merely because a mocking framework makes it easy. You want enough freedom to restructure the code while preserving its externally relevant behaviour.

Larger outputs need a reviewable baseline

For a sizeable JSON response or generated document, individual assertions can become cumbersome. A reviewed snapshot or checked-in expected file can capture more of the output with less test code.

Keep that baseline small enough to inspect. A huge snapshot that gets approved without being read provides weak protection, even if the test technically compares every byte.

Variable values need attention too. Use fixed clocks and deterministic identifiers where possible. Normalise fields only when their exact values are outside the behaviour being protected, and keep meaningful relationships intact. Removing every timestamp, for example, could hide a broken expiry calculation.

Also consider ordering. Sorting a collection before comparison is appropriate only when its order has no contractual significance. Otherwise, the normalisation removes evidence of a change consumers may notice.

A surprising result deserves investigation

Suppose the lowercase country code behaviour turns out to be a bug. The pinning test has helped uncover it; preserving it temporarily doesn't make it an approved requirement.

I would keep the refactor focused, then change the comparison deliberately with a test expressing the agreed behaviour. Update the old expectation as part of that fix and explain why it changed.

That separation makes review easier. A reviewer can assess whether the refactor preserves behaviour, then assess whether the proposed behaviour change is correct.

An urgent defect may need fixing immediately. The same principle still applies: identify the intentional difference, test it explicitly and retain the useful surrounding baseline. Don't blindly preserve a known defect just to keep a characterisation test green.

Keep the tests that remain useful

Pinning tests often start as preparation for one change, but the strongest cases can become lasting regression tests. Boundary values, historical failures and externally consumed output formats usually remain worth protecting.

As the code becomes better understood, give those tests names that explain the behaviour. Record uncertain quirks clearly so a future developer doesn't mistake an observed result for a confirmed business rule.

I don't need to understand every historical decision before making unfamiliar code easier to maintain. I do need evidence about the behaviour I'm changing. Pinning tests let me gather that evidence before the first refactor, while the original implementation is still there to tell me what it does.

• xUnit theory data attributes
• .NET decimal.Round documentation