In a .NET 10 SDK pipeline, how do dotnet test's --filter and --logger options select tests and produce a results file?
answer
- Property, operator, value
- = != ~ !~ joined by | and &
- bare value means FullyQualifiedName~
- xUnit traits vs TestCategory
- trx;LogFileName= under TestResults
basics
~20 sdotnet test --filter takes expressions such as FullyQualifiedName~Pricing or Category!=Printer joined with | and &, and --logger trx writes a TRX results file into the TestResults folder; both are options of the default VSTest mode.
solid answer
~30 sA filter expression is `<Property><Operator><Value>`, with `=`, `!=`, `~` (contains) and `!~`, combined with `|` (or), `&` (and) and parentheses. A bare value such as `--filter Pricing` means `FullyQualifiedName~Pricing`. Which properties exist depends on the framework: MSTest exposes `TestCategory`, `Priority`, `ClassName`; NUnit `Category` and `TestCategory`; xUnit `DisplayName` plus any trait key, so `[Trait("Category", "Printer")]` is filtered with `Category=Printer`. `--logger "trx;LogFileName=results.trx"` writes a TRX file under `TestResults` (or `--results-directory`), and `--logger "console;verbosity=detailed"` makes the console chattier. These are VSTest-mode options; a solution switched to Microsoft.Testing.Platform gets a different option set.
code
bash · 9 lines# Skip hardware tests on the CI agent and keep a TRX file
dotnet test PressCtl.slnx -c Release \
--filter "Category!=Printer" \
--logger "trx;LogFileName=presscli.trx" \
--results-directory ./test-results
# Nightly job on the print-room machine
dotnet test PressCtl.slnx --filter Category=Printer \
--logger "console;verbosity=detailed"go deeper
Recall that dotnet test can run a subset with --filter and write a results file with --logger trx.
Explain the property-operator-value grammar, the bare-value shorthand, and that each framework exposes different filter properties, xUnit through trait keys.
Show a CI design: tag slow or hardware tests, exclude them by filter on agents, publish TRX from a fixed results directory, and use blame-hang to turn hangs into diagnosable failures.
Weigh test-selection conventions across many repositories: one shared trait vocabulary keeps pipeline filters portable, and the runner choice decides which switches those pipelines may rely on.
## Where the options live `dotnet test` builds the test projects and runs them through a test platform. With the .NET 10 SDK the default is **VSTest**, and `--filter`, `--logger`, `--results-directory`, `--blame-hang-timeout` and `--settings` are VSTest-mode options. A repository can opt into Microsoft.Testing.Platform through `global.json`; in that mode `dotnet test` accepts a different set of options, and filtering is done by the test framework's own switches. That runner choice is covered elsewhere; this answer is about the default mode most pipelines still use. ## The filter grammar An expression has the form **`<Property><Operator><Value>`**: | Operator | Meaning | |---|---| | `=` | exact match | | `!=` | not an exact match | | `~` | contains | | `!~` | does not contain | Expressions combine with `|` (or) and `&` (and), and parentheses group them: `"(FullyQualifiedName~Pricing&Category=Fast)|Priority=1"`. Quote the whole expression in the shell, because `|`, `&` and `!` mean something to bash and PowerShell. A value with no operator at all, such as `dotnet test --filter Pricing`, is shorthand for `FullyQualifiedName~Pricing`. ## Which properties exist The property names come from the test adapter, so they differ by framework: - **MSTest**: `FullyQualifiedName`, `Name`, `ClassName`, `Priority`, `TestCategory`, `Id`. - **NUnit**: `FullyQualifiedName`, `Name`, `Priority`, `TestCategory`, `Category`, `Property`. - **xUnit**: `FullyQualifiedName`, `DisplayName`, and every **trait** key. A test marked `[Trait("Category", "Printer")]` is selected with `Category=Printer` and excluded with `Category!=Printer`. A common slip is writing `TestCategory=Printer` against xUnit tests: xUnit has no `TestCategory` attribute, so the filter only matches if someone literally named a trait that. ## Loggers and results files `--logger` (`-l`) adds a results logger; it can be repeated: 1. `--logger trx` writes a Visual Studio TRX (XML) results file into a `TestResults` folder. 2. `--logger "trx;LogFileName=results.trx"` fixes the file name; `LogFilePrefix` is the alternative when several target frameworks would overwrite each other. 3. `--logger "console;verbosity=detailed"` prints each test, useful in CI logs. 4. `--logger html` writes an HTML report. `--results-directory <dir>` moves the output, which matters when the pipeline uploads a fixed folder. Code coverage is a separate switch (`--collect`), not a logger. ## The print shop's pipeline The print shop's `PressCtl` tool has unit tests and a few tests that drive a real printer, tagged `[Trait("Category", "Printer")]`. The CI agent has no printer, so the pipeline runs `dotnet test --filter "Category!=Printer" --logger "trx;LogFileName=presscli.trx" --results-directory ./test-results`, uploads the TRX file to the CI system's test tab, and a nightly job on the print-room machine runs `--filter Category=Printer`. ## Edge cases worth knowing - Escape special characters in values with a backslash (`\(`, `\&`), and commas in generic type names with `%2C`. - `--list-tests` shows what a filter would run without running it. - `--blame-hang-timeout 5m` collects a dump and aborts a hung run instead of letting the CI job time out silently. ## Common mistakes - Relying on test names for selection: renaming a class silently changes what a `FullyQualifiedName~` filter runs, while a trait or category stays stable. - Assuming a filter that matches nothing will fail loudly; it may only produce a warning, so check the run summary, or `--list-tests`, when a pipeline suddenly reports zero tests. - Writing results into the default location and then uploading a different folder: the default is a `TestResults` folder under each test project, so set `--results-directory` once for the whole solution.
- Why must the filter be quoted in bash?`|` starts a pipe, `&` backgrounds a command and `!` triggers history expansion in interactive bash, so an unquoted `Category!=Printer|Priority=1` is mangled before `dotnet test` sees it. Quoting the whole expression passes it through intact.
- How do you stop several target frameworks overwriting one TRX file?Use `--logger "trx;LogFilePrefix=presscli"` instead of `LogFileName`; the logger then makes each file name unique per target framework, so a multi-targeted test project no longer overwrites one framework's results with the next.
- --filter takes a regular expression matched against test names.
- TestCategory=Printer selects xUnit tests marked with a Category trait.
- --logger trx is the switch that produces code coverage.
- --filter and --logger behave the same after switching global.json to Microsoft.Testing.Platform.
- A filter with no operator matches the test method name exactly.