From c679ad3c158492dde4c4667c068fe5849256ff7b Mon Sep 17 00:00:00 2001
From: Thomas Bruderer <apophis@apophis.ch>
Date: Thu, 29 Oct 2026 14:41:03 +0100
Subject: [PATCH] Accept xUnit.net v3 1.x through 4.x in Funcky.Xunit.v3

The package was pinned to xunit.v3 [1.0.1, 2) although nothing it uses
(Assert, XunitException, ArgumentFormatter, IXunitSerializer,
SerializationHelper) changed in the 2.0, 3.0 and 4.0 releases; the
breaking changes there are in the runner and extensibility pipeline.
The range is now [1.0.1, 5), still compiled against 1.0.1, and the test
suite passes against 4.0.2 at runtime.

The xunit chapter gains a compatibility table with the test host and
runner requirements of each xunit.v3 major, including the VSTest opt-in
needed on the .NET 10 SDK with 4.x.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 Directory.Packages.props   |  4 ++--
 Documentation/src/xunit.md | 37 +++++++++++++++++++++++++++++++++----
 Funcky.Xunit.v3/package.md |  2 +-
 changelog.md               |  5 +++++
 4 files changed, 41 insertions(+), 7 deletions(-)

diff --git a/Directory.Packages.props b/Directory.Packages.props
index 8c960fe8..e9011185 100644
--- a/Directory.Packages.props
+++ b/Directory.Packages.props
@@ -9,8 +9,8 @@
     <PackageVersion Include="System.Text.Json" Version="5.0.2" />
     <PackageVersion Include="xunit.assert" Version="[2.9.3, 2.10)" />
     <PackageVersion Include="xunit.extensibility.core" Version="[2.9.3, 2.10)" />
-    <PackageVersion Include="xunit.v3.assert" Version="[1.0.1, 2)" />
-    <PackageVersion Include="xunit.v3.extensibility.core" Version="[1.0.1, 2)" />
+    <PackageVersion Include="xunit.v3.assert" Version="[1.0.1, 5)" />
+    <PackageVersion Include="xunit.v3.extensibility.core" Version="[1.0.1, 5)" />
     <!-- Funcky.Async compiles against the 5.x operator vocabulary (SelectAwait, SelectAwaitWithCancellation, ...) and is
 		     binary compatible with 6.x. System.Linq.Async 7 is a legacy shim over System.Linq.AsyncEnumerable with the .NET 10
 		     operator shapes only, so it has none of the members Funcky.Async binds to; the upper bound keeps NuGet from resolving
diff --git a/Documentation/src/xunit.md b/Documentation/src/xunit.md
index 5389d913..5294d18c 100644
--- a/Documentation/src/xunit.md
+++ b/Documentation/src/xunit.md
@@ -8,10 +8,10 @@ assert the case, get the content back.
 
 ## Which package
 
