Why is an xunit.v3 test project built as an executable, and which packages and project settings does it need?
answer
- the runner lives inside the test assembly
- <OutputType>Exe</OutputType> or the build fails
- UseAppHost and a generated entry point
- xunit.v3 brings xunit.v3.mtp-v2
- xunit.v3.mtp-off for VSTest only
basics
~20 sIn xunit.v3 every test project is its own runnable program: the package generates an entry point and the build fails unless OutputType is Exe. Reference xunit.v3, which brings Microsoft.Testing.Platform v2, or xunit.v3.mtp-off when the project must run on VSTest only.
solid answer
~40 sxunit.v3 moves the test runner into the test project. The package's build targets add a generated entry point (`XunitAutoGeneratedEntryPoint`), switch off `Microsoft.NET.Test.Sdk`'s `GenerateProgramFile`, force `UseAppHost` on .NET, and stop the build with "xUnit.net v3 test projects must be executable (set project property '<OutputType>Exe</OutputType>')" when the project is still a library. The result can be started with `dotnet run`, by launching the built executable, or through `dotnet test` and Test Explorer. For packages, reference `xunit.v3`, which depends on `xunit.v3.mtp-v2` (core on Microsoft.Testing.Platform v2, `xunit.v3.assert` and `xunit.analyzers`); choose `xunit.v3.mtp-off` plus `Microsoft.NET.Test.Sdk` and `xunit.runner.visualstudio` to stay on VSTest only. A shared library of custom attributes or fixtures that is not itself a test project references `xunit.v3.extensibility.core` instead. Targets are .NET 8 or later and .NET Framework 4.7.2 or later.
code
xml · 19 lines<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<OutputType>Exe</OutputType>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>
<ItemGroup>
<Using Include="Xunit" />
<PackageReference Include="xunit.v3" Version="4.0.1" />
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\Ticketing\Ticketing.csproj" />
</ItemGroup>
</Project>go deeper
Remember that an xunit.v3 test project is an executable with OutputType Exe and a reference to the xunit.v3 package.
Explain what the package's build targets add (entry point, app host, validation) and the difference between xunit.v3, xunit.v3.mtp-off and xunit.v3.extensibility.core.
Plan project layout and CI around executables: helper libraries on extensibility.core, the VSTest-only variant where tooling demands it, and direct execution for focused reruns.
Decide a solution-wide test platform strategy (Microsoft.Testing.Platform or VSTest) and when the executable model's isolation justifies the migration cost.
## From library to program In xUnit.net v2 the test assembly never ran itself. Something else, the Visual Studio adapter `xunit.runner.visualstudio` inside the test host or a console runner, loaded the compiled test DLL, discovered the tests by reflection and ran them in its own process. xunit.v3 turns this around: **the test project is the program**. The runner code ships inside the test assembly, so the build output is an executable that discovers and runs its own tests. That is why the same project can be started several ways and why each project carries exactly the runner version it was built against. ## What the package does to the build The `xunit.v3.core` build files, pulled in through `xunit.v3`, change the project in these ways: - **Validation.** A target that runs before the build stops with "xUnit.net v3 test projects must be executable (set project property '<OutputType>Exe</OutputType>'). If this is not a test project, reference xunit.v3.extensibility.core instead." - **App host.** `UseAppHost` is forced to `true` on .NET, because the runner utilities launch the produced executable; turning it off produces a matching build error. - **Entry point.** An `XunitAutoGeneratedEntryPoint` source file with `Main` is generated into the intermediate folder. Setting `XunitAutoGeneratedEntryPoint` to `false` lets you write your own. - **No competing `Main`.** `GenerateProgramFile` is set to `false`, so `Microsoft.NET.Test.Sdk` does not add a second entry point when it is referenced. - **Markers.** `IsTestingPlatformApplication` and `TestProject` are set to `true`, so tooling recognises the project as a test application. The minimum project file is therefore an ordinary console-style project with `<OutputType>Exe</OutputType>` and one package reference. ## The package choices | Package id | Runs on | Typical companions | |---|---|---| | `xunit.v3` | Microsoft.Testing.Platform v2, through its dependency `xunit.v3.mtp-v2` | none needed | | `xunit.v3.mtp-v2` | the same, referenced directly (what the `xunit3` template uses) | none needed | | `xunit.v3.mtp-off` | VSTest only | `Microsoft.NET.Test.Sdk`, `xunit.runner.visualstudio` | | `xunit.v3.extensibility.core` | not a test project | for libraries of custom attributes, fixtures or orderers | `xunit.v3.mtp-v2` itself depends on `xunit.v3.core.mtp-v2`, `xunit.v3.assert` and `xunit.analyzers`, so assertions and analyzers come along without extra references. The 4.x line ships only the `mtp-v2` and `mtp-off` variants. ## Ways to run it 1. **`dotnet run`** in the project folder builds and starts the executable, which runs every test and prints a summary. 2. **The executable directly**, for example `bin/Release/net8.0/Ticketing.Tests`, which is handy on a build agent or in a container. 3. **`dotnet test`** and IDE test explorers, which talk to the executable through Microsoft.Testing.Platform or, with `xunit.v3.mtp-off`, through VSTest. How `dotnet test` chooses between the two is SDK configuration and a separate topic. The native command line accepts filters and switches of its own, such as `-class`, `-method`, `-trait` and `-explicit`, so a single failing class can be rerun without any other tooling. ## Variants worth knowing - **Native AOT.** A separate package, `xunit.v3.aot.mtp-v2`, builds the tests for Native AOT with `PublishAot`; its build targets reject anything but C# with "xUnit.net v3 Native AOT only supports C# at this time". - **.NET Framework targets.** For `net472` to `net481` the package turns on `AutoGenerateBindingRedirects` and full debug symbols, which the executable needs to resolve assembly versions at run time. - **Custom entry points.** With `XunitAutoGeneratedEntryPoint` set to `false`, the project supplies its own `Main`, for example to set process-wide state before any test runs. ## Practical consequences - **One executable per test project.** A solution with five test projects produces five test programs; each can run alone. - **The target framework matters at build time.** xunit.v3 supports .NET 8 or later and .NET Framework 4.7.2 or later; older targets must stay on v2. - **Helper libraries must not reference `xunit.v3`.** A shared library of fixtures that references the full package inherits the executable requirement and fails to build as a library; it should reference `xunit.v3.extensibility.core`. - **A custom `Main` needs the opt-out.** Projects that need their own startup code set `XunitAutoGeneratedEntryPoint` to `false` and call the runner themselves.
- A shared project with custom fixtures fails to build after referencing xunit.v3. Why?The `xunit.v3` package's build targets treat any project that references it as a test project and demand `<OutputType>Exe</OutputType>`. A helper library is not a test project, so it should reference `xunit.v3.extensibility.core`, which carries the fixture and attribute types without the executable requirement. The error message itself suggests exactly that.
- When would you pick xunit.v3.mtp-off over xunit.v3?When the pipeline or IDE must keep using VSTest, for example a CI step built around VSTest options or an environment that cannot use Microsoft.Testing.Platform yet. `xunit.v3.mtp-off` omits Microsoft.Testing.Platform, and you add `Microsoft.NET.Test.Sdk` and `xunit.runner.visualstudio` as in v2. The project is still an executable.
- With the xunit.v3 package, a test project builds fine without OutputType Exe.
- Every xunit.v3 test project must reference xunit.runner.visualstudio.
- A helper library of fixtures should reference the full xunit.v3 package.
- xunit.v3 runs on any .NET Framework version that v2 supported.
- You must write your own Main method for an xunit.v3 test project.
Assumes xunit.v3 4.x (the "v3" product line with 4.x packages); xUnit.net v2 test assemblies were loaded and run by an external runner such as xunit.runner.visualstudio.