Update Library.Template and enable xUnit NativeAOT tests

.agents/skills/testing/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: testing
+description: Provides guidance and instructions for writing, running and filtering tests.
+user-invocable: false
+---
+
+**IMPORTANT**: This repository uses xUnit v3 with Microsoft.Testing.Platform (MTP v2). 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 `.Tests` suffix.
+* Tests use xUnit v3 with Microsoft.Testing.Platform (MTP v2). The threading tests use xUnit's AOT runner on .NET 10 and the reflection-based runner on older targets.
+* Run published NativeAOT tests with `tools/dotnet-test-cloud.ps1 -Configuration Release -IncludeNativeAOT` after `dotnet publish test -c Release`.
+
+## Running Tests
+
+**Run all tests**:
+```bash
+dotnet test --no-build -c Release
+```
+
+**Run tests for a specific test project**:
+```bash
+dotnet test --no-build -c Release
+```
+
+**Run a single test method**:
+```bash
+dotnet test --no-build -c Release -- --filter-method "ClassName.MethodName"
+```
+
+**Run all tests in a test class**:
+```bash
+dotnet test --no-build -c Release -- --filter-class "ClassName"
+```
+
+**Run tests with wildcard matching** (supports wildcards at beginning and/or end):
+```bash
+dotnet test --no-build -c Release -- --filter-method "*Pattern*"
+```
+
+**Run tests with a specific trait**:
+```bash
+dotnet test --no-build -c Release -- --filter-trait "TraitName=value"
+```
+
+**Run tests for a specific framework only**:
+```bash
+dotnet test --no-build -c Release --framework net8.0
+```
+
+**List all available tests without running them**:
+```bash
+dotnet run --no-build -c Release --framework net8.0 -- --list-tests
+```
+
+**Key points about test filtering with xUnit / MTP v2**:
+- Options after `--` are passed to the test runner, not to `dotnet test`
+- Use `--filter-method`, `--filter-class`, `--filter-namespace`, and `--filter-trait`
+- Exclude unstable tests with `--filter-not-trait "TestCategory=FailsInCloudTest"`
+- Traditional VSTest `--filter` expressions do NOT work
+- Wildcards `*` are supported at the beginning and/or end of filter values
+- See `--help` for query filter language for advanced scenarios

.agents/skills/update-library-template/SKILL.md

@@ -30,6 +30,28 @@ Conflicts in the following files should always be resolved by keeping the curren
 
 * README.md
 
