dotnet test --filter: run a single test or a category in .NET

dotnet test --filter "FullyQualifiedName~Adds" builds the test project and runs only the tests whose fully qualified name (Namespace.Class.Method) contains Adds. Filters are expressions of property operator value: = (equals), !=, ~ (contains) and !~, combined with | (or) and & (and). Use a category or trait (Category=Slow) to run a group of tests, and --list-tests to see the names you can filter on.

Run one test and one category

dotnet new xunit -o Calc.Tests > /dev/null
cat > Calc.Tests/UnitTest1.cs <<'EOF'
namespace Calc.Tests;

public class MathTests
{
    [Fact]
    public void Adds() => Assert.Equal(4, 2 + 2);

    [Fact]
    public void Subtracts() => Assert.Equal(1, 3 - 2);

    [Fact]
    [Trait("Category", "Slow")]
    public void SlowCheck() => Assert.True(true);
}
EOF
cd Calc.Tests
dotnet build -v q --nologo > /dev/null
dotnet test --no-build --filter "FullyQualifiedName~Adds" | grep -E "^(Passed!|Failed!)" | sed -E 's/, Duration: .*//'
dotnet test --no-build --filter "Category=Slow" | grep -E "^(Passed!|Failed!)" | sed -E 's/, Duration: .*//'
dotnet test --no-build --list-tests | grep -E "^    Calc"

Passed!  - Failed:     0, Passed:     1, Skipped:     0, Total:     1
Passed!  - Failed:     0, Passed:     1, Skipped:     0, Total:     1
    Calc.Tests.MathTests.Adds
    Calc.Tests.MathTests.Subtracts
    Calc.Tests.MathTests.SlowCheck

The first run executed only Adds, the second only the test with the Category trait set to Slow. --list-tests prints every test name without running anything. The summary line also contains the test DLL name and target framework; the sed call above only trims the duration.

Filter syntax

Pitfalls

• Quote the expression. |, & and ! are shell operators; without quotes, bash or PowerShell splits or changes the filter. In PowerShell use single quotes or escape !.
• Special characters in names. Parentheses, commas and = inside a value must be escaped with a backslash (\() per the filter syntax; generic or parameterised test names are easiest to match with ~ on a unique part.
• Several projects. In a folder with more than one project or solution file, dotnet test stops with MSB1011; pass the project or solution path.
• Restore failures such as NU1101 Unable to find package happen before any test runs; they come from the package sources, not from the filter.
• Microsoft.Testing.Platform. Projects that opt into the newer test platform pass filters through the test framework's own options; the --filter syntax above is the VSTest one used by default.

How to confirm it worked

The summary line, for example Passed! - Failed: 0, Passed: 1, Skipped: 0, Total: 1, shows how many tests ran. Total equal to the number you expected confirms the filter; if dotnet test reports that no test matches the given testcase filter, compare it with the output of dotnet test --list-tests.

FAQ