How to filter NUnit tests by category using "dotnet test"

2 min read 06-10-2024

How to filter NUnit tests by category using "dotnet test"

Filtering NUnit Tests by Category with "dotnet test"

Running all tests in your project can be time-consuming and unnecessary when you only need to focus on a specific set of tests. NUnit, a popular unit testing framework for .NET, provides the ability to categorize tests, allowing you to easily filter and run only the tests that are relevant to your current task.

This article explains how to filter NUnit tests by category using the "dotnet test" command line tool.

The Scenario

Let's imagine you have a project with several NUnit tests, and you want to run only the tests related to a specific feature, say "Authentication."

Here's an example of how you might structure your tests using the [Category] attribute in NUnit:

using NUnit.Framework;

namespace MyProject.Tests
{
    public class AuthenticationTests
    {
        [Test, Category("Authentication")]
        public void ShouldLoginSuccessfully()
        {
            // Test logic here
        }

        [Test, Category("Authentication")]
        public void ShouldHandleInvalidCredentials()
        {
            // Test logic here
        }
    }

    public class OtherFeatureTests
    {
        [Test, Category("Data")]
        public void ShouldSaveDataSuccessfully()
        {
            // Test logic here
        }
    }
}

Filtering with "dotnet test"

To run only the tests in the "Authentication" category, you can use the --filter option with "dotnet test":

dotnet test --filter "Category=Authentication"

This command will execute all tests marked with the "Authentication" category.

Beyond Simple Filtering

You can further customize your filtering with the following options:

Multiple Categories: You can filter tests by multiple categories using a comma-separated list:
```
dotnet test --filter "Category=Authentication,Data"
```
Excluding Categories: To exclude a specific category, use the ! character:
```
dotnet test --filter "Category!=Data"
```
Combining Filters: You can combine different filtering criteria using parentheses and logical operators like && and ||. For example:
```
dotnet test --filter "Category=Authentication && TestName=ShouldLoginSuccessfully" 
```

Advantages of Using Categories

Efficient Test Execution: Focus on relevant tests, saving time and resources.
Organized Test Suites: Categorizing tests helps maintain organization and understand the structure of your tests.
Targeted Debugging: Isolate and diagnose problems more effectively by running specific sets of tests.

Conclusion

Filtering NUnit tests by category with "dotnet test" is a powerful technique for improving your testing workflow. This flexibility allows you to run tests selectively, improving efficiency and helping you focus on the most critical areas of your codebase.

Remember, proper test categorization is a crucial element for maintaining well-structured and manageable test suites.

Resources

NUnit Documentation: Comprehensive documentation on NUnit features, including category-based filtering.
dotnet test Documentation: Documentation on the "dotnet test" command line tool.