filter-syntax

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Test Filter Syntax Reference

测试过滤语法参考

Filter syntax depends on the platform and test framework.

过滤语法取决于使用的平台和测试框架。

VSTest filters (MSTest, xUnit v2, NUnit on VSTest)

VSTest过滤器（基于VSTest的MSTest、xUnit v2、NUnit）

bash

dotnet test --filter <EXPRESSION>

Expression syntax:

<Property><Operator><Value>[|&<Expression>]

Operators:

Operator	Meaning
`=`	Exact match
`!=`	Not exact match
`~`	Contains
`!~`	Does not contain

Combinators:

(OR),

(AND). Parentheses for grouping:

(A|B)&C

Supported properties by framework:

Framework	Properties
MSTest	`FullyQualifiedName` , `Name` , `ClassName` , `Priority` , `TestCategory`
xUnit	`FullyQualifiedName` , `DisplayName` , `Traits`
NUnit	`FullyQualifiedName` , `Name` , `Priority` , `TestCategory`

An expression without an operator is treated as

FullyQualifiedName~<value>

Examples (VSTest):

bash

undefined

bash

dotnet test --filter <EXPRESSION>

表达式语法：

<属性><运算符><值>[|&<表达式>]

运算符：

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

组合符：

（或）、

（且），可使用括号分组：

(A|B)&C

各框架支持的属性：

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

不带运算符的表达式会默认按照

FullyQualifiedName~<值>

规则处理。

VSTest使用示例：

bash

undefined

Run tests whose name contains "LoginTest"

运行名称包含"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"

undefined

dotnet test --filter "ClassName=MyNamespace.ClassA|ClassName=MyNamespace.ClassB"

undefined

MTP filters — MSTest and NUnit

MTP过滤器——MSTest与NUnit

MSTest and NUnit on MTP use the same
--filter
syntax as VSTest (same properties, operators, and combinators). The only difference is how the flag is passed:

bash

undefined

基于MTP运行的MSTest和NUnit使用与VSTest完全相同的
--filter
语法（属性、运算符、组合符规则一致），唯一区别是参数传递方式：

bash

undefined

.NET SDK 8/9 (after --)

.NET SDK 8/9 版本（参数放在--之后）

dotnet test -- --filter "Name~LoginTest"

.NET SDK 10+ (direct)

.NET SDK 10+ 版本（直接传参）

dotnet test --filter "Name~LoginTest"

undefined

dotnet test --filter "Name~LoginTest"

undefined

MTP filters — xUnit (v3)

MTP过滤器——xUnit（v3）

xUnit v3 on MTP uses framework-specific filter flags instead of the generic

--filter

expression:

Flag	Description
`--filter-class "name"`	Run all tests in a given class
`--filter-not-class "name"`	Exclude all tests in a given class
`--filter-method "name"`	Run a specific test method
`--filter-not-method "name"`	Exclude a specific test method
`--filter-namespace "name"`	Run all tests in a namespace
`--filter-not-namespace "name"`	Exclude all tests in a namespace
`--filter-trait "name=value"`	Run tests with a matching trait
`--filter-not-trait "name=value"`	Exclude tests with a matching trait

Multiple values can be specified with a single flag:

--filter-class Foo Bar

bash

undefined

基于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

bash

undefined

.NET SDK 8/9

.NET SDK 8/9 版本

dotnet test -- --filter-class "MyNamespace.LoginTests"

.NET SDK 10+

.NET SDK 10+ 版本

dotnet test --filter-class "MyNamespace.LoginTests"

Combine: namespace + trait

组合规则：指定命名空间 + 指定特征

dotnet test --filter-namespace "MyApp.Tests.Integration" --filter-trait "Category=Smoke"

undefined

dotnet test --filter-namespace "MyApp.Tests.Integration" --filter-trait "Category=Smoke"

undefined

xUnit v3 query filter language

xUnit v3查询过滤语言

For complex expressions, use

--filter-query

with a path-segment syntax:

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

Each segment matches against: assembly name, namespace, class name, method name. Use

for "match all" in any segment. Documentation: https://xunit.net/docs/query-filter-language

shell

undefined

针对复杂过滤需求，可使用

--filter-query

配合路径分段语法实现：

/<程序集过滤器>/<命名空间过滤器>/<类过滤器>/<方法过滤器>[特征名=特征值]

每个分段分别匹配：程序集名称、命名空间、类名、方法名，任意分段都可使用

表示匹配所有。官方文档：https://xunit.net/docs/query-filter-language

shell

undefined

xUnit.net v3 MTP — using query language (assembly/namespace/class/method[trait])

xUnit.net v3 MTP — 使用查询语言（程序集/命名空间/类/方法[特征]）

dotnet test -- --filter-query "///IntegrationTests/*[Category=Smoke]"

undefined

dotnet test -- --filter-query "///IntegrationTests/*[Category=Smoke]"

undefined

MTP filters — TUnit

MTP过滤器——TUnit

TUnit uses

--treenode-filter

with a path-based syntax:

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

Wildcards (

) are supported in any segment. Filter operators can be appended to test names for property-based filtering.

Operator	Meaning
`*`	Wildcard match
`=`	Exact property match (e.g., `[Category=Unit]` )
`!=`	Exclude property value
`&`	AND (combine conditions)
`\|`	OR (within a segment, requires parentheses)

Examples (TUnit):

bash

undefined

TUnit使用

--treenode-filter

配合基于路径的语法实现过滤：

--treenode-filter "/<程序集>/<命名空间>/<类名>/<测试名>"

任意分段都支持通配符（

），可在测试名后追加过滤运算符实现基于属性的过滤。

运算符	含义
`*`	通配符匹配
`=`	属性精确匹配（例如 `[Category=Unit]` ）
`!=`	排除指定属性值
`&`	且（组合多个条件）
`\|`	或（仅在同一分段内使用，需要配合括号）

TUnit使用示例：

bash

undefined

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]"

undefined

dotnet run --treenode-filter "//MyProject.Tests.Integration///[Priority=Critical]"

undefined

VSTest → MTP filter translation (for migration)

VSTest→MTP过滤器转换（迁移用）

MSTest, NUnit, and xUnit.net v2 (with
YTest.MTP.XUnit2
): The VSTest

--filter

syntax is identical on both VSTest and MTP. No changes needed.

xUnit.net v3 (native MTP): xUnit.net v3 does NOT support the VSTest

--filter

syntax on MTP. Translate filters using xUnit.net v3's native options:

VSTest `--filter` syntax	xUnit.net v3 MTP equivalent	Notes
`FullyQualifiedName~ClassName`	`--filter-class ClassName`	Wildcards required for substring match
`FullyQualifiedName=Ns.Class.Method`	`--filter-method Ns.Class.Method`	Exact match on fully qualified method
`Name=MethodName`	`--filter-method MethodName`	Wildcards for substring match
`Category=Value` (trait)	`--filter-trait "Category=Value"`	Filter by trait name/value pair
Complex expressions	`--filter-query "expr"`	Uses xUnit.net query filter language (see above)

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查询过滤语言（见上文）