-| xUnit.net version | Package                                                               |
-|-------------------|-----------------------------------------------------------------------|
-| 2.x               | [`Funcky.Xunit`](https://www.nuget.org/packages/Funcky.Xunit)         |
-| 3.x               | [`Funcky.Xunit.v3`](https://www.nuget.org/packages/Funcky.Xunit.v3)   |
+| xUnit.net version     | Package                                                             |
+|-----------------------|---------------------------------------------------------------------|
+| 2.x                   | [`Funcky.Xunit`](https://www.nuget.org/packages/Funcky.Xunit)       |
+| v3, 1.x through 4.x   | [`Funcky.Xunit.v3`](https://www.nuget.org/packages/Funcky.Xunit.v3) |
 
 Both packages share the assertions below and differ only in the theory-data helpers at the end of this chapter.
 The assertions are static extension members of xunit's `Assert`, declared in `Funcky.Extensions.AssertExtensions`,
@@ -28,6 +28,35 @@ the `Funcky.FunctionalAssert` class, `FunctionalAssert.Some(42, option)`. The tw
 `Assert` members are the implementation and `FunctionalAssert` forwards to them. If both are available,
 [λ1203](./analyzer-rules/λ1203.md) asks for the `Assert` form and comes with a code fix.
 
+### xUnit.net 3.x versions
+
+xUnit.net v3 has had three major releases since 1.0, each breaking binary compatibility with the previous one for
+extensibility authors. Funcky.Xunit.v3 is unaffected: it uses only `Assert`, `XunitException`, `ArgumentFormatter`
+and the serializer interfaces, none of which changed. The package is compiled against `xunit.v3.assert` and
+`xunit.v3.extensibility.core` 1.0.1 and declares the range `[1.0.1, 5)`, so NuGet takes whichever version your test
+project references.
+
+What does change between the xunit versions is the test host and the runner, not Funcky. In particular, with the
+.NET 10 SDK, xunit.v3 4.x no longer runs under VSTest unless you opt in, which also affects the Azure DevOps
+`DotNetCoreCLI@2` task.
+
+| xunit.v3 | Funcky.Xunit.v3                   | Test project runs on           | `dotnet test` with the .NET 10 SDK                                                |
+|----------|-----------------------------------|--------------------------------|-----------------------------------------------------------------------------------|
+| 1.x      | 1.0.0 and later                   | .NET 6+, .NET Framework 4.7.2+ | VSTest (`xunit.runner.visualstudio`) or Microsoft.Testing.Platform v1             |
+| 2.x      | 1.2.0 and later, expected to work | .NET 8+, .NET Framework 4.7.2+ | VSTest or Microsoft.Testing.Platform v1                                           |
+| 3.x      | 1.2.0 and later, expected to work | .NET 8+, .NET Framework 4.7.2+ | VSTest or Microsoft.Testing.Platform v1                                           |
+| 4.x      | 1.2.0 and later, verified         | .NET 8+, .NET Framework 4.7.2+ | Microsoft.Testing.Platform v2; VSTest only with the `xunit.v3.*.mtp-off` packages |
+
+"Verified" means Funcky's own test suite runs green against that version. "Expected to work" means nothing in the
+xunit release notes touches what Funcky uses, but the suite is not run against it yet
+([#1015](https://github.com/polyadic/funcky/issues/1015) tracks a matrix build). The test host column is xunit's
+minimum; Funcky.Xunit.v3 itself targets `netstandard2.0` and `net6.0`.
+
+If `dotnet test` on the .NET 10 SDK stops with "Testing with VSTest target is no longer supported by
+Microsoft.Testing.Platform", either opt into Microsoft.Testing.Platform in `global.json`
+(`"test": { "runner": "Microsoft.Testing.Platform" }`) or reference the `mtp-off` variants of the xunit packages. A
+v3 test project is an executable, so `dotnet run --project` works whichever runner the SDK prefers.
+
 ## The assertions
 
 Each monad gets one assertion per case. The assertion for the case that carries a value comes in two overloads:
diff --git a/Funcky.Xunit.v3/package.md b/Funcky.Xunit.v3/package.md
index d51d0dc9..965f92e0 100644
--- a/Funcky.Xunit.v3/package.md
+++ b/Funcky.Xunit.v3/package.md
@@ -1,5 +1,5 @@
 ## About
-Provides expressive assertions for xUnit.net 3.x that unpack [Funcky]'s monads.
+Provides expressive assertions for xUnit.net v3 (1.x to 4.x) that unpack [Funcky]'s monads.
 
 It also enables `Option`, `Either` and `Unit` for use in theory data by providing
 custom [serializers].
diff --git a/changelog.md b/changelog.md
index 40cadca5..7946d328 100644
--- a/changelog.md
+++ b/changelog.md
@@ -49,6 +49,11 @@ Funcky adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   `Assert.Ok(result)`, `Assert.Error(result)`, `Assert.Left(either)` and `Assert.Right(either)`; `Some`, `Ok`, `Left` and `Right`
   also come with the overload that takes the expected value. They delegate to `FunctionalAssert`, which stays the form for compilers older than
   C# 14 (the members are declared in `AssertExtensions`).
+* Funcky.Xunit.v3 now accepts xUnit.net v3 1.x through 4.x (`xunit.v3.assert` and `xunit.v3.extensibility.core`
+  `[1.0.1, 5)`, previously `[1.0.1, 2)`). The package is still compiled against 1.0.1; the types it uses (`Assert`,
+  `XunitException`, `ArgumentFormatter`, `IXunitSerializer`, `SerializationHelper`) are unchanged in 2.0, 3.0 and 4.0,
+  and the test suite passes against 4.0.2. The [Testing with xUnit](https://polyadic.github.io/funcky/xunit.html#xunitnet-3x-versions)
+  chapter has a compatibility table with the test host and runner requirements of each xunit version.
 * The asynchronous overloads of `AdjacentGroupBy`, `Chunk`, `ExclusiveScan`, `InclusiveScan`, `Inspect` and `WhereSelect`
   now follow the .NET 10 naming of `System.Linq.AsyncEnumerable`: one name per operator, with the asynchronous delegate
   taking the cancellation token of the enumeration, `xs.Inspect(async (item, cancellationToken) => …)`. This applies to