In this article, we will demonstrate getting started with xUnit.net, showing you how to write and run your first set of unit tests.
Note: The examples were done with xUnit.net v2.2 and Visual Studio 2017. The version numbers, paths, and Visual Studio UI may differ for you, depending on which version you're using.
Let's start by creating a class library project, targeting .NET 4.5.2 (or later).
Open Visual Studio, and choose
File > New > Project:
In Solution Explorer, right click the new project, and choose
Manage NuGet Packages:
Now in the NuGet package manager window, take the following steps:
nuget.orgis selected under
xUnit.netpackage, and click
This package (
xunit) is what's called a meta-package;
that is, it's a package that exists just so you can get references to several
other packages. In particular, it brings packages that include the core unit
testing framework and the assertion framework. If you open
packages.config, you'll see all the packages that get
When creating a new project with Visual Studio 2017, you may not end up with a
file. That's okay: newer versions of Visual Studio place the NuGet package references directly into your
.csproj file as
<PackageReference> elements like you see here in our
project. The advantage is that you not only have one fewer file, but you also only have packages
listed for which you've taken direct references. That makes it easier to differentiate between the
packages you've chosen to install and the dependencies they bring with them.
When you created the project, Visual Studio automatically created a file
Class1.cs and opened it for you. Inside this class, add a
Build the solution to ensure that the code compiles. Now that you've written the first test, we need a way to run it. Let's install the NuGet package with the console runner.
Once again, right click on the project in Solution Explorer and choose
Manage NuGet Packages. This time, you're going to search for
(and install) a package named
Unlike the previous package (which added references to the unit testing framework), this package is what's known as a solution-level package. Instead of having assemblies to reference, it adds some tools in your solution folder. We will use one of these tools—the console runner—to run your unit tests.
Open a command prompt or PowerShell command window. In the window, navigate to the root folder of your solution.
To run the console runner, use a command like the one highlighted below. You should see output similar to this:
> packages\xunit.runner.console.2.2.0\tools\xunit.console MyFirstUnitTests\bin\Debug\MyFirstUnitTests.dll xUnit.net Console Runner (64-bit .NET 4.0.30319.42000) Discovering: MyFirstUnitTests Discovered: MyFirstUnitTests Starting: MyFirstUnitTests MyFirstUnitTests.Class1.FailingTest [FAIL] Assert.Equal() Failure Expected: 5 Actual: 4 Stack Trace: MyFirstUnitTests\Class1.cs(16,0): at MyFirstUnitTests.Class1.FailingTest() Finished: MyFirstUnitTests === TEST EXECUTION SUMMARY === MyFirstUnitTests Total: 2, Errors: 0, Failed: 1, Skipped: 0, Time: 0.159s
Note: your path names my vary, depending on what name you chose for your project and which version of xUnit.net you installed.
The console runner has several command line options, which include options for parallelization, test filtering, and result reporting. To learn more about the console runner options, run the console runner with no command line options.
Now that we've gotten your first unit tests to run, let's introduce one more way to write tests: using theories.
You may have wondered why your first unit tests use an attribute named
[Fact] rather than one with a more traditional name like Test.
xUnit.net includes support for two different major types of unit tests:
facts and theories. When describing the difference between facts and theories,
we like to say:
Facts are tests which are always true. They test invariant conditions.
Theories are tests which are only true for a particular set of data.
A good example of this testing numeric algorithms. Let's say you want to test an algorithm which determines whether a number is odd or not. If you're writing the positive-side tests (odd numbers), then feeding even numbers into the test would cause it fail, and not because the test or algorithm is wrong.
Let's add a theory to our existing facts (including a bit of bad data, so we can see it fail):
This time when we compile and run our tests, we see a second failure, for our theory that was given 6:
xUnit.net Console Runner (64-bit .NET 4.0.30319.42000) Discovering: MyFirstUnitTests Discovered: MyFirstUnitTests Starting: MyFirstUnitTests MyFirstUnitTests.Class1.MyFirstTheory(value: 6) [FAIL] Assert.True() Failure Expected: True Actual: False Stack Trace: MyFirstUnitTests\Class1.cs(30,0): at MyFirstUnitTests.Class1.MyFirstTheory(Int32 value) MyFirstUnitTests.Class1.FailingTest [FAIL] Assert.Equal() Failure Expected: 5 Actual: 4 Stack Trace: MyFirstUnitTests\Class1.cs(16,0): at MyFirstUnitTests.Class1.FailingTest() Finished: MyFirstUnitTests === TEST EXECUTION SUMMARY === MyFirstUnitTests Total: 5, Errors: 0, Failed: 2, Skipped: 0, Time: 0.171s
Although we've only written 3 test methods, the console runner actually ran 5 tests; that's because each theory with its data set is a separate test. Note also that the runner tells you exactly which set of data failed, because it includes the parameter values in the name of the test.
Important note: If you've previously installed the xUnit.net Visual Studio
Runner VSIX (Extension), you must uninstall it first. The Visual Studio runner is only distributed
via NuGet now. To remove it, to go
Extensions and Updates.
Scroll to the bottom of the list, and if xUnit.net is installed, uninstall it. This will force
you to restart Visual Studio.
If you're having problems discovering or running tests, you may be a victim
of a corrupted runner cache inside Visual Studio. To clear this cache, shut down all instances
of Visual Studio, then delete the folder
Also make sure your solution is only linked against a single version of the Visual Studio runner
NuGet package (
If you have Visual Studio Community (or a paid-for version of Visual Studio), you can run your xUnit.net tests within Visual Studio's built-in test runner (named Test Explorer). Unfortunately, this does not include Express editions of Visual Studio (you should upgrade to the free Community Edition instead).
Right click on the project in Solution Explorer and choose
Manage NuGet Packages.
Search for (and install) a package named
Make sure Test Explorer is visible (go to
Test > Windows > Test Explorer). Every
time you build your project, the runner will discover unit tests in your project. After a moment of
discovery, you should see the list of discovered tests:
Run All link in the Test Explorer window, and you should see the results update
in the Test Explorer window as the tests are run:
You can click on a failed test to see the failure message, and the stack trace. You can click on the stack trace lines to take you directly to the failing line of code.
Note: Only xUnit.net v2 supports pre-enumeration of theories; when discovering theories with v1, it will only show a single test method for the theory.
Starting with version 2.2, the following return codes are used by the console runner:
||The tests ran successfully.|
||One or more of the tests failed.|
||The help page was shown, either because it was requested, or because the user did not provide any command line arguments.|
||There was a problem with one of the command line options passed to the runner.|
||There was a problem loading one or more of the test assemblies (for example, if a 64-bit only assembly is run with the 32-bit test runner).|
||The user canceled the test execution by pressing Ctrl+C.|