Testing
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
var total = basket.Total;
// Assert
Assert.Equal(12.50m, total);
}
[Fact]
public void Total_EmptyBasket_IsZero()
{
// Act
var 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 thatdotnet runruns directly, without VSTest's slower process model.dotnet testuses MTP only with the runner opt-in below. Without it, the SDK uses VSTest, and xunit.v3 4.0.0 (MTP v2) fails on .NET 10 withTesting with VSTest target is no longer supported.- On xunit.v3 3.x, the same mistake runs zero tests and exits with code 0.
{ "sdk": { "version": "10.0.400", "rollForward": "latestFeature" }, "test": { "runner": "Microsoft.Testing.Platform" } }Don't use
<TestingPlatformDotnetTestSupport>instead. It's the VSTest bridge, and it causes the error above under MTP v2. MSTest and NUnit also run on MTP. xUnit is the default because it constructs a new class instance for each test and has the largest ecosystem. TUnit is too new to have a track record. (Microsoft Learn: Microsoft.Testing.Platform overview, Microsoft Learn: What's new in .NET 10: SDK)<Project Sdk="Microsoft.NET.Sdk"> <PropertyGroup> <TargetFramework>net10.0</TargetFramework> <Nullable>enable</Nullable> <OutputType>Exe</OutputType> <UseMicrosoftTestingPlatformRunner>true</UseMicrosoftTestingPlatformRunner> </PropertyGroup> <ItemGroup> <PackageReference Include="xunit.v3" /> </ItemGroup> </Project>- The reference has no version, because Central Package Management pins it in templates/Directory.Packages.props. For details, see project-structure.md.
- There's no
Microsoft.NET.Test.Sdkreference. That package is for VSTest, andxunit.v3needs nothing else under MTP. - Don't pin
Microsoft.Testing.Platform. xunit.v3 4.0.0 brings MTP v2. Under Central Package Management, your pin overrides it through transitive pinning and throwsTypeLoadExceptionat run time.
-
Moving a suite from VSTest to MTP breaks two things the build doesn't catch. Review by 2027-11-30. This is migration guidance. Drop it when VSTest workflows are rare, or re-date it.
--loggerisn't an MTP option. VSTest's--logger "console;verbosity=normal"or--logger trxmakes the test application exit with code 5 (invalid command-line arguments) before any test runs. Every CI line that passes it fails as soon asglobal.jsonopts in. Each MTP reporter registers its own option. Use--output Detailedfor console verbosity, and--report-xunit-trx, which is built into xunit.v3, for TRX.--report-trx, from Microsoft's migration guide, needs theMicrosoft.Testing.Extensions.TrxReportpackage and fails the same way without it. (Microsoft Learn: Migration guide from VSTest to Microsoft.Testing.Platform, Microsoft Learn: Microsoft.Testing.Platform exit codes, xUnit.net: Microsoft Testing Platform)- A multi-targeted test project runs its target frameworks concurrently. Each target framework builds its own executable, and MTP runs test modules in parallel, up to
Environment.ProcessorCount. VSTest ran them in sequence. A fixture with a fixed temporary directory, port, file, or database name now races the other framework's process, and one run'sDisposedeletes a directory the other is writing to. Make that state unique per instance, for example withGuid.NewGuid()in the name.--max-parallel-test-modules 1hides the race and gives up MTP's speed. (Microsoft Learn: dotnet test command with Microsoft.Testing.Platform)
-
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.jsonopt-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.System.Text.Jsonusually fails first, withInvalidOperationException, 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-v2instead ofxunit.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. NUnit doesn't support Native AOT.
(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
- Integration-test ASP.NET Core apps with
WebApplicationFactory<TEntryPoint>instead of unit-testing controllers or handlers.Microsoft.AspNetCore.Mvc.Testingruns the real app in memory, with routing, model binding, filters, DI, and middleware. A few factory tests catch the routing, binding, and registration bugs that controller unit tests miss. Unit-test the domain logic the endpoints call, not the endpoints. (Microsoft Learn: Integration tests in ASP.NET Core, Lock: Should you unit-test API/MVC controllers?) - Replace services for a test with
ConfigureTestServices, scoped byWithWebHostBuilder. (Microsoft Learn: Integration tests in ASP.NET Core)
Deterministic time
- Test time-dependent code through an injected
TimeProvider, usingFakeTimeProviderfromMicrosoft.Extensions.TimeProvider.Testing. Never useThread.Sleepor the real clock. datetime.md covers how to drive it, the large-Advancecaveat, 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
FakeTimeProviderwith 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 withAdvance. - Assert time-derived results against
time.Startplus 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
AdvanceandGetUtcNow)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 var 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)); } } - Arrange with
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)
Snapshot libraries locate
.verifiedfiles from the test's source path, which deterministic builds rewrite to/_/…. WithContinuousIntegrationBuildorDeterministicSourcePathson, the project can't find its snapshots. Keep determinism, and restore the mapping at startup: an MSBuild target can generate a[ModuleInitializer]that maps eachSourceRoot'sMappedPathback to the real directory. (Meziantou: Reproducible builds and snapshot testing) -
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
- Collect line coverage on every CI run, and use it to find untested code, not to measure quality. Coverage shows which lines ran, not whether a test checked them. (Microsoft Learn: Use code coverage for unit testing, Meziantou: Is the code coverage a sufficient metric?)
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 var celsius = 37d; // Act var fahrenheit = Temperature.CelsiusToFahrenheit(celsius); var 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>]onlet-bound functions, with no test class. For the reasoning and an example, see fsharp.md.