dotnet · agocke · Jan 16, 2026 · Jan 17, 2026 · Jan 18, 2026 · Jan 18, 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
@@ -28,7 +28,7 @@ This file should be imported by eng/Versions.props
     <MicrosoftDotNetRemoteExecutorPackageVersion>11.0.0-beta.26166.111</MicrosoftDotNetRemoteExecutorPackageVersion>
     <MicrosoftDotNetSharedFrameworkSdkPackageVersion>11.0.0-beta.26166.111</MicrosoftDotNetSharedFrameworkSdkPackageVersion>
     <MicrosoftDotNetXliffTasksPackageVersion>11.0.0-beta.26166.111</MicrosoftDotNetXliffTasksPackageVersion>
-    <MicrosoftDotNetXUnitAssertPackageVersion>2.9.3-beta.26166.111</MicrosoftDotNetXUnitAssertPackageVersion>
+    <MicrosoftDotNetXUnitAssertPackageVersion>3.2.2-beta.26168.106</MicrosoftDotNetXUnitAssertPackageVersion>
     <MicrosoftDotNetXUnitConsoleRunnerPackageVersion>2.9.3-beta.26166.111</MicrosoftDotNetXUnitConsoleRunnerPackageVersion>
     <MicrosoftDotNetXUnitExtensionsPackageVersion>11.0.0-beta.26166.111</MicrosoftDotNetXUnitExtensionsPackageVersion>
     <MicrosoftNetCompilersToolsetPackageVersion>5.6.0-2.26166.111</MicrosoftNetCompilersToolsetPackageVersion>

diff --git a/eng/Version.Details.xml b/eng/Version.Details.xml
@@ -71,9 +71,9 @@
       <Uri>https://github.com/dotnet/dotnet</Uri>
       <Sha>3ccdcc4cf9b93bf3504275d4506144cf68c15b2c</Sha>
     </Dependency>
-    <Dependency Name="Microsoft.DotNet.XUnitAssert" Version="2.9.3-beta.26166.111">
+    <Dependency Name="Microsoft.DotNet.XUnitAssert" Version="3.2.2-beta.26168.106">
       <Uri>https://github.com/dotnet/dotnet</Uri>
-      <Sha>3ccdcc4cf9b93bf3504275d4506144cf68c15b2c</Sha>
+      <Sha>803eb28628f5623c108f1bf33504c86e19815821</Sha>
     </Dependency>
     <Dependency Name="Microsoft.DotNet.XUnitExtensions" Version="11.0.0-beta.26166.111">
       <Uri>https://github.com/dotnet/dotnet</Uri>

diff --git a/eng/Versions.props b/eng/Versions.props
@@ -157,7 +157,7 @@
     <MoqVersion>4.18.4</MoqVersion>
     <MicrosoftDiagnosticsRuntimeVersion>3.1.512801</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/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-v1" />
+  <assembly fullname="Microsoft.DotNet.XUnitV3Extensions" />
+  <assembly fullname="xunit.v3.assert" />
+  <assembly fullname="Microsoft.DotNet.XUnitAssert" />
+  <assembly fullname="xunit.v3.runner.common" />
 </linker>
diff --git a/eng/testing/RunnerTemplate.cmd b/eng/testing/RunnerTemplate.cmd
@@ -44,6 +44,8 @@ set EXECUTION_DIR=%~dp0
 :: Assume failure
 set HAS_TEST_RESULTS=0
 
+set DOTNET_ROOT=%RUNTIME_PATH%
+
 :: Support for SuperPMI collection
 REM SuperPMI collection
 if not defined spmi_enable_collection goto :skip_spmi_enable_collection

diff --git a/eng/testing/RunnerTemplate.sh b/eng/testing/RunnerTemplate.sh
@@ -45,6 +45,8 @@ if [[ -z "$RUNTIME_PATH" ]]; then
   exit -1
 fi
 
+export DOTNET_ROOT="$RUNTIME_PATH"
+
 exitcode_list[0]="Exited Successfully"
 exitcode_list[130]="SIGINT  Ctrl-C occurred. Likely tests timed out."
 exitcode_list[131]="SIGQUIT Ctrl-\ occurred. Core dumped."

diff --git a/eng/testing/tests.singlefile.targets b/eng/testing/tests.singlefile.targets
@@ -50,9 +50,9 @@
   </ItemGroup>
 
   <ItemGroup>
-    <Compile Include="$(CommonTestPath)SingleFileTestRunner\SingleFileTestRunner.cs"
+    <!-- <Compile Include="$(CommonTestPath)SingleFileTestRunner\SingleFileTestRunner.cs"
              Link="Common\SingleFileTestRunner\SingleFileTestRunner.cs"
-             Condition="'$(CLRTestKind)' == '' and '$(IsFunctionalTest)' != 'true'" />
+             Condition="'$(CLRTestKind)' == '' and '$(IsFunctionalTest)' != 'true'" /> -->
   </ItemGroup>
 
   <ItemGroup>

diff --git a/eng/testing/xunit/xunit.console.targets b/eng/testing/xunit/xunit.console.targets
@@ -16,23 +16,33 @@
     <SetScriptCommands Include="$(EnvVarCommand) XUNIT_HIDE_PASSING_OUTPUT_DIAGNOSTICS=1" />
   </ItemGroup>
 
