From b1fe4b221aa59977562003a87588c3fb9e844e2e Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 12 Jan 2026 04:23:35 +0000
Subject: [PATCH 1/2] Initial plan


From 181d9f153b18304d8e9f5686aa3f6d875ec8a5e6 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 12 Jan 2026 05:16:13 +0000
Subject: [PATCH 2/2] Update copilot instructions with MTP v2/xunit v3 test
 commands

Co-authored-by: AArnott <3548+AArnott@users.noreply.github.com>
---
 .github/copilot-instructions.md | 63 +++++++++++++++++++++++++++++++--
 1 file changed, 61 insertions(+), 2 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 08593502..bb31332b 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -12,9 +12,68 @@
 
 ## Testing
 
+**IMPORTANT**: This repository uses Microsoft.Testing.Platform (MTP v2) with xunit v3. Traditional `--filter` syntax does NOT work. Use the options below instead.
+
 * There should generally be one test project (under the `test` directory) per shipping project (under the `src` directory). Test projects are named after the project being tested with a `.Test` suffix.
-* Tests should use the Xunit testing framework.
-* Some tests are known to be unstable. When running tests, you should skip the unstable ones by running `dotnet test --filter "TestCategory!=FailsInCloudTest"`.
+* Tests use xunit v3 with Microsoft.Testing.Platform (MTP v2). Traditional VSTest `--filter` syntax does NOT work.
+* Some tests are known to be unstable. When running tests, you should skip the unstable ones by using `-- --filter-not-trait "FailsInCloudTest=true"`.
+
+### Running Tests
+
+**Run all tests**:
+```bash
+dotnet test --no-build -c Release
+```
+
+**Run tests for a specific test project**:
+```bash
+dotnet test --project test/Library.Tests/Library.Tests.csproj --no-build -c Release
+```
+
+**Run a single test method**:
+```bash
+dotnet test --project test/Library.Tests/Library.Tests.csproj --no-build -c Release -- --filter-method ClassName.MethodName
+```
+
+**Run all tests in a test class**:
+```bash
+dotnet test --project test/Library.Tests/Library.Tests.csproj --no-build -c Release -- --filter-class ClassName
+```
+
+**Run tests with wildcard matching** (supports wildcards at beginning and/or end):
+```bash
+dotnet test --project test/Library.Tests/Library.Tests.csproj --no-build -c Release -- --filter-method "*Pattern*"
+```
+
+**Run tests with a specific trait** (equivalent to category filtering):
+```bash
+dotnet test --project test/Library.Tests/Library.Tests.csproj --no-build -c Release -- --filter-trait "TraitName=value"
+```
+
+**Exclude tests with a specific trait** (skip unstable tests):
+```bash
+dotnet test --project test/Library.Tests/Library.Tests.csproj --no-build -c Release -- --filter-not-trait "FailsInCloudTest=true"
+```
+
+**Run tests for a specific framework only**:
+```bash
+dotnet test --project test/Library.Tests/Library.Tests.csproj --no-build -c Release --framework net9.0
+```
+
+**List all available tests without running them**:
+```bash
+cd test/Library.Tests
+dotnet run --no-build -c Release --framework net9.0 -- --list-tests
+```
+
+**Key points about test filtering with MTP v2 / xunit v3**:
+- Options after `--` are passed to the test runner, not to `dotnet test`
+- Use `--filter-method`, `--filter-class`, `--filter-namespace` for simple filtering
+- Use `--filter-trait` and `--filter-not-trait` for trait-based filtering (replaces `--filter "TestCategory=..."`)
+- Traditional VSTest `--filter` expressions do NOT work
+- Wildcards `*` are supported at the beginning and/or end of filter values
+- Multiple simple filters of the same type use OR logic, different types combine with AND
+- See `--help` for query filter language for advanced scenarios
 
 ## Coding style