csharp-nunit

NUnit Best Practices

Your goal is to help me write effective unit tests with NUnit, 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, NUnit, and NUnit3TestAdapter packages
• Pin explicit package versions (preferably managed centrally), commit a package lock file and use locked restore in CI, restore only from the trusted official package feed, and verify exact package names before adding them
• Create test classes that match the classes being tested (e.g., CalculatorTests for Calculator)
• Use .NET SDK test commands: dotnet test for running tests, passing the specific [ProjectName].Tests project rather than the whole solution
• dotnet test restores packages, runs build steps, and executes setup code with your privileges; run it only in trusted repositories or after reviewing project files, build property files, and setup code, preferably in an isolated environment that holds no secrets

Test Structure

• Apply [TestFixture] attribute to test classes
• Use [Test] attribute for test methods
• Follow the Arrange-Act-Assert (AAA) pattern
• Name tests using the pattern MethodName_Scenario_ExpectedBehavior
• Use [SetUp] and [TearDown] for per-test setup and teardown
• Use [OneTimeSetUp] and [OneTimeTearDown] for per-class setup and teardown
• Use [SetUpFixture] for assembly-level setup and teardown, keeping setup code limited to resources local to the tests

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 [TestCase] for inline test data
• Use [TestCaseSource] for programmatically generated test data
• Use [Values] for simple parameter combinations
• Use [ValueSource] for property or method-based data sources
• Use [Random] for random numeric test values only with a fixed or logged seed so failures can be reproduced; otherwise prefer [Range] or [TestCase] to keep tests idempotent
• Use [Range] for sequential numeric test values
• Use [Combinatorial] or [Pairwise] for combining multiple parameters

Assertions

• Use Assert.That with constraint model (preferred NUnit style)
• Use constraints like Is.EqualTo, Is.SameAs, Contains.Item
• Prefer Assert.That with constraints for value, collection and string checks; this guidance targets current NUnit releases
• Assert.AreEqual (classic style), CollectionAssert, and StringAssert moved to a separate legacy namespace in newer NUnit major versions and will not compile unless it is imported; use them only when maintaining older test code
• Use Assert.Throws<T> or Assert.ThrowsAsync<T> to test exceptions
• Use descriptive messages in assertions for clarity on failure
• Use synthetic values in assertion messages, test descriptions, and test data, keeping secrets, connection strings, tokens, and production data out of them

Mocking and Isolation

• Consider using Moq or NSubstitute alongside NUnit
• Use reviewed, pinned versions of mocking and DI libraries from the trusted official package feed, and read release notes before upgrading, since past releases of popular mocking libraries have added unexpected data collection
• Mock dependencies to isolate units under test
• Use interfaces to facilitate mocking
• Consider using a DI container for complex test setups, preferring simple handwritten fakes or the standard built-in container over extra unvetted packages

Test Organization

• Group tests by feature or component
• Use categories with [Category("CategoryName")]
• Use [Order] only as a last resort when sequencing is unavoidable; unit tests must stay independent of execution order
• Use [Author("DeveloperName")] to indicate ownership
• Use [Description] to provide additional test information
• Consider [Explicit] for tests that shouldn't run automatically; make sure explicit and ignored tests are reported in CI, and keep security tests in the regular run
• Use [Ignore("Reason")] to temporarily skip tests, giving a reason that references a tracking issue and an end date