DOCSEARCHbyAlgolia
Submit Docs

NUnit Framework Documentation

repository·main·Indexed 25 days ago

https://github.com/nunit/nunit

A comprehensive cross-platform unit-testing framework for all .NET languages, supporting TDD, system, and integration testing on Windows, macOS, and Linux. The documentation covers installation via NuGet and MyGet, migration paths from NUnit 3 and 4 to NUnit 5, and details on core projects including the Test Framework, Visual Studio Adapter, Analyzers, and Console/Engine. It also provides guidance on building from source using .NET 10.0 SDK and instructions for using classic assertion extension methods via the nunit.framework.legacy package.

Tokens
2.2K
Snippets
1
Records
14
Agent score
83%

What's inside NUnit

  1. Overview of NUnit Projects

    main

    NUnit consists of several specialized projects depending on your testing needs:

    Core Projects

    • NUnit Test Framework: The primary framework used to write NUnit tests.
    • NUnit Visual Studio Adapter: Enables running NUnit 3+ tests in Visual Studio or via the dotnet command line.
    • NUnit Analyzers: Roslyn analyzers for code analysis and refactoring support in IDEs.
    • NUnit Console and Engine: Provides a command-line runner and the engine used by other test runners.

    Visual Studio Extensions

    • Visual Studio Test Generator: Generates NUnit tests within Visual Studio.
    • NUnit 2 Visual Studio Adapter: For running legacy NUnit 2.x tests.

    Engine Extensions

    • NUnit 2 Driver: Allows the NUnit 3 engine to run NUnit 2 tests.
    • NUnit 2 Result Writer: Writes results in the legacy NUnit 2 format.

  2. Build NUnit Framework using build scripts

    main

    NUnit provides build scripts for different environments: build.cmd (Windows CMD), build.ps1 (Windows PowerShell), and build.sh (Linux/macOS). These scripts support the following arguments:

    • --target={task}: Specifies the task to run.
    • --configuration=[Release|Debug]: Sets the build configuration (defaults to Release).
    • --showdescription: Displays all available build tasks and their descriptions.

    Available Build Tasks

    TaskCommandDescription
    Restorebuild --target restoreRestores all dependencies
    BuildbuildBuilds everything (includes restore); this is the default
    Rebuildbuild --target RebuildCleans output directories and builds everything
    Testbuild --target TestRuns all tests (requires Build to have run)
    Packagebuild --target PackageCreates all packages (does not perform a build)

    Note: The Package target does not depend on Build. Ensure your binaries are up to date before running the package target.

  3. Install the NUnit Framework

    main

    The NUnit Framework can be installed via NuGet for stable projects or via MyGet for pre-release builds.

    • Stable releases: Available on NuGet.
    • Pre-release builds: Available on MyGet.

  4. Prepare for building NUnit Framework

    main

    Before building, ensure you have the following prerequisites installed:

    • .NET SDK: .NET 10.0 SDK or newer on all platforms.
    • Mono: Required for macOS or Linux. Mono version 6.12.0 Stable (6.12.0.206) is validated for GNU/Linux Debian 10 'buster'.
    • IDE: You can use Visual Studio 2026+, Visual Studio for Mac, JetBrains Rider, or VS Code (though VS Code users should use the build scripts instead of the IDE build features).

    The NUnit solution is contained in nunit.slnx at the repository root. Binary files are output to the bin directory of each C# project.

  5. Run NUnit tests with different output verbosity

    main

    You can run tests using the NUnit build scripts or directly via the dotnet test CLI. Use the following options to control output verbosity:

    Using NUnit Build Scripts

    • build --target=Test: Normal output.
    • build --target=Test --minimal=true: Minimal output (summaries only).

    Using dotnet CLI

    • dotnet test: Standard test execution.
    • dotnet test -v m: Minimal MSBuild output.
    • dotnet test -l "console;verbosity=detailed": Detailed test output.
    • dotnet test --settings quiet.runsettings: Reduced NUnit output.

    The Test target in the build script provides a summary of total tests, passed, failed, and skipped counts across all frameworks. Using --quiet=true shows only per-assembly summaries without individual test names.

  6. Use Classic Assert extension methods

    main

    The nunit.framework.legacy package provides extension methods that allow you to use classic assertion syntax directly on the Assert class. This provides a 1:1 mapping to the original ClassicAssert methods while maintaining type safety.

    Requirements:

    • C# Version: C# 14 or later
    • Package: nunit.framework.legacy
    • Namespace: Add using NUnit.Framework; to your file.

    Key Design Rules:

    • No Optional Parameters: Instead of optional parameters, separate overloads are used to match the original ClassicAssert behavior.
    • Naming Conflicts: To avoid conflicts (e.g., between string and collection operations), specific prefixes are used, such as Assert.StringContains instead of a generic Contains.
    // Before (Classic Assert style)
ClassicAssert.AreEqual(expected, actual);
ClassicAssert.IsTrue(condition, "Custom message", arg1, arg2);
StringAssert.Contains("substring", str);

// After (Extension Method style)
Assert.AreEqual(expected, actual);
Assert.IsTrue(condition, "Custom message", arg1, arg2);
Assert.StringContains("substring", str);

  9. Reference Numeric Assertions

    main

    The following numeric assertions are available for types including int, uint, long, ulong, decimal, double, and float via Assert:

    • Assert.Zero(T): Asserts that the value is zero.
    • Assert.NotZero(T): Asserts that the value is not zero.
    • Assert.Positive(T): Asserts that the value is positive.
    • Assert.Negative(T): Asserts that the value is negative.

    Each method supports an optional error message: Assert.Zero(value, "message", params).

  11. Reference Type Assertions

    main

    Use these methods to assert type compatibility and instance types via Assert:

    Assignment Compatibility

    • Assert.IsAssignableFrom(Type, object)
    • Assert.IsAssignableFrom<T>(object)
    • Assert.IsNotAssignableFrom(Type, object)
    • Assert.IsNotAssignableFrom<T>(object)

    Instance Checks

    • Assert.IsInstanceOf(Type, object)
    • Assert.IsInstanceOf<T>(object)
    • Assert.IsNotInstanceOf(Type, object)
    • Assert.IsNotInstanceOf<T>(object)

    All methods support optional error messages via the (..., string message, object[] parameters) overload.