# Csharp Xunit

> Get best practices for XUnit unit testing, including data-driven tests

- Skill: `markheydon/csharp-xunit-2` (Agent Skill)
- Install (CLI): `npx get-skill add markheydon/csharp-xunit-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/markheydon/csharp-xunit-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: markheydon (https://skillmd.com/u/markheydon)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/markheydon/csharp-xunit-2

---


# XUnit Best Practices

Your goal is to help me write effective unit tests with XUnit, covering both standard and data-driven testing approaches.

## Project Setup

- Use a separate test project with naming convention `[ProjectName].Tests`
- Reference `Microsoft.NET.Test.Sdk`, `xunit.v3`, and `xunit.runner.visualstudio` packages
- Add `NSubstitute` for mocks, stubs, and test doubles
- Create test classes that match the classes being tested (e.g., `CalculatorTests` for `Calculator`)
- Use .NET SDK test commands: `dotnet test` for running tests
- Test projects inherit `TreatWarningsAsErrors`; compile test code without warning suppressions

## Test Structure

- No test class attributes required
- Use fact-based tests with `[Fact]` attribute for simple tests
- Follow the Arrange-Act-Assert (AAA) pattern
- Name tests using the pattern `MethodName_Scenario_ExpectedBehavior`
- Use constructor for setup and `IDisposable.Dispose()` for teardown
- Use `IClassFixture<T>` for shared context between tests in a class
- Use `ICollectionFixture<T>` for shared context between multiple test classes

## Standard Tests

- Keep tests focused on a single behavior
- Avoid testing multiple behaviors in one test method
- Use clear assertions that express intent
- Include only the assertions needed to verify the test case
- Make tests independent and idempotent (can run in any order)
- Avoid test interdependencies

## Data-Driven Tests

- Use `[Theory]` combined with data source attributes
- Use `[InlineData]` for inline test data
- Use `[MemberData]` for method-based test data
- Use `[ClassData]` for class-based test data
- Create custom data attributes by implementing `DataAttribute`
- Use meaningful parameter names in data-driven tests

## Assertions

- Use built-in xUnit `Assert` methods only
- Use `Assert.Equal` for value equality
- Use `Assert.Same` for reference equality
- Use `Assert.True`/`Assert.False` for boolean conditions
- Use `Assert.Contains`/`Assert.DoesNotContain` for collections
- Use `Assert.Matches`/`Assert.DoesNotMatch` for regex pattern matching
- Use `Assert.Throws<T>` or `await Assert.ThrowsAsync<T>` to test exceptions

Do not introduce FluentAssertions, AwesomeAssertions, Shouldly, or other assertion libraries.

## Mocking and Isolation

- Use **NSubstitute** for mocks, stubs, and test doubles
- Prefer handwritten stateful doubles when they model real behaviour (for example,
  in-memory stores or adapter subclasses)
- Mock dependencies to isolate units under test
- Use interfaces to facilitate mocking
- Consider using a DI container for complex test setups

Do not introduce Moq, NUnit, MSTest, or AppHost testing harnesses.

## Test Organization

- Group tests by feature or component
- Use `[Trait("Category", "CategoryName")]` for categorization
- Use collection fixtures to group tests with shared dependencies
- Consider output helpers (`ITestOutputHelper`) for test diagnostics
- Skip tests conditionally with `Skip = "reason"` in fact/theory attributes

## End-to-end testing

- Use Playwright only when a complete user journey explicitly requires end-to-end
  coverage
- Do not use Playwright as a replacement for unit tests
- AppHost modelling and orchestration are not tested in this repository

