Run selective unit tests

With the dotnet test command in .NET Core, you can use a filter expression to run selective tests. This article demonstrates how to filter which tests are run. The following examples use dotnet test. If you're using vstest.console.exe, replace --filter with --testcasefilter:.

Character escaping

Using filters that include exclamation mark ! on *nix requires escaping since ! is reserved. For example, this filter skips all tests if the namespace contains IntegrationTests:

dotnet test --filter FullyQualifiedName\!~IntegrationTests

Important

The backslash precedes the exclamation mark to indicate it is an escaped character \!.

For FullyQualifiedName values that include a comma for generic type parameters, escape the comma with %2C. For example:

dotnet test --filter "FullyQualifiedName=MyNamespace.MyTestsClass<ParameterType1%2CParameterType2>.MyTestMethod"
using Microsoft.VisualStudio.TestTools.UnitTesting;

namespace MSTestNamespace
{
    [TestClass]
    public class UnitTest1
    {
        [TestMethod, Priority(1), TestCategory("CategoryA")]
        public void TestMethod1()
        {
        }

        [TestMethod, Priority(2)]
        public void TestMethod2()
        {
        }
    }
}
Expression Result
dotnet test --filter Method Runs tests whose FullyQualifiedName contains Method. Available in vstest 15.1+.
dotnet test --filter Name~TestMethod1 Runs tests whose name contains TestMethod1.
dotnet test --filter ClassName=MSTestNamespace.UnitTest1 Runs tests that are in class MSTestNamespace.UnitTest1.
Note: The ClassName value should have a namespace, so ClassName=UnitTest1 won't work.
dotnet test --filter FullyQualifiedName!=MSTestNamespace.UnitTest1.TestMethod1 Runs all tests except MSTestNamespace.UnitTest1.TestMethod1.
dotnet test --filter TestCategory=CategoryA Runs tests that are annotated with [TestCategory("CategoryA")].
dotnet test --filter Priority=2 Runs tests that are annotated with [Priority(2)].

Examples using the conditional operators | and &:

To run tests that have UnitTest1 in their FullyQualifiedName or TestCategoryAttribute is "CategoryA".

dotnet test --filter "FullyQualifiedName~UnitTest1|TestCategory=CategoryA"

To run tests that have UnitTest1 in their FullyQualifiedName and have a TestCategoryAttribute of "CategoryA".

dotnet test --filter "FullyQualifiedName~UnitTest1&TestCategory=CategoryA"

To run tests that have either FullyQualifiedName containing UnitTest1 and have a TestCategoryAttribute of "CategoryA" or have a PriorityAttribute with a priority of 1.

dotnet test --filter "(FullyQualifiedName~UnitTest1&TestCategory=CategoryA)|Priority=1"
using Xunit;

namespace XUnitNamespace
{
    public class TestClass1
    {
        [Fact, Trait("Priority", "1"), Trait("Category", "CategoryA")]
        public void Test1()
        {
        }

        [Fact, Trait("Priority", "2")]
        public void Test2()
        {
        }
    }
}
Expression Result
dotnet test --filter DisplayName=XUnitNamespace.TestClass1.Test1 Runs only one test, XUnitNamespace.TestClass1.Test1.
dotnet test --filter FullyQualifiedName!=XUnitNamespace.TestClass1.Test1 Runs all tests except XUnitNamespace.TestClass1.Test1.
dotnet test --filter DisplayName~TestClass1 Runs tests whose display name contains TestClass1.

In the code example, the defined traits with keys "Category" and "Priority" can be used for filtering.

Expression Result
dotnet test --filter XUnit Runs tests whose FullyQualifiedName contains XUnit. Available in vstest 15.1+.
dotnet test --filter Category=CategoryA Runs tests that have [Trait("Category", "CategoryA")].

Examples using the conditional operators | and &:

To run tests that have TestClass1 in their FullyQualifiedName or have a Trait with a key of "Category" and value of "CategoryA".

dotnet test --filter "FullyQualifiedName~TestClass1|Category=CategoryA"

To run tests that have TestClass1 in their FullyQualifiedName and have a Trait with a key of "Category" and value of "CategoryA".

dotnet test --filter "FullyQualifiedName~TestClass1&Category=CategoryA"

To run tests that have either FullyQualifiedName containing TestClass1 and have a Trait with a key of "Category" and value of "CategoryA" or have a Trait with a key of "Priority" and value of 1.

dotnet test --filter "(FullyQualifiedName~TestClass1&Category=CategoryA)|Priority=1"
using NUnit.Framework;

namespace NUnitNamespace
{
    public class UnitTest1
    {
        [Test, Property("Priority", 1), Category("CategoryA")]
        public void TestMethod1()
        {
        }

        [Test, Property("Priority", 2)]
        public void TestMethod2()
        {
        }
    }
}
Expression Result
dotnet test --filter Method Runs tests whose FullyQualifiedName contains Method. Available in vstest 15.1+.
dotnet test --filter Name~TestMethod1 Runs tests whose name contains TestMethod1.
dotnet test --filter FullyQualifiedName~NUnitNamespace.UnitTest1 Runs tests that are in class NUnitNamespace.UnitTest1.
dotnet test --filter FullyQualifiedName!=NUnitNamespace.UnitTest1.TestMethod1 Runs all tests except NUnitNamespace.UnitTest1.TestMethod1.
dotnet test --filter TestCategory=CategoryA Runs tests that are annotated with [Category("CategoryA")].
dotnet test --filter Priority=2 Runs tests that are annotated with [Priority(2)].

Examples using the conditional operators | and &:

To run tests that have UnitTest1 in their FullyQualifiedName or have a Category of "CategoryA".

dotnet test --filter "FullyQualifiedName~UnitTest1|TestCategory=CategoryA"

To run tests that have UnitTest1 in their FullyQualifiedName and have a Category of "CategoryA".

dotnet test --filter "FullyQualifiedName~UnitTest1&TestCategory=CategoryA"

To run tests that have either a FullyQualifiedName containing UnitTest1 and have a Category of "CategoryA" or have a Property with a "Priority" of 1.

dotnet test --filter "(FullyQualifiedName~UnitTest1&TestCategory=CategoryA)|Priority=1"

For more information, see TestCase filter.

See also

Next steps