dotnet · Copilot · Mar 29, 2026 · Mar 29, 2026 · Mar 29, 2026 · Mar 29, 2026
diff --git a/Directory.Build.targets b/Directory.Build.targets
@@ -31,6 +31,23 @@
   <Import Project="$(RepositoryEngineeringDir)packaging.targets" Condition="'$(IsPackable)' == 'true' and '$(MSBuildProjectExtension)' != '.pkgproj'" />
   <Import Project="$(RepositoryEngineeringDir)slngen.targets" Condition="'$(IsSlnGen)' == 'true'" />
 
+  <!--
+    The xunit.v3.core.mtp-v1 NuGet package unconditionally sets UseAppHost=true
+    in its buildTransitive props and validates it in its buildTransitive targets.
+    Test projects in dotnet/runtime don't need an apphost (tests are run via
+    dotnet exec or the Helix test runner).  Override UseAppHost here, in
+    Directory.Build.targets, which is imported after the NuGet package targets.
+    Library tests also have an override in eng/testing/xunit/xunit.targets.
+  -->
+  <PropertyGroup Condition="'$(IsTestProject)' == 'true' and '$(TestSingleFile)' != 'true'">
+    <UseAppHost>false</UseAppHost>
+    <_RuntimeIdentifierUsesAppHost Condition="'$(SelfContained)' == 'true'">false</_RuntimeIdentifierUsesAppHost>
+  </PropertyGroup>
+  <Target Name="_XunitValidateBuild" BeforeTargets="BeforeBuild" Condition=" '$(TargetFramework)' != '' AND '$(IsTestProject)' == 'true' ">
+    <Error Text="xUnit.net v3 test projects must be executable (set project property '&lt;OutputType&gt;Exe&lt;/OutputType&gt;')."
+           Condition=" '$(OutputType)' != 'Exe' AND '$(TargetsMobile)' != 'true' " />
+  </Target>
+
   <PropertyGroup>
     <NetCoreAppCurrentBuildSettings>$(NetCoreAppCurrent)-$(TargetOS)-$(Configuration)-$(TargetArchitecture)</NetCoreAppCurrentBuildSettings>
     <NativeBinDir>$([MSBuild]::NormalizeDirectory('$(ArtifactsBinDir)', 'native', '$(NetCoreAppCurrentBuildSettings)'))</NativeBinDir>

diff --git a/NuGet.config b/NuGet.config
@@ -12,6 +12,7 @@
       one as a template. The following line is a marker to insert the test restore sources.
     -->
     <!-- TEST_RESTORE_SOURCES_INSERTION_LINE -->
+    <add key="nuget" value="https://api.nuget.org/v3/index.json" />
     <add key="dotnet-public" value="https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public/nuget/v3/index.json" />
     <add key="dotnet-tools" value="https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-tools/nuget/v3/index.json" />
     <add key="dotnet-eng" value="https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-eng/nuget/v3/index.json" />

diff --git a/docs/workflow/testing/libraries/filtering-tests.md b/docs/workflow/testing/libraries/filtering-tests.md
@@ -338,6 +338,12 @@ A common usage in the libraries tests is the following:
 
 This is put on test classes to indicate that none of the tests in that class (which as usual run serially with respect to each other) may run concurrently with tests in another class. This is used for tests that use a lot of disk space or memory, or dominate all the cores, such that they are likely to disrupt any tests that run concurrently.
 
+## xunit v3 Migration
+
+For xunit v3–specific patterns (empty `[MemberData]`, `ConditionalTheory`
+migration, non-serializable test data), see the
+[xunit v3 Migration Notes](xunit3-migration.md).
+
 ## FactAttribute and `Skip`
 
 Another way to disable the test entirely is to use the `Skip` named argument that is used on the `FactAttribute`.

