filter-syntax

测试筛选语法参考

筛选语法取决于平台和测试框架。

VSTest 筛选器（MSTest、xUnit v2、基于 VSTest 的 NUnit）

dotnet test --filter <EXPRESSION>

表达式语法：<Property><Operator><Value>[|&<Expression>]

运算符：

运算符	含义
=	精确匹配
!=	不精确匹配
~	包含
!~	不包含

组合符： |（或）、&（与）。使用括号分组：(A|B)&C

各框架支持的属性：

框架	属性
MSTest	FullyQualifiedName、Name、ClassName、Priority、TestCategory
xUnit	FullyQualifiedName、DisplayName、Traits
NUnit	FullyQualifiedName、Name、Priority、TestCategory

不带运算符的表达式会被视为 FullyQualifiedName~<value>。

示例（VSTest）：

# Run tests whose name contains "LoginTest"
dotnet test --filter "Name~LoginTest"

# Run a specific test class
dotnet test --filter "ClassName=MyNamespace.MyTestClass"

# Run tests in a category
dotnet test --filter "TestCategory=Integration"

# Exclude a category
dotnet test --filter "TestCategory!=Slow"

# Combine: class AND category
dotnet test --filter "ClassName=MyNamespace.MyTestClass&TestCategory=Unit"

# Either of two classes
dotnet test --filter "ClassName=MyNamespace.ClassA|ClassName=MyNamespace.ClassB"

MTP 筛选器 — MSTest 和 NUnit

MTP 上的 MSTest 和 NUnit 使用与 VSTest相同的 --filter 语法（属性、运算符和组合符均相同）。唯一的区别是传递标志的方式：

# .NET SDK 8/9 (after --)
dotnet test -- --filter "Name~LoginTest"

# .NET SDK 10+ (direct)
dotnet test --filter "Name~LoginTest"

MTP 筛选器 — xUnit（v3）

MTP 上的 xUnit v3 使用框架专属的筛选标志，而非通用的 --filter 表达式：

标志	说明
--filter-class "name"	运行指定类中的所有测试
--filter-not-class "name"	排除指定类中的所有测试
--filter-method "name"	运行指定的测试方法
--filter-not-method "name"	排除指定的测试方法
--filter-namespace "name"	运行指定命名空间中的所有测试
--filter-not-namespace "name"	排除指定命名空间中的所有测试
--filter-trait "name=value"	运行具有匹配特征的测试
--filter-not-trait "name=value"	排除具有匹配特征的测试

单个标志可以指定多个值：--filter-class Foo Bar。

# .NET SDK 8/9
dotnet test -- --filter-class "MyNamespace.LoginTests"

# .NET SDK 10+
dotnet test --filter-class "MyNamespace.LoginTests"

# Combine: namespace + trait
dotnet test --filter-namespace "MyApp.Tests.Integration" --filter-trait "Category=Smoke"

xUnit v3 查询筛选语言

对于复杂表达式，请使用 --filter-query 和路径段语法：

/<assemblyFilter>/<namespaceFilter>/<classFilter>/<methodFilter>[traitName=traitValue]

每个段匹配以下内容：程序集名称、命名空间、类名、方法名。任意段中使用 * 表示“匹配全部”。文档：https://xunit.net/docs/query-filter-language

# xUnit.net v3 MTP — using query language (assembly/namespace/class/method[trait])
dotnet test -- --filter-query "/*/*/*IntegrationTests*/*[Category=Smoke]"

MTP 筛选器 — TUnit

TUnit 使用 --treenode-filter 和基于路径的语法：

--treenode-filter "/<Assembly>/<Namespace>/<ClassName>/<TestName>"

任意段中均支持通配符（*）。可以在测试名称后追加筛选运算符，按属性进行筛选。

运算符	含义
*	通配符匹配
=	精确匹配属性（例如，[Category=Unit]）
!=	排除属性值
&	与（组合条件）
|	或（在段内使用，需要括号）

示例（TUnit）：

# All tests in a class
dotnet run --treenode-filter "/*/*/LoginTests/*"

# A specific test
dotnet run --treenode-filter "/*/*/*/AcceptCookiesTest"

# By namespace prefix (wildcard)
dotnet run --treenode-filter "/*/MyProject.Tests.Api*/*/*"

# By custom property
dotnet run --treenode-filter "/*/*/*/*[Category=Smoke]"

# Exclude by property
dotnet run --treenode-filter "/*/*/*/*[Category!=Slow]"

# OR across classes
dotnet run --treenode-filter "/*/*/(LoginTests)|(SignupTests)/*"

# Combined: namespace + property
dotnet run --treenode-filter "/*/MyProject.Tests.Integration/*/*/*[Priority=Critical]"

VSTest → MTP 筛选器转换（用于迁移）

MSTest、NUnit 和 xUnit.net v2（使用 YTest.MTP.XUnit2）：VSTest 的 --filter 语法在 VSTest 和 MTP 上完全相同。无需更改。

xUnit.net v3（原生 MTP）：xUnit.net v3 在 MTP 上不支持 VSTest 的 --filter 语法。请使用 xUnit.net v3 的原生选项转换筛选器：

VSTest --filter 语法	xUnit.net v3 MTP 对应语法	备注
FullyQualifiedName~ClassName	--filter-class *ClassName*	子字符串匹配需要通配符
FullyQualifiedName=Ns.Class.Method	--filter-method Ns.Class.Method	对完全限定方法名进行精确匹配
Name=MethodName	--filter-method *MethodName*	子字符串匹配需要通配符
Category=Value（特征）	--filter-trait "Category=Value"	按特征名称/值对筛选
复杂表达式	--filter-query "expr"	使用 xUnit.net 查询筛选语言（见上文）