What NuGet Packages Should I Use? xUnit.net v3
xUnit.net v3 ships with many NuGet packages. This guide helps you understand which NuGet packages you should use in your projects.
If you don't know where to start, try starting with a reference to xunit.v3
.
Note
Because xUnit.net v3 injects code into your test projects to make them executable, non-unit test projects must not reference xunit.v3
(or xunit.v3.core
) and should instead reference xunit.v3.extensibility.core
to be able to provide extensions to xUnit.net v3.
Version selector: Stable (NuGet) Latest CI (feedz.io)
Packages for writing tests
Packages used by developers who are writing unit tests.
xunit.v3
This is the package that will most typically be used by unit test authors. It brings in references to xunit.v3.core
(which contains the unit testing framework), xunit.analyzers
(which contains source code analyzers), and xunit.v3.assert
(which contains the class you use to write assertions).
Latest Introduced 1.0 Targets net472
,net8.0
Depends on xunit.v3.assert
,xunit.v3.core
,xunit.analyzers
xunit.v3.assert
This package contains the xUnit.net assertion library (i.e., the Assert
class).
This is a separate NuGet package, because some developers wish to use the xUnit.net framework and test runners, but with a different assertion library.
Note
If you want to extend the Assert
class, you should consider using the xunit.v3.assert.source
package instead.
Latest Introduced 1.0 Targets netstandard2.0
,net8.0
xunit.v3.core
This package contains the core types for the test framework (f.e., FactAttribute
).
Referencing this package provides the required infrastructure to be able to write unit tests, including the injection of the entry point that is required to make all v3 test projects stand-alone executables.
Note
This package should only be used by unit test projects. If you wish to extend xUnit.net or create a base library consumed by unit test projects, then you should reference xunit.v3.extensibility.core
instead.
Latest Introduced 1.0 Targets net472
,net8.0
Depends on xunit.v3.extensibility.core
,xunit.v3.runner.inproc.console
xunit.v3.templates
This package provides templates for dotnet new
to support xUnit.net v3 test projects and xUnit.net v3 extensibility projects.
To install this package, run: dotnet new install xunit.v3.templates
. This will add two new templates (xunit3
and xunit3-extension
) for C#, F#, and VB.NET.
Latest Introduced 1.0 Targets xunit3: net8.0
,net9.0
,net472
,net48
,net481
xunit3-extension:netstandard2.0
,net8.0
,net9.0
,net472
,net48
,net481
xunit.analyzers
This package contains the xUnit.net source code analyzers.
This library provides code analysis and code fixers for common issues that are encountered both by test authors and extensibility authors. It's based on the .NET Compiler Platform ("Roslyn") analyzers which can provide real-time source code analysis inside IDEs (including Visual Studio and Visual Studio Code), as well as compile-time source code analysis.
Latest Introduced 1.0 Targets Roslyn 3.11+ (Visual Studio 2019 16.11+)
Packages for running tests
Packages used by developers who are running unit tests.
xunit.v3.runner.console
This package contains the console test runner. This runner is capable of running .NET Framework and .NET projects from xUnit.net v3, as well as .NET Framework projects from xUnit.net v1 and v2. It can run multiple test projects in parallel.
Note
Note: we ship runners targeting multiple versions of .NET Framework, because xUnit.net v1 and v2 projects are loaded into runner process, so the version of .NET Framework that the runner is built against determines the version of .NET Framework that the tests will run against (and more importantly, the features available). We also ship AnyCPU versions as well as versions which are built for 32-bit x86. Since xUnit.net v3 projects are stand-alone executables, they will run with whatever version (and bitness) of .NET or .NET Framework that they were built against regardless of the runner's version.
Latest Introduced 1.0 Targets net472
(v1/v2/v3),net8.0
(v3)
xunit.v3.runner.msbuild
This package contains the MSBuild test runner. This runner is capable of running .NET Framework and .NET projects from xUnit.net v3, as well as .NET Framework projects from xUnit.net v1 and v2. It can run multiple test projects in parallel.
Note
For xUnit.net v3 projects, this runner can be used from both msbuild.exe
as well as dotnet msbuild
. For xUnit.net v1/v2 projects, this runner only supports being run from msbuild.exe
.
Latest Introduced 1.0 Targets net472
(v1/v2/v3),net8.0
(v3)
xunit.runner.visualstudio
This package contains the adapter to run tests via VSTest. This runner is capable of running .NET Framework projects from xUnit.net v1/v2/v3, and .NET projects from xUnit.net v2/v3. (Support for v3 requires using runner version 3.0 or later.)
The VSTest framework is used by several 3rd party runners, including:
- Visual Studio (via Test Explorer)
- Visual Studio Code (via the Testing panel)
dotnet test
anddotnet vstest
vstest.console.exe
Latest Introduced 1.0 Targets net472
(v1/v2/v3),net8.0
(v2/v3)
Packages for extending xUnit.net
Packages used by developers who are extending xUnit.net and/or creating unit test runners.
xunit.v3.assert.source
This package contains the xUnit.net assertion library (i.e., the Assert
class) in source form. The Assert
class is a partial class, which allows developers to write additional methods available directly from Assert
.
When you have multiple unit test libraries in your project, it is common practice to import this package into a "test utility" library where you write all your custom assertions, and then reference that "test utility" library from your unit test projects.
For more information, see the xunit/assert.xunit
README
Latest Introduced 1.0 Targets netstandard1.1
with C# 6 or later
xunit.v3.extensibility.core
This package contains xunit.v3.core.dll
. It is intended to be used by developers who wish to reference this DLL for extensibility purposes, such as writing your own theory data provider.
This package is referenced by xunit.v3.core
. It differs in that it does not include the MSBuild steps required to make the project an executable test project.
Latest Introduced 1.0 Targets netstandard2.0
Depends on xunit.v3.common
xunit.v3.runner.inproc.console
This package contains the code that provides the command line UI for running xUnit.net v3 projects as stand-alone executables. This includes both the native xUnit.net command line UX as well as the Microsoft Testing Platform command line UX.
Latest Introduced 1.0 Targets net472
,net8.0
Depends on xunit.v3.extensibility.core
,xunit.v3.runner.common
xunit.v3.runner.utility
This package contains xunit.v3.runner.utility.*.dll
. It is intended to be used by developers who are writing their own test runners.
The libraries contained here are both backward and forward compatible for all v1, v2, and v3 xUnit.net tests.
Latest Introduced 1.0 Targets net472
,net8.0
Depends on xunit.abstractions
,xunit.v3.runner.common
Packages for shared code
Packages that contain types that are shared among packages in other categories. Not typically directly referenced.
xunit.v3.common
This package contains types that are shared between xunit.v3.core
and xunit.v3.runner.common
.
Latest Introduced 1.0 Targets netstandard2.0
xunit.v3.runner.common
This package contains types that are shared between xunit.v3.runner.inproc.console
and xunit.v3.runner.utility
.
Latest Introduced 1.0 Targets netstandard2.0
Depends on xunit.v3.common
xunit.abstractions
This package contains common interfaces used by various parts of xUnit.net v2. It is used by xunit.v3.runner.utility
to be able to run xUnit.net v2 test projects.
Latest Introduced 1.0 Targets net35
,netstandard1.0