C# xUnit testing
Guide C# test design by turning a class, behavior, or test request into focused xUnit tests that use idiomatic setup, data sources, assertions, isolation, and dotnet test validation.
When to invoke
- "Write xUnit tests for this C# class."
- "Show xunit best practices for data-driven tests."
- "Convert these cases into
[Theory] and [InlineData]."
- "How should I organize fixtures in xUnit?"
Project setup
| Concern |
Rule |
| Test project |
Use a separate [ProjectName].Tests project. |
| Packages |
Reference Microsoft.NET.Test.Sdk, xunit, and xunit.runner.visualstudio. |
| Test class names |
Match the class under test, for example CalculatorTests for Calculator. |
| Command |
Run tests with dotnet test; narrow with --filter for targeted validation. |
| Visibility |
Prefer testing public behavior; use InternalsVisibleTo only when the project already exposes internals for tests. |
Test structure
| Pattern |
Use it for |
Notes |
[Fact] |
One fact-based scenario with no external data rows. |
No class-level test attribute is required in xUnit, unlike MSTest/NUnit. |
[Theory] |
Same behavior over multiple inputs. |
Pair with one data source attribute. |
| Arrange-Act-Assert |
Every test body. |
Keep setup, action, and assertions visually separable. |
MethodName_Scenario_ExpectedBehavior |
Test method naming. |
Example: Divide_ByZero_ThrowsDivideByZeroException. |
| Constructor |
Per-test setup. |
xUnit creates a new test class instance for each test. |
IDisposable.Dispose() |
Per-test teardown. |
Release files, handles, or mocks that require cleanup. |
IAsyncLifetime |
Async setup or teardown. |
Use InitializeAsync and DisposeAsync instead of blocking on tasks. |
Data-driven tests
| Source |
Best use |
Example shape |
[InlineData] |
Small scalar cases that fit on one line. |
[InlineData(2, 3, 5)] |
[MemberData] |
Generated, named, reusable, or method-based test data. |
Static property or method returning IEnumerable<object[]>. |
[ClassData] |
Larger reusable or class-based datasets. |
Class implements IEnumerable<object[]>. |
Custom DataAttribute |
Dynamic or domain-specific data creation. |
Keep deterministic; avoid network calls and current time. |
Use meaningful parameter names. Keep the assertion intent identical across all rows; split into separate theories when rows prove different behaviors.
Assertions and exceptions
| Need |
Assertion |
| Value equality |
Assert.Equal(expected, actual); baseline form Assert.Equal. |
| Reference identity |
Assert.Same(expected, actual); baseline form Assert.Same. |
| Boolean |
Assert.True(condition) or Assert.False(condition) with a clear message when helpful; baseline forms Assert.True and Assert.False. |
| Collections |
Assert.Contains, Assert.DoesNotContain, Assert.Collection, or Assert.All. |
| Regex |
Assert.Matches or Assert.DoesNotMatch. |
| Exceptions |
Assert.Throws<T> or await Assert.ThrowsAsync<T>. |
| Readability |
Use a fluent assertions library only if the project already uses one or accepts the dependency. |
Fixtures, mocking, and organization
| Technique |
Use when |
Avoid |
IClassFixture<T> |
Expensive context shared by tests in one class. |
Storing mutable state that leaks between tests. |
ICollectionFixture<T> |
Shared context across multiple test classes. |
Using it as a global singleton for unrelated tests. |
| Moq or NSubstitute |
Isolate dependencies behind interfaces. |
Mocking the class under test or framework primitives unnecessarily. |
| DI container |
Complex object graphs already use dependency injection. |
Rebuilding the production container when a direct constructor call is clearer. |
[Trait("Category", "CategoryName")] |
Filtering smoke, integration, or slow tests. |
Encoding ordering dependencies as categories. |
ITestOutputHelper |
Diagnostics that should appear only on failure or in test output. |
Replacing assertions with log inspection. |
Skip = "reason" |
Temporarily disabled tests with a specific reason in fact/theory attributes. |
Silent or permanent skips. |
Gotchas
- xUnit creates a new test class instance per test: constructor state is not shared; use fixtures for intentional sharing.
- Do not depend on test order: tests must be independent and idempotent even when run in parallel.
- Avoid broad assertions: one focused behavior with the minimum useful assertions is easier to diagnose than a scenario that checks everything.
- Keep data rows readable: complex object graphs in
[InlineData] usually belong in [MemberData] or builders.
Output template
## xUnit test plan
**Target:** `<class or behavior>`
**Command:** `dotnet test <project-or-solution> --filter <optional-filter>`
| Test | Attribute | Data source | Behavior verified |
| --- | --- | --- | --- |
| `<MethodName_Scenario_ExpectedBehavior>` | `[Fact]` or `[Theory]` | `<none / InlineData / MemberData / ClassData>` | `<single behavior>` |
### Notes
- Fixtures: `<IClassFixture<T> / ICollectionFixture<T> / none>`
- Assertions: `<key Assert.* calls>`
- Isolation: `<mocks, fakes, or real collaborators>`
Quality gate
1---2name: csharp-xunit-23description: Apply xUnit best practices for C# unit tests, including test project setup, Fact and Theory structure, data-driven tests, assertions, fixtures, mocking, categorization, diagnostics, and dotnet test execution. Use when asked for xUnit guidance or to write .NET unit tests.4---56# C# xUnit testing78Guide C# test design by turning a class, behavior, or test request into focused xUnit tests that use idiomatic setup, data sources, assertions, isolation, and `dotnet test` validation.910## When to invoke1112- "Write xUnit tests for this C# class."13- "Show xunit best practices for data-driven tests."14- "Convert these cases into `[Theory]` and `[InlineData]`."15- "How should I organize fixtures in xUnit?"1617## Project setup1819| Concern | Rule |20| --- | --- |21| Test project | Use a separate `[ProjectName].Tests` project. |22| Packages | Reference `Microsoft.NET.Test.Sdk`, `xunit`, and `xunit.runner.visualstudio`. |23| Test class names | Match the class under test, for example `CalculatorTests` for `Calculator`. |24| Command | Run tests with `dotnet test`; narrow with `--filter` for targeted validation. |25| Visibility | Prefer testing public behavior; use `InternalsVisibleTo` only when the project already exposes internals for tests. |2627## Test structure2829| Pattern | Use it for | Notes |30| --- | --- | --- |31| `[Fact]` | One fact-based scenario with no external data rows. | No class-level test attribute is required in xUnit, unlike `MSTest/NUnit`. |32| `[Theory]` | Same behavior over multiple inputs. | Pair with one data source attribute. |33| Arrange-Act-Assert | Every test body. | Keep setup, action, and assertions visually separable. |34| `MethodName_Scenario_ExpectedBehavior` | Test method naming. | Example: `Divide_ByZero_ThrowsDivideByZeroException`. |35| Constructor | Per-test setup. | xUnit creates a new test class instance for each test. |36| `IDisposable.Dispose()` | Per-test teardown. | Release files, handles, or mocks that require cleanup. |37| `IAsyncLifetime` | Async setup or teardown. | Use `InitializeAsync` and `DisposeAsync` instead of blocking on tasks. |3839## Data-driven tests4041| Source | Best use | Example shape |42| --- | --- | --- |43| `[InlineData]` | Small scalar cases that fit on one line. | `[InlineData(2, 3, 5)]` |44| `[MemberData]` | Generated, named, reusable, or method-based test data. | Static property or method returning `IEnumerable<object[]>`. |45| `[ClassData]` | Larger reusable or class-based datasets. | Class implements `IEnumerable<object[]>`. |46| Custom `DataAttribute` | Dynamic or domain-specific data creation. | Keep deterministic; avoid network calls and current time. |4748Use meaningful parameter names. Keep the assertion intent identical across all rows; split into separate theories when rows prove different behaviors.4950## Assertions and exceptions5152| Need | Assertion |53| --- | --- |54| Value equality | `Assert.Equal(expected, actual)`; baseline form `Assert.Equal`. |55| Reference identity | `Assert.Same(expected, actual)`; baseline form `Assert.Same`. |56| Boolean | `Assert.True(condition)` or `Assert.False(condition)` with a clear message when helpful; baseline forms `Assert.True` and `Assert.False`. |57| Collections | `Assert.Contains`, `Assert.DoesNotContain`, `Assert.Collection`, or `Assert.All`. |58| Regex | `Assert.Matches` or `Assert.DoesNotMatch`. |59| Exceptions | `Assert.Throws<T>` or `await Assert.ThrowsAsync<T>`. |60| Readability | Use a fluent assertions library only if the project already uses one or accepts the dependency. |6162## Fixtures, mocking, and organization6364| Technique | Use when | Avoid |65| --- | --- | --- |66| `IClassFixture<T>` | Expensive context shared by tests in one class. | Storing mutable state that leaks between tests. |67| `ICollectionFixture<T>` | Shared context across multiple test classes. | Using it as a global singleton for unrelated tests. |68| Moq or NSubstitute | Isolate dependencies behind interfaces. | Mocking the class under test or framework primitives unnecessarily. |69| DI container | Complex object graphs already use dependency injection. | Rebuilding the production container when a direct constructor call is clearer. |70| `[Trait("Category", "CategoryName")]` | Filtering smoke, integration, or slow tests. | Encoding ordering dependencies as categories. |71| `ITestOutputHelper` | Diagnostics that should appear only on failure or in test output. | Replacing assertions with log inspection. |72| `Skip = "reason"` | Temporarily disabled tests with a specific reason in fact/theory attributes. | Silent or permanent skips. |7374## Gotchas7576- **xUnit creates a new test class instance per test**: constructor state is not shared; use fixtures for intentional sharing.77- **Do not depend on test order**: tests must be independent and idempotent even when run in parallel.78- **Avoid broad assertions**: one focused behavior with the minimum useful assertions is easier to diagnose than a scenario that checks everything.79- **Keep data rows readable**: complex object graphs in `[InlineData]` usually belong in `[MemberData]` or builders.8081## Output template8283```markdown84## xUnit test plan8586**Target:** `<class or behavior>`87**Command:** `dotnet test <project-or-solution> --filter <optional-filter>`8889| Test | Attribute | Data source | Behavior verified |90| --- | --- | --- | --- |91| `<MethodName_Scenario_ExpectedBehavior>` | `[Fact]` or `[Theory]` | `<none / InlineData / MemberData / ClassData>` | `<single behavior>` |9293### Notes94- Fixtures: `<IClassFixture<T> / ICollectionFixture<T> / none>`95- Assertions: `<key Assert.* calls>`96- Isolation: `<mocks, fakes, or real collaborators>`97```9899## Quality gate100101- [ ] Tests use `[Fact]` for single cases and `[Theory]` with data attributes for data-driven cases.102- [ ] Each test follows Arrange-Act-Assert and verifies one behavior.103- [ ] Names follow `MethodName_Scenario_ExpectedBehavior` or the project's established equivalent.104- [ ] Shared setup uses constructor, `IDisposable.Dispose()`, `IClassFixture<T>`, or `ICollectionFixture<T>` appropriately.105- [ ] Assertions use the most specific `Assert.*` API and cover exception paths with `Assert.Throws<T>` or `Assert.ThrowsAsync<T>`.106- [ ] Tests are independent, idempotent, and runnable with `dotnet test`.
paulasilvatech