+### Test framework docs, scripts, and packages
+
+Library.Template's `AGENTS.md`, test docs, and `tools/dotnet-test-cloud.ps1` assume **TUnit** on Microsoft.Testing.Platform.
+Many consumers still use **xunit v3 + MTP**, classic **VSTest xunit**, or hybrid setups (including xunit *extension* libraries such as Xunit.StaFact / Xunit.SkippableFact / Xunit.Combinatorial, whose own tests must stay on xunit).
+
+When merging:
+
+* Prefer the template only where the consumer's prior content was **equivalent**. Do not overwrite repo-specific behavior with template placeholders or TUnit-only defaults.
+* Keep framework-specific **AGENTS.md** (and similar agent/contributor docs): filter syntax (`--filter-method` / `--filter-not-trait` vs `--treenode-filter`), FailsInCloudTest / FailureExpected exclusions, real test project paths, and `--framework` TFMs that match the repo's test projects.
+* Keep bespoke **`tools/dotnet-test-cloud.ps1`** logic when it is not equivalent to the template (per-project loops, NonTUnit vs TUnit splits, MultiRID/NativeAOT discovery, hang/blame timeouts, coverage naming, custom filters). Graft genuine template improvements (for example `IncludeNativeAOT` + `Get-NativeAOTTestProjects.ps1`) onto the repo script only when they fit.
+* Do not add unused template **PackageVersion** entries (`TUnit.Engine`, `xunit.v3.assert.aot`, etc.) to `Directory.Packages.props` unless a project in the repo actually references them (or Central Package Management truly requires them).
+* Preserve repo-specific Azure Pipelines / GitHub Actions build steps that the template lacks equivalents for (for example full **MSBuild@1** on Windows for `net35`, `IncompleteBuild` as `warnNotAsError`).
+
+### Traversal coverage, placeholders, and non-test projects
+
+* `GitVersionBaseDirectory` in the template's `Directory.Build.props` assumes the repo has exactly one `version.json`. If the repo has nested `version.json` files (typically for analyzer or source generator projects that need `assemblyVersion` precision `revision`), the repo has deliberately removed or must not have that property. Never re-add it during a merge; keep the repo's first-parent state.
+* `init.ps1` and CI restore and build only `tools/dirs.proj`. If the solution contains projects outside `src` and `test` (for example `samples/` or `benchmark/`), add them to `tools/dirs.proj` (with `Pack="false"` and/or `Publish="false"` as appropriate) so they are still restored and compiled. Otherwise `dotnet format --no-restore` and sample regressions go unnoticed.
+* `test/Directory.Build.props` marks every project under `test` as a test project. Set `<IsTestProject>false</IsTestProject>` on non-test executables there (for example BenchmarkDotNet projects) so they are not run by `dotnet test` or picked up by NativeAOT test discovery.
+* After the merge, search `CONTRIBUTING.md`, `AGENTS.md`, and source headers for template placeholders such as `test/Library.Tests/Library.Tests.csproj`, the company-name placeholder token that `Expand-Template.ps1` replaces with the author, and the template's `net8.0` examples, and replace them with the repo's real project paths, metadata, and NativeAOT-enabled frameworks.
+* If the repo already publishes NativeAOT tests through its own mechanism (for example `MultiRIDProjectReference` items in `test/dirs.proj`), either keep that mechanism and disable the template's discovery (`PublishNativeAOTTests=false`, and drop or don't wire up `Get-NativeAOTTestProjects.ps1`), or replace it fully. Don't leave both half-wired, and update `CONTRIBUTING.md` to describe whichever one the repo actually uses.
+
+
 ### Deleted files
 
 Very typically, when the incoming change is to a file that was deleted locally, the correct resolution is to re-delete the file.

.agents/skills/update-library-template/template-release-notes.md

@@ -18,3 +18,75 @@ dotnet solution EXISTING.sln migrate
 This will create an EXISTING.slnx file. `git add` that file, then `git rm` the old `.sln` file.
 Sometimes a repo will reference the sln filename in a script or doc somewhere.
 Search the repo for such references and update them to the slnx file.
