Skip to content

Testing

Targets net11.0 csharp-15Last reviewed 2026-11-14 freshSources andrew-lock dotnet-blog house:simon-mckenna mark-seemann meziantou ms-learn

Hold tests to the same review bar and conventions as production code.

House opinion · Simon McKenna

House: Name tests UnitOfWork_Scenario_ExpectedBehaviour, and mark each test's Arrange, Act, and Assert sections with comments. Leave out the marker for a section with no statements of its own. When the only setup is a literal passed to the call, inline it and mark that line // Act. When the call and the check are one expression, such as Assert.Throws, mark it // Act & Assert. A marker over an empty section labels nothing, and a fixed set of markers lets a reviewer or a script check the rule. (HOUSE-OPINIONS.md)

public class BasketTests
{
    [Fact]
    public void Total_MultipleItemsAdded_SumsAllItemPrices()
    {
        // Arrange
        var basket = new Basket();
        basket.Add(10.00m);
        basket.Add(2.50m);

        // Act
        decimal total = basket.Total;

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

    [Fact]
    public void Total_EmptyBasket_IsZero()
    {
        // Act
        decimal total = new Basket().Total;

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

    [Fact]
    public void Add_NegativePrice_ThrowsArgumentOutOfRangeException()
    {
        // Arrange
        var basket = new Basket();

        // Act & Assert
        Assert.Throws<ArgumentOutOfRangeException>(() => basket.Add(-1.00m));
    }
}

Framework and platform

  • Use xUnit v3 on Microsoft.Testing.Platform (MTP) for new test projects, and opt in to the MTP runner in global.json. xunit.v3 includes a native MTP runner, so each test project builds to an executable that dotnet run runs directly, without VSTest's slower process model.

    • dotnet test uses MTP only with the runner opt-in below. Without it, the SDK uses VSTest, and xunit.v3 4.0.0 and later (MTP v2) fails on the .NET 10 SDK and later with Testing with VSTest target is no longer supported.
    • On xunit.v3 3.x, the same mistake runs zero tests and exits with code 0.
    • On the .NET 11 SDK, the DOTNET_TEST_RUNNER environment variable "accepts VSTest or Microsoft.Testing.Platform, without regard to case, and overrides the global.json value". Keep the opt-in in global.json, where every machine reads it, and check for the variable when dotnet test picks VSTest despite the opt-in. (Microsoft Learn: dotnet test)
    {
      "sdk": { "version": "11.0.100", "rollForward": "latestFeature" },
      "test": { "runner": "Microsoft.Testing.Platform" }
    }
    

    Don't use <TestingPlatformDotnetTestSupport> instead. It belongs to "VSTest mode": it makes Microsoft.Testing.Platform.MSBuild redirect the VSTest target to run MTP applications, which MTP v2 no longer supports on the .NET 10 SDK and later. Setting it doesn't select MTP mode, so the error above stays. With the opt-in, remove the property, "as it's no longer required". MSTest and NUnit also run on MTP. (Microsoft Learn: Testing with dotnet test, Microsoft Learn: Microsoft.Testing.Platform overview)

    <Project Sdk="Microsoft.NET.Sdk">
      <PropertyGroup>
        <IsPublishable>false</IsPublishable>
        <OutputType>Exe</OutputType>
        <UseMicrosoftTestingPlatformRunner>true</UseMicrosoftTestingPlatformRunner>
      </PropertyGroup>
      <ItemGroup>
        <PackageReference Include="Microsoft.Testing.Extensions.CodeCoverage" />
        <PackageReference Include="xunit.v3" />
      </ItemGroup>
    </Project>
    
    • The project sets no TargetFramework, Nullable, or IsPackable, because templates/Directory.Build.props sets them for every project. IsPublishable keeps the test host out of a solution-level publish, as ci.md describes.
    • The references have no version, because Central Package Management pins them in templates/Directory.Packages.props. For details, see project-structure.md.
    • There's no Microsoft.NET.Test.Sdk reference. That package is for VSTest, and xunit.v3 needs nothing else to run tests under MTP. Microsoft.Testing.Extensions.CodeCoverage adds the --coverage option that Coverage and the ci.md workflow pass. Without it, MTP rejects --coverage the way it rejects --logger, as described below.
    • Don't pin Microsoft.Testing.Platform. xunit.v3 4.0.0 brings MTP v2, and under Central Package Management your pin overrides its version through transitive pinning. A pin below the version xunit.v3 needs fails restore with NU1109. A pin a major version above it restores and builds, and then every test run throws TypeLoadException.
  • Moving a suite from VSTest to MTP breaks two things the build doesn't catch.

    This is migration guidance. Drop it when VSTest workflows are rare, or re-date it. Review by 2027-11-30.

  • Leaving VSTest saves more time than changing frameworks. Meziantou benchmarked xUnit v3 4.0.0, NUnit 4.6.1, MSTest 4.4.0, and TUnit 1.65.68 on the .NET 10 SDK with up to 10,000 tests. VSTest was 4.9 times slower than the MTP executable for xUnit v3, 5.1 times for MSTest, and 1.5 times for NUnit. He puts that at three to four times the difference between frameworks. Per test, the frameworks range from 15 µs (MSTest) through 42 µs (TUnit) and 56 µs (xUnit v3) to 85 µs (NUnit). The numbers are a reason to keep the global.json opt-in, not to leave xUnit. (Meziantou: Benchmarking .NET test frameworks: xUnit v3, NUnit, MSTest, and TUnit)

  • If the app ships with Native AOT, add a native test run beside the managed suite. Run the managed suite on every change for fast feedback. For the native run, publish one representative C# test project with <PublishAot>true</PublishAot>, and run the executable. Trimming and reflection-free serialization change behaviour that a managed run can't see.

    • In the MSTest post's example, System.Text.Json is what fails, with InvalidOperationException, because reflection-based serialization is off. Fix it with a [JsonSerializable] context in the app, not in the test.
    • The native project references xunit.v3.aot.mtp-v2 instead of xunit.v3. The AOT package replaces the reflection-based one, so it can't share a project with the managed suite.
    • Keep F# test projects in the managed run: "at this time the only language supported for Native AOT is C#".

    (xUnit.net: Testing with Native AOT, .NET Blog: Test what you ship: MSTest and Native AOT, Meziantou: Benchmarking .NET test frameworks: xUnit v3, NUnit, MSTest, and TUnit)

Integration testing

Deterministic time

  • Test time-dependent code through an injected TimeProvider, using FakeTimeProvider from Microsoft.Extensions.TimeProvider.Testing. Never use Thread.Sleep or the real clock. datetime.md covers how to drive it, the large-Advance caveat, the instants to test (DST gaps and overlaps, leap days, and ISO week year boundaries), and the analyzer rules that ban custom clocks.
  • Give each test one clock: construct FakeTimeProvider with an explicit start, and derive every other date from it. A test of an awkward instant has to name that instant. Name it once, as the provider's start.

    • Arrange with time.GetUtcNow(), and move time with Advance.
    • Assert time-derived results against time.Start plus the elapsed time, so the expected value visibly follows from the input.

    Two literals six minutes apart pass today, but the next reviewer has to work out how they relate. A hand-typed expected value repeats the arithmetic the code under test should do. For the two constructor overloads that break this rule, see datetime.md. (Lock: Avoiding flaky tests with TimeProvider and ITimer for Advance and GetUtcNow)

    Before: two unrelated literals, which the reader has to compare.

    public class TokenValidatorTests
    {
        [Fact]
        public void IsExpired_LifetimeElapsed_ReturnsTrue()
        {
            // Arrange
            var token = new Token(issuedAt: new DateTimeOffset(2026, 10, 25, 0, 57, 0, TimeSpan.Zero), lifetime: TimeSpan.FromMinutes(5));
            var validator = new TokenValidator(new FakeTimeProvider(new DateTimeOffset(2026, 10, 25, 1, 3, 0, TimeSpan.Zero)));
    
            // Act
            bool expired = validator.IsExpired(token);
    
            // Assert
            Assert.True(expired);
        }
    }
    

    After: one clock, one chosen start, and the test checks elapsed time. The start is six minutes before the EU fall-back, in a zone that observes it, so the local clock goes from 02:57 CEST back to 02:03 CET while six minutes pass. A validator that compared local clock times would call the token unexpired, and this test catches it.

    public class TokenValidatorTests
    {
        [Fact]
        public void IsExpired_LifetimeElapsedAcrossFallBack_ReturnsTrue()
        {
            // Arrange
            var time = new FakeTimeProvider(new DateTimeOffset(2026, 10, 25, 0, 57, 0, TimeSpan.Zero));
            time.SetLocalTimeZone(TimeZoneInfo.FindSystemTimeZoneById("Europe/Paris"));
            var lifetime = TimeSpan.FromMinutes(5);
            var token = new Token(issuedAt: time.GetUtcNow(), lifetime);
            var validator = new TokenValidator(time);
    
            // Act
            time.Advance(TimeSpan.FromMinutes(6));
    
            // Assert
            Assert.Equal(time.Start.Add(lifetime), token.ExpiresAt);
            Assert.True(validator.IsExpired(token));
        }
    }
    

Output and scale

  • Use snapshot testing for complex serialized output, such as generated code, API payloads, and rendered documents, instead of asserting each field. (Meziantou: Snapshot testing)

    Keep deterministic builds on for a C# test project that uses Meziantou.Framework.SnapshotTesting: it needs no fix. Snapshot libraries locate .verified files from the test's source path, which ContinuousIntegrationBuild and DeterministicSourcePaths rewrite to /_/…. The package handles that itself. Its MSBuild target generates a [ModuleInitializer] that maps each SourceRoot's MappedPath back to the real directory. (Meziantou: Reproducible builds and snapshot testing) The target runs only for C#, so an F# test project that compares snapshots still can't find them in a deterministic build.

  • Measure a slow CI suite, then shard it deterministically across parallel jobs. Sharding helps CPU-bound suites far more than I/O-bound ones. (Meziantou: Test sharding)

Coverage

Seeing tests fail

  • See every test fail on its assertion before you trust it to pass. A test that has never failed might assert a tautology or lock in a bug, and coverage and a green run can't tell it from a working test. Writing the test first isn't enough: a test that failed only because the member didn't exist might pass whatever the member does. After a test passes, break the code under test once per assertion, and see the test fail on that assertion's line. Then revert, and see it pass. (Seemann: Tautological assertion, Seemann: Epistemology of software, Seemann: Empirical Characterization Testing)
  • Review a passing suite as the devil's advocate. Write the simplest wrong implementation that passes every test, then add a test case that catches it. Stop when a wrong implementation takes more work than the correct one. Round trips are the usual gap: two identity functions pass any test that only compares output with input, so assert the intermediate value too. (Seemann: Devil's advocate)

    [Fact]
    public void FahrenheitToCelsius_RoundTrip_ReturnsOriginalReading()
    {
        // Arrange
        double celsius = 37d;
    
        // Act
        double fahrenheit = Temperature.CelsiusToFahrenheit(celsius);
        double roundTripped = Temperature.FahrenheitToCelsius(fahrenheit);
    
        // Assert
        Assert.Equal(98.6d, fahrenheit, 1e-9); // fails if both conversions return their input
        Assert.Equal(celsius, roundTripped, 1e-9);
    }
    

F#

  • Use the same xUnit v3 stack for F# tests. Put [<Fact>] on let-bound functions, with no test class. For the reasoning and an example, see fsharp.md.