Organizing and Selecting Tests

As a test suite grows, you often want to run only part of it: the fast tests on every build, the integration tests at night, or the one test you are working on. NUnit lets you group tests, and then choose which groups to run.

Grouping tests with categories

Put [Category] on a test or a fixture. A test can be in several categories, and it inherits the categories of its fixture.

[Category("Integration")]
public class DatabaseTests
{
    [Test]
    public void Connection_Opens()
    {
        Assert.Pass();
    }

    [Test]
    [Category("Slow")]
    public void Migration_Runs()
    {
        // This test is in both the "Integration" and the "Slow" category.
        Assert.Pass();
    }
}

Running only some categories

With dotnet test, filter on TestCategory:

# Only the integration tests
dotnet test --filter "TestCategory=Integration"

# Everything except the slow tests
dotnet test --filter "TestCategory!=Slow"

With the NUnit console, use --where with the Test Selection Language, which can also select tests by name, class, namespace or property:

nunit3-console MyTests.dll --where "cat == Integration && cat != Slow"

The same expressions work with dotnet test through the NUnit.Where setting, for example dotnet test -- NUnit.Where="cat == Integration". See Configuring with .runsettings for all the settings.

Tests that run only on demand

Mark a test with [Explicit] when it should run only when you select it yourself, for example a test that rebuilds a database. It is skipped when you run all the tests.

Tests that must not run for now

Mark a test with [Ignore] when it can't run at the moment, and give the reason. Ignored tests show up as warnings, so they are not forgotten. With Until, the test starts running again after the given date.

public class MaintenanceTests
{
    [Test]
    [Explicit("Rebuilds the test database, run it on demand")]
    public void RebuildTestDatabase()
    {
        Assert.Pass();
    }

    [Test]
    [Ignore("Waiting for issue #123 to be fixed", Until = "2099-12-31")]
    public void Export_HandlesUnicode()
    {
        Assert.Fail("Not fixed yet");
    }
}
Tip

If a project contains only explicit tests, running the project runs all of them, because the adapter can't tell that apart from selecting them yourself. See Explicit for details.

See also