+
+## Migrating from xUnit to TUnit
+
+The template now uses TUnit with Microsoft.Testing.Platform instead of the xUnit test runner.
+When merging this update into an existing repository, migrate all test projects and repo-specific test automation.
+Follow the [TUnit xUnit migration guide](https://tunit.dev/docs/migration/xunit), including its automated migration code fixes.
+
+* Replace xUnit runner/framework package references with `TUnit.Engine` and set `<OutputType>Exe</OutputType>` in each test project.
+  Remove obsolete runner dependencies such as `xunit.runner.visualstudio`, `Microsoft.NET.Test.Sdk`, and `coverlet.collector`, along with `xunit.runner.json`.
+  Reconcile central package versions with the template's `Directory.Packages.props`.
+* Existing xUnit assertions can remain: the template retains `xunit.v3.assert`, using `xunit.v3.assert.aot` for .NET 9 and later.
+  Keep `Xunit` imports for assertions, but use TUnit for test attributes and lifecycle APIs.
+* Convert `[Fact]` and `[Theory]` to `[Test]`, and `[InlineData]` to `[Arguments]`.
+  Migrate member/class data sources, traits, fixtures, collection behavior, setup/teardown, and test output according to the migration guide.
+  Review tests that depend on xUnit's execution ordering or parallelization rules; do not assume those rules carry over.
+* Merge the `global.json` Microsoft.Testing.Platform runner setting, test directory build files, traversal projects, and updated PowerShell/YAML automation.
+  Keep every test project in the repository's solution for managed test runs.
+  The traversals discover `.csproj` files under `src` and `test`; adjust discovery if your projects live elsewhere or use another project language.
+* Update custom test commands and filters.
+  VSTest `--filter` expressions do not work with this runner; pass TUnit filters after `--`, for example `-- --treenode-filter "/*/*/ClassName/MethodName"`.
+  Replace any xUnit-specific CI result or coverage handling with the template's Microsoft.Testing.Platform integration.
+* Validate managed tests and coverage, then run `dotnet publish tools\dirs.proj -c Release` and `.\tools\dotnet-test-cloud.ps1 -Configuration Release -IncludeNativeAOT`.
+  Test projects targeting .NET 8 or later are eligible for NativeAOT publication by default.
+  If a project cannot support NativeAOT, set `<PublishNativeAOTTests>false</PublishNativeAOTTests>` in its project file; it will still run as managed tests.
+
+## Template expansion validation
+
+The `tools/Validate-TemplateExpansion.ps1` script and the template-expansion validation steps in Azure Pipelines and GitHub Actions exist only to test Library.Template itself.
+They clean the working tree, run `Expand-Template.ps1`, and build the expanded result after the normal build and test sequence has completed.
+
+Do not bring `tools/Validate-TemplateExpansion.ps1`, `azure-pipelines/expand-template.yml`, or the block marked `TEMPLATE EXPANSION VALIDATION` in `.github/workflows/build.yml` into an existing repository.
+These files and steps are removed automatically when creating a repository through `Expand-Template.ps1`, and should likewise be discarded while merging template updates into an already-expanded repository.
+
+## NativeAOT compatibility validation
+
+Shipping projects now set `IsAotCompatible` for target frameworks compatible with .NET 8.
+Apply the same conditional property to each shipping project that is intended to support NativeAOT, then resolve all trim and AOT analyzer warnings rather than suppressing them broadly.
+
+The new `test/AotCompatibilityTest` project catches NativeAOT compiler warnings that library analyzers may not report.
+Keep it in the solution, add every NativeAOT-compatible shipping assembly as a `TrimmerRootAssembly`, and retain its publishable entry in `test/dirs.proj`.
+CI validates this project through the existing traversal publish on Windows, Linux, and macOS; it is intentionally marked `IsTestProject=false` because publishing successfully is the test.
+
+## NativeAOT opt-out and AI merge guidance
+
+Not every repo wants to take on NativeAOT readiness or NativeAOT-published test validation.
+If a receiving repo does not intend to support NativeAOT, opt out explicitly instead of inheriting the template's defaults.
+
+For test projects that should remain managed-only:
+
+* Set `<PublishNativeAOTTests>false</PublishNativeAOTTests>` in the project file or in a repo-level `Directory.Build.props`.
+* Leave the managed test project in the solution so usual IL-based testing continues to work.
+* Keep `dotnet test` and the managed coverage flow unchanged; only the NativeAOT publish step is disabled.
+
+For shipping libraries that do not want NativeAOT compatibility analysis:
+
+* Remove `IsAotCompatible` from the project, or set it only for specific target frameworks that truly support NativeAOT.
+* Do not add new AOT compatibility warnings to the build if the library is not intended to be AOT-compatible.
+* If the repo does not target .NET 8 or later, the property should be omitted entirely rather than applied unconditionally.
+
+For the compatibility project itself:
+
+* Remove the `test/AotCompatibilityTest` project from the solution if NativeAOT validation is out of scope.
+* Remove its entry from `test/dirs.proj` so the traversal publish no longer publishes it.
+* Keep the project only when the repo intends to validate shipping assemblies under NativeAOT in CI.
+
+When merging this template into a downstream repo, the AI assistant should ask whether NativeAOT is a relevant target for that repo before applying these changes if `IsAotCompatible` is not already set by any of the projects.
+If the answer is no, it should apply the opt-out steps above instead of blindly keeping the NativeAOT defaults.
+This is especially important for repos that are not shipping a NativeAOT-ready library or that cannot support the extra publish-time validation in CI.
+If the repo owner is unsure about NativeAOT support, you might offer to test the repo for NativeAOT readiness by attempting a NativeAOT publish of the relevant projects and observing whether any compatibility warnings or errors are produced.
+
+In the event the user elects for NativeAOT targeting, make efforts to get tests to work under NativeAOT as well so the shipping code can confidently advertise its NativeAOT compatibility.
+If aspects of the library or tests make successful builds, publish or test runs problematic, discuss this with the repo owner before making significant changes or giving up on NativeAOT support.

.config/dotnet-tools.json

@@ -10,7 +10,7 @@
       "rollForward": false
     },
     "dotnet-coverage": {
-      "version": "18.11.2",
+      "version": "18.12.0",
       "commands": [
         "dotnet-coverage"
       ],
@@ -24,7 +24,7 @@
       "rollForward": false
     },
     "docfx": {
-      "version": "2.78.5",
+      "version": "2.81.0",
       "commands": [
         "docfx"
       ],

.github/actions/publish-artifacts/action.yaml

@@ -14,46 +14,46 @@ runs:
 
   - name: 📢 Upload project.assets.json files
     if: always()
-    uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+    uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
     with:
       name: projectAssetsJson-${{ runner.os }}
       path: ${{ runner.temp }}/_artifacts/projectAssetsJson
     continue-on-error: true
   - name: 📢 Upload variables
-    uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+    uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
     with:
       name: variables-${{ runner.os }}
       path: ${{ runner.temp }}/_artifacts/Variables
     continue-on-error: true
   - name: 📢 Upload build_logs
     if: always()
-    uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+    uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
     with:
       name: build_logs-${{ runner.os }}
       path: ${{ runner.temp }}/_artifacts/build_logs
     continue-on-error: true
   - name: 📢 Upload testResults
     if: always()
-    uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+    uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
     with:
       name: testResults-${{ runner.os }}
       path: ${{ runner.temp }}/_artifacts/testResults
     continue-on-error: true
   - name: 📢 Upload coverageResults
     if: always()
-    uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+    uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
     with:
       name: coverageResults-${{ runner.os }}
       path: ${{ runner.temp }}/_artifacts/coverageResults
     continue-on-error: true
   - name: 📢 Upload symbols
-    uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+    uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
     with:
       name: symbols-${{ runner.os }}
       path: ${{ runner.temp }}/_artifacts/symbols
     continue-on-error: true
   - name: 📢 Upload deployables
-    uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+    uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
     with:
       name: deployables-${{ runner.os }}
       path: ${{ runner.temp }}/_artifacts/deployables

.github/renovate.json

@@ -6,10 +6,37 @@
 		"github>microsoft/vs-renovate-presets:dotnet_packages_LTS",
 		"github>microsoft/vs-renovate-presets:xunitv2"
 	],