diff --git a/docs/workflow/testing/libraries/xunit3-migration.md b/docs/workflow/testing/libraries/xunit3-migration.md
@@ -0,0 +1,175 @@
+# xunit v3 Migration Notes
+
+This document covers common issues and patterns encountered when migrating
+tests from xunit v2 to xunit v3.
+
+## Empty `[MemberData]` at Runtime
+
+In xunit v3, a `[Theory]` whose `[MemberData]` source returns **zero rows**
+is a hard failure ("No data found"), not a silent no-op. When running through
+the test harness this surfaces as:
+
+```
+[FATAL ERROR] System.InvalidOperationException
+  Cannot find test case metadata for ID <sha256-hash>
+```
+
+This commonly happens when:
+
+- A `[MemberData]` source filters its output based on platform support
+  (e.g., `Where(x => SomeAlgorithm.IsSupported)`) and all items are
+  filtered out on the current platform.
+- A `[MemberData]` source **throws during enumeration** (e.g., because an
+  object in the test data does not support `GetHashCode()`). The
+  `ModifiedType` returned by `GetModifiedFieldType()` is a known example —
+  it throws `NotSupportedException` from `GetHashCode()`.
+
+### Diagnosing
+
+Run the test assembly directly with `-list full` to map the failing ID to a
+test method name:
+
+```bash
+# Use the testhost dotnet, not the system one
+artifacts/bin/testhost/net11.0-linux-Debug-x64/dotnet exec \
+  artifacts/bin/<TestProject>/Debug/net11.0-unix/<TestProject>.dll \
+  -list full 2>&1 | grep <sha256-hash>
+```
+
+Then inspect the `[MemberData]` source for conditional logic or types that
+cannot be serialized/hashed by xunit v3.
+
+### Fixing Empty Data
+
+Switch to an unconditional data source and move the platform check into the
+test body:
+
+```cs
+// BROKEN: MemberData can return zero rows
+public static IEnumerable<object[]> SupportedAlgorithmsTestData =>
+    AllAlgorithms.Where(a => MyAlgorithm.IsSupported(a)).Select(a => new object[] { a });
+
+[Theory]
+[MemberData(nameof(SupportedAlgorithmsTestData))]
+public void MyTest(MyAlgorithm algorithm) { /* ... */ }
+```
+
+```cs
+// FIXED: MemberData always returns rows; skip at runtime
+public static IEnumerable<object[]> AllAlgorithmsTestData =>
+    AllAlgorithms.Select(a => new object[] { a });
+
+[Theory]
+[MemberData(nameof(AllAlgorithmsTestData))]
+public void MyTest(MyAlgorithm algorithm)
+{
+    Assert.SkipUnless(MyAlgorithm.IsSupported(algorithm), "Not supported on this platform.");
+    /* ... */
+}
+```
+
+### Fixing Non-Serializable Data
+
+When test data contains types that xunit v3 cannot serialize or hash (e.g.,
+`ModifiedType` from `GetModifiedFieldType()`), pass simple identifiers
+through `[InlineData]` and construct the problematic objects inside the test
+body:
+
+```cs
+// BROKEN: ModifiedType throws NotSupportedException from GetHashCode()
+public static IEnumerable<object[]> TestData
+{
+    get
+    {
+        yield return [someSignatureType, typeof(Foo).GetField("Bar").GetModifiedFieldType()];
+    }
+}
+
+[Theory]
+[MemberData(nameof(TestData))]
+public void MyTest(Type signatureType, Type reflectedType) { /* ... */ }
+```
+
+```cs
+// FIXED: pass field name, construct ModifiedType in test body
+[Theory]
+[InlineData(nameof(Foo.Bar))]
+public void MyTest(string fieldName)
+{
+    Type reflectedType = typeof(Foo).GetField(fieldName).GetModifiedFieldType();
+    Type signatureType = /* construct based on fieldName */;
+    /* ... */
+}
+```
+
+## `ConditionalTheory` → `[Theory]` + `Assert.SkipUnless`
+
+`[ConditionalTheory]` from `Microsoft.DotNet.XUnitExtensions` evaluates its
+conditions **before** enumerating `[MemberData]`. If the condition is false,
+the entire theory is skipped without touching test data.
+
+When migrating to plain `[Theory]`, move the condition into the test body
+using `Assert.SkipUnless`:
+
+```cs
+// Before (xunit v2 / ConditionalTheory)
+[ConditionalTheory(typeof(PlatformDetection), nameof(PlatformDetection.IsFeatureSupported))]
+[MemberData(nameof(MyTestData))]
+public void MyTest(int x) { /* ... */ }
+
+// After (xunit v3)
+[Theory]
+[MemberData(nameof(MyTestData))]
+public void MyTest(int x)
+{
+    Assert.SkipUnless(PlatformDetection.IsFeatureSupported, "Requires IsFeatureSupported");
+    /* ... */
+}
+```
+
+**Important**: Ensure the `[MemberData]` source does not depend on the same
+condition. If it does, refactor the data source to always return rows (see
+[Fixing Empty Data](#fixing-empty-data) above).
+
+## `ConditionalFact` → `[Fact]` + `Assert.SkipUnless`
+
+The same pattern applies:
+
+```cs
+// Before
+[ConditionalFact(typeof(PlatformDetection), nameof(PlatformDetection.IsFeatureSupported))]
+public void MyTest() { /* ... */ }
+
+// After
+[Fact]
+public void MyTest()
+{
+    Assert.SkipUnless(PlatformDetection.IsFeatureSupported, "Requires IsFeatureSupported");
+    /* ... */
+}
+```
+
+## `EqualException.ForMismatchedValues` Signature Change
+
+In xunit v3, `EqualException.ForMismatchedValues` requires `string`
+parameters instead of `object`. Calls that previously passed arbitrary
+objects must now call `.ToString()`:
+
+```cs
+// Before (xunit v2)
+throw EqualException.ForMismatchedValues(expected, actual, banner);
+
+// After (xunit v3)
+throw EqualException.ForMismatchedValues(expected.ToString(), actual.ToString(), banner);
+```
+
+## Runner Configuration
+
+The test runner configuration is in `eng/testing/xunit/xunit.runner.json`.
+Key settings for the migration:
+
+- `"preEnumerateTheories": false` — theories are **not** pre-enumerated at
+  discovery time. Data is enumerated at runtime. This means `[MemberData]`
+  sources are called during execution, not discovery.
+- `"diagnosticMessages": true` — enables diagnostic output for debugging
+  discovery and execution issues.
diff --git a/eng/Version.Details.props b/eng/Version.Details.props
@@ -143,6 +143,10 @@ This file should be imported by eng/Versions.props
     <MicrosoftDotNetXUnitAssertVersion>$(MicrosoftDotNetXUnitAssertPackageVersion)</MicrosoftDotNetXUnitAssertVersion>
     <MicrosoftDotNetXUnitConsoleRunnerVersion>$(MicrosoftDotNetXUnitConsoleRunnerPackageVersion)</MicrosoftDotNetXUnitConsoleRunnerVersion>
     <MicrosoftDotNetXUnitExtensionsVersion>$(MicrosoftDotNetXUnitExtensionsPackageVersion)</MicrosoftDotNetXUnitExtensionsVersion>
+    <XUnitV3Version>4.0.0-pre.81</XUnitV3Version>
+    <!-- xunit 4.0.0-pre.81 (MTP v2) requires Microsoft.Testing.Platform >= 2.2.1;
+         arcade defaults to 1.9.1 (MTP v1), causing NU1605 downgrade errors. -->
+    <MicrosoftTestingPlatformVersion>2.2.1</MicrosoftTestingPlatformVersion>
     <MicrosoftNetCompilersToolsetVersion>$(MicrosoftNetCompilersToolsetPackageVersion)</MicrosoftNetCompilersToolsetVersion>
     <MicrosoftNETSdkILVersion>$(MicrosoftNETSdkILPackageVersion)</MicrosoftNETSdkILVersion>
     <MicrosoftNETWorkloadEmscriptenCurrentManifest110100TransportVersion>$(MicrosoftNETWorkloadEmscriptenCurrentManifest110100TransportPackageVersion)</MicrosoftNETWorkloadEmscriptenCurrentManifest110100TransportVersion>

diff --git a/eng/Versions.props b/eng/Versions.props
@@ -157,7 +157,7 @@
     <MoqVersion>4.18.4</MoqVersion>
     <MicrosoftDiagnosticsRuntimeVersion>4.0.722401</MicrosoftDiagnosticsRuntimeVersion>
     <AwesomeAssertionsVersion>8.0.2</AwesomeAssertionsVersion>
-    <FsCheckVersion>2.14.3</FsCheckVersion>
+    <FsCheckVersion>3.3.2</FsCheckVersion>
     <CommandLineParserVersion>2.9.1</CommandLineParserVersion>
     <CompilerPlatformTestingVersion>1.1.3-beta1.24423.1</CompilerPlatformTestingVersion>
     <CompilerPlatformTestingDiffPlexVersion>1.7.2</CompilerPlatformTestingDiffPlexVersion>

diff --git a/eng/XUnitV3/XUnitV3.targets b/eng/XUnitV3/XUnitV3.targets
@@ -0,0 +1,113 @@
+<!-- Licensed to the .NET Foundation under one or more agreements. The .NET Foundation licenses this file to you under the MIT license. -->
+<!--
+  Repo-local override for the Arcade SDK XUnitV3 test runner targets.
+
+  The Arcade SDK passes 'report-xunit' and 'report-xunit-filename' (with
+  the double-dash prefix) on the MTP runner command line, but xUnit v3
+  4.0.0-pre.81 renamed those options to 'report-xunit-xml' and
+  'report-xunit-xml-filename'.  This file imports the Arcade originals and
+  then redefines the RunTests target with the corrected option names.
+
+  Remove this override once the Arcade SDK is updated.
+-->
+<Project>
+
+  <!-- Import the Arcade SDK XUnitV3 targets (package refs, settings, runner). -->
+  <Import Project="$(NuGetPackageRoot)microsoft.dotnet.arcade.sdk/$(MicrosoftDotNetArcadeSdkVersion)/tools/XUnitV3/XUnitV3.targets" />
+
+  <!--
+    Redefine RunTests with corrected MTP CLI option names.
+    Because this target is defined after the Arcade import, MSBuild uses this
+    definition (last-writer-wins).
+  -->
+  <Target Name="RunTests"
+          Outputs="%(TestToRun.ResultsStdOutPath)"
+          Condition="'@(TestToRun)' != ''">
+    <Telemetry EventName="NETCORE_ENGINEERING_TELEMETRY" EventData="Category=Test" />
+
+    <PropertyGroup Condition="'$(UseMicrosoftTestingPlatformRunner)' == 'true'">
+      <_TestResultDirectory>$([System.IO.Path]::GetDirectoryName('%(TestToRun.ResultsTrxPath)'))</_TestResultDirectory>
+      <_TestResultTrxFileName>$([System.IO.Path]::GetFileName('%(TestToRun.ResultsTrxPath)'))</_TestResultTrxFileName>
+      <_TestResultXmlFileName>$([System.IO.Path]::GetFileName('%(TestToRun.ResultsXmlPath)'))</_TestResultXmlFileName>
+      <_TestResultHtmlFileName>$([System.IO.Path]::GetFileName('%(TestToRun.ResultsHtmlPath)'))</_TestResultHtmlFileName>
+    </PropertyGroup>
+
+    <PropertyGroup>
+      <_TestEnvironment>%(TestToRun.EnvironmentDisplay)</_TestEnvironment>
+      <_TestAssembly>%(TestToRun.Identity)</_TestAssembly>
+      <_TestRuntime>%(TestToRun.TestRuntime)</_TestRuntime>
+      <_TestTimeout>%(TestToRun.TestTimeout)</_TestTimeout>
+      <_TestRunnerAdditionalArguments>%(TestToRun.TestRunnerAdditionalArguments)</_TestRunnerAdditionalArguments>
+
+      <_TestRunner>%(TestToRun.RunCommand)</_TestRunner>
+      <_TestRunnerArgs Condition="'$(UseMicrosoftTestingPlatformRunner)' != 'true'">%(TestToRun.RunArguments) $(_TestRunnerAdditionalArguments) -xml "%(TestToRun.ResultsXmlPath)" -html "%(TestToRun.ResultsHtmlPath)" -trx "%(TestToRun.ResultsTrxPath)"</_TestRunnerArgs>
+      <!-- Fixed: report-xunit-xml instead of report-xunit, report-xunit-xml-filename instead of report-xunit-filename (all with double-dash prefix) -->
+      <_TestRunnerArgs Condition="'$(UseMicrosoftTestingPlatformRunner)' == 'true'">%(TestToRun.RunArguments) $(_TestRunnerAdditionalArguments) --results-directory "$(_TestResultDirectory)" --report-xunit-xml --report-xunit-xml-filename "$(_TestResultXmlFileName)" --report-xunit-html --report-xunit-html-filename "$(_TestResultHtmlFileName)" --report-trx --report-trx-filename "$(_TestResultTrxFileName)"</_TestRunnerArgs>
+
+      <TestDotNetRoot Condition="'$(TestDotNetRoot)' == ''">$(DotNetRoot)</TestDotNetRoot>
+    </PropertyGroup>
+
+    <PropertyGroup Condition="'$(_TestRuntime)' == 'Core'">
+      <_TestRunnerArgs Condition="'$(UseMicrosoftTestingPlatformRunner)' != 'true'">$(_TestRunnerArgs) -noAutoReporters</_TestRunnerArgs>
+      <_TestRunnerArgs Condition="'$(UseMicrosoftTestingPlatformRunner)' == 'true'">$(_TestRunnerArgs) --auto-reporters off</_TestRunnerArgs>
+    </PropertyGroup>
+
+    <PropertyGroup>
+      <_TestRunnerCommand>"$(_TestRunner)" $(_TestRunnerArgs)</_TestRunnerCommand>
+
+      <!--
+        Redirect std output of the runner.
+        Note that xUnit outputs failure info to both STDOUT (stack trace, message) and STDERR (failed test name)
+      -->
+      <_TestRunnerCommand Condition="'$(TestCaptureOutput)' != 'false'">$(_TestRunnerCommand) >> "%(TestToRun.ResultsStdOutPath)" 2>&amp;1</_TestRunnerCommand>
+    </PropertyGroup>
+
+    <ItemGroup>
+      <_OutputFiles Include="%(TestToRun.ResultsXmlPath)" />
+      <_OutputFiles Include="%(TestToRun.ResultsHtmlPath)" />
+      <_OutputFiles Include="%(TestToRun.ResultsStdOutPath)" />
+    </ItemGroup>
+
+    <MakeDir Directories="@(_OutputFiles->'%(RootDir)%(Directory)')"/>
+    <Delete Files="@(_OutputFiles)" />
+
+    <Message Text="Running tests: $(_TestAssembly) [$(_TestEnvironment)]" Importance="high"/>
+
+    <!--
+      Add command line to the log.
+    -->
+    <Exec Command="echo === COMMAND LINE === > %(TestToRun.ResultsStdOutPath)
+                   echo $(_TestRunnerCommand) >> %(TestToRun.ResultsStdOutPath)" />
+
+    <Exec Command='$(_TestRunnerCommand)'
+          LogStandardErrorAsError="false"
+          WorkingDirectory="$(_TargetDir)"
+          IgnoreExitCode="true"
+          Timeout="$(_TestTimeout)"
+          EnvironmentVariables="DOTNET_ROOT=$(TestDotNetRoot);DOTNET_ROOT_X86=$(TestDotNetRoot)x86"
+          ContinueOnError="WarnAndContinue">
+      <Output TaskParameter="ExitCode" PropertyName="_TestErrorCode" />
+    </Exec>
+
+    <!--
+      Report test status.
+    -->
+    <Message Text="Tests succeeded: $(_TestAssembly) [$(_TestEnvironment)]" Condition="'$(_TestErrorCode)' == '0'" Importance="high" />
+
+    <PropertyGroup>
+      <_ResultsFileToDisplay>%(TestToRun.ResultsHtmlPath)</_ResultsFileToDisplay>
+      <_ResultsFileToDisplay Condition="!Exists('$(_ResultsFileToDisplay)')">%(TestToRun.ResultsStdOutPath)</_ResultsFileToDisplay>
+    </PropertyGroup>
+
+    <!--
+      Ideally we would set ContinueOnError="ErrorAndContinue" so that when a test fails in multi-targeted test project
+      we'll still run tests for all target frameworks. ErrorAndContinue doesn't work well on Linux though: https://github.com/Microsoft/msbuild/issues/3961.
+    -->
+    <Error Text="Tests failed: $(_ResultsFileToDisplay) [$(_TestEnvironment)]" Condition="'$(_TestErrorCode)' != '0' and '$(_ErrorOnTestFailure)' != 'false'" File="XUnit" />
+
+    <ItemGroup>
+      <FileWrites Include="@(_OutputFiles)"/>
+    </ItemGroup>
+  </Target>
+
+</Project>
diff --git a/eng/testing/BionicRunOnDevice.sh b/eng/testing/BionicRunOnDevice.sh
@@ -66,4 +66,4 @@ cd "$currentDirectory" || exit 1
 if [ -e "${currentTest}.deps.json" ]; then
 	depsFileArg="--depsfile ${currentTest}.deps.json"
 fi
-$runtimeExe exec --runtimeconfig "${currentTest}".runtimeconfig.json ${depsFileArg} xunit.console.dll "${currentTest}".dll -xml testResults.xml -nologo -nocolor -notrait category=IgnoreForCI -notrait category=OuterLoop -notrait category=failing
+$runtimeExe exec --runtimeconfig "${currentTest}".runtimeconfig.json ${depsFileArg} "${currentTest}".dll -xml testResults.xml -nologo -nocolor -trait- category=IgnoreForCI -trait- category=OuterLoop -trait- category=failing
diff --git a/eng/testing/ILLink.Descriptor.xunit.xml b/eng/testing/ILLink.Descriptor.xunit.xml
@@ -1,24 +1,8 @@
-<!-- xunit 2.x version is not under development. We make xunit trimming compatible in methods which ILLink cannot track by providing XML descriptor to keep the dependencies -->
+<!-- xunit v3 trimming descriptor: preserve assemblies that ILLink cannot statically track -->
 <linker>
-  <assembly fullname="xunit.execution.dotnet">
-    <type fullname="Xunit.Sdk.ReflectionAssemblyInfo">
-      <method signature="System.Void .ctor(System.String)" />
-    </type>
-    <type fullname="Xunit.Sdk.TestFrameworkProxy">
-      <method signature="System.Void .ctor(System.Object,System.Object,System.Object)" />
-    </type>
-    <type fullname="Xunit.Sdk.FactDiscoverer" />
-    <type fullname="Xunit.Sdk.CollectionPerAssemblyTestCollectionFactory" />
-  </assembly>
-  <assembly fullname="Microsoft.DotNet.XUnitExtensions" />
-  <assembly fullname="xunit.core">
-    <namespace fullname="Xunit" />
-    <namespace fullname="Xunit.Sdk" />
-  </assembly>
-  <assembly fullname="xunit.assert">
-    <type fullname="Xunit.Sdk.CollectionTracker">
-      <method name="CompareTypedSets" />
-    </type>
-  </assembly>
-  <assembly fullname="xunit.runner.utility.netcoreapp10" />
+  <assembly fullname="xunit.v3.mtp-v2" />
+  <assembly fullname="Microsoft.DotNet.XUnitV3Extensions" />
+  <assembly fullname="xunit.v3.assert" />
+  <assembly fullname="xunit.assert" />
+  <assembly fullname="xunit.v3.runner.common" />
 </linker>