+  <!-- xunit v3: The test executable needs execute permission on Unix after ZIP extraction on Helix. -->
+  <ItemGroup Condition="'$(TargetFrameworkIdentifier)' == '.NETCoreApp' and
+                         '$(RunScriptWindowsCmd)' != 'true' and
+                         '$(TargetsMobile)' != 'true' and
+                         '$(TestSingleFile)' != 'true'">
+    <SetScriptCommands Include="chmod +x $EXECUTION_DIR/$(AssemblyName)" />
+  </ItemGroup>
+
   <PropertyGroup Condition="'$(BundleXunitRunner)' == 'true'">
     <XunitConsolePath Condition="'$(TargetFrameworkIdentifier)' == '.NETCoreApp'">xunit.console.dll</XunitConsolePath>
     <XunitConsolePath Condition="'$(TargetFrameworkIdentifier)' == '.NETFramework'">xunit.console.exe</XunitConsolePath>
   </PropertyGroup>
 
   <PropertyGroup Condition="'$(TargetsMobile)' != 'true' and '$(TestSingleFile)' != 'true'">
-    <_depsFileArgument Condition="'$(GenerateDependencyFile)' == 'true'">--depsfile $(AssemblyName).deps.json</_depsFileArgument>
-    <RunScriptCommand Condition="'$(TargetFrameworkIdentifier)' == '.NETCoreApp'">"$(RunScriptHost)" exec --runtimeconfig $(AssemblyName).runtimeconfig.json $(_depsFileArgument) $(XunitConsolePath)</RunScriptCommand>
-    <RunScriptCommand Condition="'$(TargetFrameworkIdentifier)' == '.NETFramework'">$(XunitConsolePath)</RunScriptCommand>
+    <!--
+      xunit v3: All test projects (both .NETCoreApp and .NETFramework) produce
+      executables with an embedded in-process runner.  Run them directly.
+    -->
+    <RunScriptCommand Condition="'$(RunScriptWindowsCmd)' != 'true'">./$(AssemblyName)</RunScriptCommand>
+    <RunScriptCommand Condition="'$(RunScriptWindowsCmd)' == 'true'">$(AssemblyName).exe</RunScriptCommand>
 
-    <RunScriptCommand>$(RunScriptCommand) $(TargetFileName)</RunScriptCommand>
     <RunScriptCommand>$(RunScriptCommand) -xml $(TestResultsName)</RunScriptCommand>
-    <RunScriptCommand>$(RunScriptCommand) -nologo</RunScriptCommand>
-    <RunScriptCommand Condition="'$(ArchiveTests)' == 'true'">$(RunScriptCommand) -nocolor</RunScriptCommand>
+    <RunScriptCommand>$(RunScriptCommand) -noLogo</RunScriptCommand>
+    <RunScriptCommand Condition="'$(ArchiveTests)' == 'true'">$(RunScriptCommand) -noColor</RunScriptCommand>
     <RunScriptCommand Condition="'$(TargetFrameworkIdentifier)' == '.NETFramework' and '$(TestDisableAppDomain)' == 'true'">$(RunScriptCommand) -noappdomain</RunScriptCommand>
-    <RunScriptCommand Condition="'$(TestDisableParallelization)' == 'true'">$(RunScriptCommand) -maxthreads 1</RunScriptCommand>
-    <RunScriptCommand Condition="'$(XUnitShowProgress)' == 'true'">$(RunScriptCommand) -verbose</RunScriptCommand>
+    <RunScriptCommand Condition="'$(TestDisableParallelization)' == 'true'">$(RunScriptCommand) -maxThreads 1</RunScriptCommand>
+    <RunScriptCommand Condition="'$(XUnitShowProgress)' == 'true'">$(RunScriptCommand) -reporter verbose</RunScriptCommand>
   </PropertyGroup>
 
   <PropertyGroup Condition="'$(UseXunitExcludesTxtFile)' != 'true'">
@@ -42,7 +52,7 @@
 
     <!-- Add to run argument string -->
     <RunScriptCommand>$(RunScriptCommand)$(_withCategories.Replace(';', ' -trait category='))</RunScriptCommand>
-    <RunScriptCommand>$(RunScriptCommand)$(_withoutCategories.Replace(';', ' -notrait category='))</RunScriptCommand>
+    <RunScriptCommand>$(RunScriptCommand)$(_withoutCategories.Replace(';', ' -trait- category='))</RunScriptCommand>
 
     <!-- User passed in options. -->
     <RunScriptCommand Condition="'$(XUnitOptions)' != ''">$(RunScriptCommand) $(XUnitOptions)</RunScriptCommand>
@@ -58,9 +68,6 @@
   </PropertyGroup>
 
   <ItemGroup Condition="'$(TestSingleFile)' != 'true'">
-    <PackageReference Include="Microsoft.DotNet.XUnitConsoleRunner"
-                      Version="$(MicrosoftDotNetXUnitConsoleRunnerVersion)"
-                      Condition="'$(TargetFrameworkIdentifier)' == '.NETCoreApp'" />
     <PackageReference Include="xunit.runner.console"
                       Version="$(XUnitVersion)"
                       GeneratePathProperty="true"
@@ -83,7 +90,7 @@
   </Target>
 
   <!-- ResolveAssemblyReferences is the target that populates ReferenceCopyLocalPaths which is what is copied to output directory. -->
-  <Target Name="CopyRunnerToOutputDirectory" BeforeTargets="ResolveAssemblyReferences" Condition="'$(BundleXunitRunner)' == 'true'">
+  <Target Name="CopyRunnerToOutputDirectory" BeforeTargets="ResolveAssemblyReferences" Condition="'$(BundleXunitRunner)' == 'true' and '$(TargetFrameworkIdentifier)' != '.NETCoreApp'">
     <ItemGroup>
       <None Include="$([System.IO.Path]::GetDirectoryName('$(XunitConsole472Path)'))\*"
             Exclude="$([System.IO.Path]::GetDirectoryName('$(XunitConsole472Path)'))\xunit.console.*exe.config;