How to Run Your First xUnit Test Script
Create and run your first xUnit test in .NET. Follow the xUnit.net v3 command-line path, understand v2 differences, and fix common first-run errors.
The quickest route for a new project is to install the .NET SDK, create an xUnit.net v3 test project, and run it with dotnet run. If you already have an xUnit.net v2 project, use its dotnet new xunit and dotnet test workflow instead; v2 and v3 templates and runner setup are not interchangeable. The commands below follow the official documentation examples, whose SDK and package versions may differ from yours.
1. Check that the .NET SDK is installed
Open a new terminal or command prompt and run:
dotnet --versionThe command should print an installed SDK version. The official guide shows 10.0.102 as an example; you do not need that exact version. If the shell says dotnet is not recognized or not found, install the .NET SDK for your operating system, then open a fresh terminal and try again. The SDK includes the CLI used to create and run the project. See Microsoft’s .NET installation instructions.
2. Create a new xUnit.net v3 project
For a new project, install the xUnit.net v3 templates and create a standard test project:
dotnet new install xunit.v3.templates
mkdir MyFirstUnitTests
cd MyFirstUnitTests
dotnet new xunit3The template package provides xunit3 and xunit3-extension templates, with C#, F#, and VB.NET support. Use xunit3 for a normal test project. The template restores project dependencies during creation; if restore did not complete, run dotnet restore from the project directory.
Open the generated project and inspect UnitTest1.cs. A typical starter test resembles:
namespace MyFirstUnitTests;
public class UnitTest1
{
[Fact]
public void Test1()
{
Assert.True(true);
}
}The generated assertion is a placeholder. Replace it with a check that describes behavior your application needs. The generated project settings depend on the installed SDK and template version. The documented default v3 project targets net8.0, has OutputType set to Exe, enables TestingPlatformDotnetTestSupport, and includes xunit.runner.json. Use the files generated on your machine as the source of truth for your runner configuration.
3. Run the first test
From the directory containing the test project, run:
dotnet runA successful run reports test discovery and execution, with the number of tests and zero errors or failures. Exact wording, timing, and counts vary by template and SDK. If the project is configured for the VSTest runner instead, use the command documented for that configuration; do not assume every v3 project uses the same runner.
4. Replace the placeholder with a useful assertion
A test should exercise behavior that matters. Here is a small runnable example that tests an addition method. Replace the contents of UnitTest1.cs with:
namespace MyFirstUnitTests;
public class Calculator
{
public static int Add(int left, int right) => left + right;
}
public class CalculatorTests
{
[Fact]
public void Add_ReturnsTheSumOfTwoNumbers()
{
Assert.Equal(4, Calculator.Add(2, 2));
}
}Run dotnet run again. A passing result means the assertion held for this input. To see how a failure is reported, temporarily change the expected value from 4 to 5, run again, and read the expected value, actual value, and source location in the diagnostic output. Restore the correct expectation afterward. Deliberately failing the assertion is a way to learn the output, not a test to leave failing.
5. Use facts and theories appropriately
A [Fact] checks one case or invariant. xUnit.net’s guide puts it this way: “Facts are tests which are always true. They test invariant conditions.” A [Theory] applies the same test logic to supplied data, which is useful when one behavior has several input cases.
namespace MyFirstUnitTests;
public class CalculatorTests
{
[Theory]
[InlineData(2, 2, 4)]
[InlineData(-1, 1, 0)]
[InlineData(0, 0, 0)]
public void Add_ReturnsTheSum(int left, int right, int expected)
{
Assert.Equal(expected, Calculator.Add(left, right));
}
}Each [InlineData] row is a separate case. When a case fails, the runner output can identify the input row that failed. Keep test names and data specific enough that a failure points you toward the behavior to inspect.
6. Know which xUnit version and runner your project uses
For an existing project, inspect its .csproj and follow the setup that matches its package references and runner. The main documented paths are:
| Project setup | Template command | Typical first run | Notes |
|---|---|---|---|
| New xUnit.net v3, Microsoft Testing Platform template | dotnet new xunit3 |
dotnet run |
The current getting-started guide uses this route. Follow the generated project configuration. |
| xUnit.net v3 configured for VSTest | dotnet new xunit3 with the VSTest option |
Use the runner’s documented command, commonly dotnet test |
The VSTest configuration adds runner support packages. Check the template options and generated project. |
| Existing xUnit.net v2 project | dotnet new xunit for a new v2 project |
dotnet test |
The documented VSTest path references xunit, xunit.runner.visualstudio, and Microsoft.NET.Test.Sdk. Keep an existing project on its configured path. |
xUnit.net v2 is in maintenance mode: critical bug fixes continue, while new feature work is in v3. That does not mean an existing v2 project should be changed just to run its first test. If you intend to migrate, follow the project’s migration guidance and update its template, packages, and runner configuration together. Do not copy a v2 command into a v3 project, or vice versa, without checking how that project is configured.
7. Run tests from an editor if you prefer
The command line is sufficient for a first run. You can also use Visual Studio Test Explorer when the project has the VSTest-related package references needed for discovery. The xUnit instructions also describe VS Code with Microsoft’s C# Dev Kit and the relevant runner packages. An editor is optional; it does not replace the need to understand the project’s runner configuration.
Common errors and fixes
| Symptom | Likely cause | What to do |
|---|---|---|
dotnet is not found |
The .NET SDK is missing, or the shell’s PATH has not refreshed. | Install the SDK, open a new terminal, and rerun dotnet --version. |
No templates or subcommands found for xunit3 |
The xUnit v3 template package is not installed, or the command was mistyped. | Run dotnet new install xunit.v3.templates, then check dotnet new list for the template. |
| Restore fails or packages cannot be resolved | Network or package-source access failed, or restore has not completed. | Check configured NuGet sources and network access, then run dotnet restore from the project directory. |
| No tests are discovered | The runner setup does not match the command, or required VSTest integration packages are absent. | Inspect the project file and generated runner configuration. Use the instructions for Microsoft Testing Platform or VSTest that match the template. |
dotnet test does not execute the v3 project as expected |
The generated project may use Microsoft Testing Platform and document dotnet run for that setup. |
Try the command specified by the generated template and current xUnit v3 runner instructions. Do not add packages at random. |
| A test fails with expected and actual values | The assertion does not match the method result, or the implementation is wrong. | Use the failure’s test name and source location to inspect the input, expected value, and code under test. |
| The tutorial’s target framework is unavailable | The project targets a framework not installed or supported by the local SDK. | Check the TargetFramework in the project and install a suitable SDK, or choose a framework your project supports. |
| Tests pass locally but are not listed in an IDE | The IDE’s test adapter or project runner configuration differs from the command-line setup. | Check the documented IDE integration and package references for the selected runner, then reload or rebuild the project. |
Performance, reliability, and cost notes
A small first test project should run quickly, but startup and package restore can take longer than executing a trivial assertion. A reliable first-run sequence is to restore dependencies once, keep the project and runner configuration consistent, and rerun tests after meaningful code changes. As a project grows, keep tests focused and isolate external services when a test is intended to verify a unit of code rather than network or database behavior.
The reviewed xUnit documentation provides sample output, not general setup benchmarks or a universal test speed guarantee. SDK versions, package restore, runner choice, machine resources, and the test workload affect elapsed time. The .NET SDK and xUnit are developer software; the documented first-run workflow does not require a physical product purchase. The xUnit.net v3 guide used a pre-release package version in its example, so check current official instructions before pinning versions.
Or skip the browser setup
For a separate task such as capturing a test report or documentation page as an image, you can call ScreenshotNeo, a website screenshot API and MCP server for developers. It is unrelated to running xUnit tests, but can help when your workflow also needs page captures. See the ScreenshotNeo API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpCookie banners are accepted and removed before the shot, along with known newsletter popups and chat widgets. Bot checks, blank pages, failed loads, timeouts, and cache hits cost nothing; response headers say the page verdict and whether the request was billed. An MCP server lets AI agents use the take_screenshot, get_page_info, and capture_pdf tools. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for 1,000 free screenshots a month, with no card.
FAQ
Do I need to write a script file to run xUnit?
No separate shell script is required. The generated test project contains C# test code, and the .NET CLI invokes its configured runner.
Can I use F# or VB.NET instead of C#?
Yes. The documented xUnit.net v3 templates support C#, F#, and VB.NET. Select the language and template options supported by the installed template version.
Should I start with v2 or v3?
For a new project, the current xUnit getting-started path is v3. For an existing v2 project, keep using its matching runner setup unless you have chosen to migrate.
What does one passing test prove?
It shows that the assertion held for the exercised case. It does not establish that untested inputs or other parts of the application behave correctly.