+	"labels": ["dependencies"],
 	"packageRules": [
 		{
 			"matchFileNames": ["Directory.Packages.Analyzers.props"],
 			"enabled": false
+		},
+		{
+			"matchPackageNames": ["nbgv", "nerdbank.gitversioning"],
+			"groupName": "nbgv and nerdbank.gitversioning updates"
+		},
+		{
+			"matchPackageNames": ["xunit*"],
+			"groupName": "xunit"
+		},
+		{
+			"matchPackageNames": ["tunit*"],
+			"groupName": "tunit",
+			"schedule": ["on the first day of the month"]
+		},
+		{
+			"matchPackageNames": ["Microsoft.Testing.Extensions.*"],
+			"groupName": "Microsoft Testing Platform"
+		},
+		{
+			"matchDatasources": ["dotnet-version", "docker"],
+			"matchDepNames": ["dotnet-sdk", "mcr.microsoft.com/dotnet/sdk"],
+			"groupName": "Dockerfile and global.json updates"
+		},
+		{
+			"matchPackageNames": ["*"],
+			"allowedVersions": "!/-g[a-f0-9]+$/"
 		}
 	],
 	"customManagers": [

.github/workflows/copilot-setup-steps.yml

@@ -16,7 +16,7 @@ on:
 jobs:
   # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
   copilot-setup-steps:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     # Set the permissions to the lowest permissions possible needed for your steps.
     # Copilot will be given its own token for its operations.
     permissions:

.github/workflows/docs.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
     - main
+  workflow_dispatch:
 
 # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
 # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
@@ -22,7 +23,7 @@ jobs:
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     steps:
     - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       with:
@@ -37,7 +38,12 @@ jobs:
       uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
       with:
         path: docfx/_site
+        # Artifacts from prior attempts remain visible on re-runs, so make the name unique per attempt
+        # to avoid deploy-pages failing due to multiple artifacts with the same name.
+        name: github-pages-${{ github.run_attempt }}
 
     - name: Deploy to GitHub Pages
       id: deployment
       uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
+      with:
+        artifact_name: github-pages-${{ github.run_attempt }}