---
name: csharp-xunit
description: "Use when writing or reviewing .NET tests: xUnit v3 (latest, Microsoft Testing Platform) + NSubstitute only (no FluentAssertions, Moq, NUnit, or MSTest), naming, theories, fixtures, fake time and logging, WebApplicationFactory integration tests, and the Testcontainers → SQLite → test DB → EF InMemory database ladder."
---
# .NET testing: xUnit v3 + NSubstitute
## Policy
- **Framework:** xUnit v3, latest stable; scaffold with `dotnet new xunit3`. Never NUnit or MSTest, and never xUnit v2 (`xunit`) in a new project.
- **Runner:** Microsoft Testing Platform (MTP). From xUnit 4.0 the `xunit.v3` package is `xunit.v3.mtp-v2`; the test project is an executable (`Exe`). On the .NET 10 SDK, opt `dotnet test` into MTP in the root `global.json` — `{ "test": { "runner": "Microsoft.Testing.Platform" } }` — and drop `TestingPlatformDotnetTestSupport` (MTP v2 fails under the VSTest-mode `dotnet test`). Only when VSTest compatibility is required, reference `xunit.v3.mtp-off` + `xunit.runner.visualstudio` + `Microsoft.NET.Test.Sdk` instead.
- **Assertions:** xUnit's `Assert` only. Never FluentAssertions, AwesomeAssertions, or Shouldly.
- **Test doubles:** NSubstitute only, plus `NSubstitute.Analyzers.CSharp` to catch substitutions that silently do nothing. Never Moq or FakeItEasy. For time and logging, use the fakes in `Microsoft.Extensions.TimeProvider.Testing` (`FakeTimeProvider`) and `Microsoft.Extensions.Diagnostics.Testing` (`FakeLogger`, whose `Collector` asserts `[LoggerMessage]` output).
- **Existing suites:** if a project already uses a banned library or xUnit v2, new tests still follow this policy and no banned package is added. Migrate existing tests only when asked.
## Project and naming
- Two test projects per solution under `test/`: `.Unit.Test` and `.Integration.Test`, their folders mirroring the source projects (`Api/`, `Service/`, `Repository/`, …), with `TestInfrastructure/` at each root for fixtures, fakes, builders, and collection definitions; test classes mirror the class under test (`OrderServiceTests`). Layout detail in `dotnet-api-architecture`. Existing per-project suites are migrated only when asked.
- Name tests `MethodName_Scenario_ExpectedBehavior`.
- Arrange-Act-Assert structure, with **no** `// Arrange` / `// Act` / `// Assert` comments — blank lines separate the phases.
- One behavior per test; tests are independent and order-agnostic.
- Test code follows `csharp-standards`: fixtures arrive through a primary constructor (`public sealed class OrderServiceTests(DbFixture fixture) : IClassFixture`), locals use `var`, `TheoryData` rows and expected collections use collection expressions, and private helpers sit in the `Private methods` region.
- Run with `dotnet test`; one test: `dotnet test --project test/.Unit.Test --filter-method "*Scenario*"`.
- Use the latest stable package versions — check NuGet or the repo's `Directory.Packages.props`, never versions from memory.
## xUnit v3
- `[Fact]` for single cases; `[Theory]` with `[InlineData]`, `[MemberData]`, or `TheoryData` for data-driven cases.
- Setup in the constructor; async setup and teardown via `IAsyncLifetime` (`ValueTask InitializeAsync()` / `DisposeAsync()`).
- Share expensive state with `IClassFixture` (one class) or `ICollectionFixture` (several classes); assembly-wide via `[assembly: AssemblyFixture(typeof(T))]`.
- Pass `TestContext.Current.CancellationToken` to async calls so cancelled runs stop promptly.
- Skip dynamically with `Assert.Skip(reason)`; statically with `Skip = "reason"`.
- `Assert.Equal`, `Assert.Equivalent` (structural), `Assert.Same`, `Assert.True`/`False`, `Assert.Contains`/`DoesNotContain`, `Assert.Single`, `Assert.Empty`, `Assert.Throws` / `await Assert.ThrowsAsync(...)`.
- `ITestOutputHelper` (namespace `Xunit`) for diagnostics.
## NSubstitute
- Substitute interfaces (or abstract/virtual members) at the boundary: `var gateway = Substitute.For();`.
- Stub with `.Returns(...)`, match with `Arg.Any()` / `Arg.Is(x => ...)`, verify with `.Received(1)` / `.DidNotReceive()`.
- Async: `.Returns(Task.FromResult(x))` or `.Returns(x)`; throw with `.ThrowsAsync(...)` (`NSubstitute.ExceptionExtensions`).
- Services query the `DbContext` directly (no repository to substitute), so a service test runs on the database ladder below; endpoint and handler tests substitute `IService`.
- Do not substitute what you own and can construct cheaply (value objects, pure services); do not substitute `DbContext`/`DbSet` (use the database ladder), `HttpClient` (use a stub `HttpMessageHandler` or `WebApplicationFactory`), `TimeProvider`, or `ILogger` (use the fakes above).
## Database ladder
Pick the first rung the environment supports; record in the test fixture why a lower rung was used. Fixture setup, transactions, and the retry-strategy caveat: [references/database-ladder.md](references/database-ladder.md).
1. **Testcontainers** — the production engine in Docker (`Testcontainers.MsSql`, `Testcontainers.PostgreSql`, …).
2. **SQLite in-memory** — when Docker is unavailable; provider gaps mean provider-specific behavior still needs rung 1 or 3.
3. **Dedicated physical test database** — a real, disposable instance; connection string from user secrets or an environment variable, never production and never committed.
4. **EF Core InMemory provider** — last resort; not relational (no transactions, constraints, or raw SQL), so only for logic that does not depend on database behavior.
## Integration tests (ASP.NET Core)
- `WebApplicationFactory` (`Microsoft.AspNetCore.Mvc.Testing`; the package name is historical — it hosts Minimal API apps) runs the app in memory; replace external dependencies in `ConfigureTestServices` with NSubstitute substitutes and point data access at the database ladder.
- Assert on status codes and Problem Details bodies (`HttpValidationProblemDetails.Errors` for FluentValidation failures), not on internal state.