xUnit.net

https://xunit.net/
Admin
xUnit.net is a free, open-source unit testing framework for C#, F#, and Visual Basic that supports...
Tokens:246,550
Snippets:2,174
Trust Score:9.5
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Expected output from installing xUnit.net v3 templates

Source: https://xunit.net/docs/getting-started/v3/getting-started

Example output after running the install command, listing the installed template package and the available templates.

```shell
$ dotnet new install xunit.v3.templates
The following template packages will be installed:
   xunit.v3.templates

Success: xunit.v3.templates::4.0.0-pre.108 installed the following templates:
Template Name                   Short Name        Language    Tags
------------------------------  ----------------  ----------  ----------
xUnit.net v3 Extension Project  xunit3-extension  [C#],F#,VB  Test/xUnit
xUnit.net v3 Test Project       xunit3            [C#],F#,VB  Test/xUnit
```

--------------------------------

### Check .NET SDK version with dotnet --version

Source: https://xunit.net/docs/getting-started/v3/getting-started

Verifies the .NET SDK installation by printing the installed version. The output shown is an example; your version may differ.

```shell
$ dotnet --version
10.0.102
```

--------------------------------

### Install xUnit.net v3 templates

Source: https://xunit.net/docs/getting-started/v3/code-coverage-with-mtp

Installs the xUnit.net v3 project templates using the .NET CLI. The output shows the template package being installed and the available templates.

```shell
dotnet new install xunit.v3.templates
```

```shell
The following template packages will be installed:
   xunit.v3.templates

Success: xunit.v3.templates@4.0.0 installed the following templates:
Template Name                   Short Name        Language    Tags
------------------------------  ----------------  ----------  ----------------------
xUnit.net v3 Extension Project  xunit3-extension  [C#],F#,VB  Test/xUnit
xUnit.net v3 Test Project       xunit3            [C#],F#,VB  Test/xUnit/Desktop/Web
```

--------------------------------

### Collection fixture example with DatabaseFixture, collection definition, and test classes

Source: https://xunit.net/docs/shared-context

Shows how to create a collection fixture: a fixture class with setup and cleanup, a collection definition class using [CollectionDefinition] and ICollectionFixture<>, and test classes using [Collection] with the fixture injected via constructor. The fixture is created before any tests in the collection run and cleaned up after all tests finish.

```csharp
public class DatabaseFixture : IDisposable
{
    public DatabaseFixture()
    {
        Db = new SqlConnection("MyConnectionString");

        // ... initialize data in the test database ...
    }

    public void Dispose()
    {
        // ... clean up test data from the database ...
    }

    public SqlConnection Db { get; private set; }
}

[CollectionDefinition("Database collection")]
public class DatabaseCollection : ICollectionFixture<DatabaseFixture>
{
    // This class has no code, and is never created. Its purpose is simply
    // to be the place to apply [CollectionDefinition] and all the
    // ICollectionFixture<> interfaces.
}

[Collection("Database collection")]
public class DatabaseTestClass1
{
    DatabaseFixture fixture;

    public DatabaseTestClass1(DatabaseFixture fixture)
    {
        this.fixture = fixture;
    }
}

[Collection("Database collection")]
public class DatabaseTestClass2
{
    // ...
}
```

--------------------------------

### Install ReportGenerator global tool

Source: https://xunit.net/docs/getting-started/v3/code-coverage-with-mtp

Installs the ReportGenerator global tool and shows the expected output confirming successful installation.

```shell
dotnet tool install --global dotnet-reportgenerator-globaltool
```

```shell
You can invoke the tool using the following command: reportgenerator
Tool 'dotnet-reportgenerator-globaltool' (version '5.5.11') was successfully installed.
```

--------------------------------

### Example xunit.runner.json structure

Source: https://xunit.net/docs/config-xunit-runner-json

Shows the top-level structure of the configuration file with example keys of different types. All configuration elements are placed inside a top-level object.

```json
{
  "$schema": "https://xunit.net/schema/current/xunit.runner.schema.json",
  "enum-or-string-key": "value1",
  "boolean-key": true,
  "integer-key": 42
}
```

--------------------------------

### Mono stack trace example

Source: https://xunit.net/docs/getting-started/multi-target/non-windows

Example stack trace from Mono when running .NET Framework tests on non-Windows OSes.

```text
Assert.Equal() Failure
Expected: 5
Actual:   4
Stack Trace:
  at MyFirstUnitTests.Class1.FailingTest () [0x0000a] in <ea38f081094e407290795149a3e20d66>:0
```

--------------------------------

### Create solution folder and solution file

Source: https://xunit.net/docs/getting-started/v3/code-coverage-with-mtp

Creates a folder for the sample project, changes into it, and creates a new solution file. The output confirms the solution file was created.

```shell
mkdir CodeCoverageSample
```

```shell
cd CodeCoverageSample
```

```shell
dotnet new sln
```

```shell
The template "Solution File" was created successfully.
```

--------------------------------

### Create class library and add to solution

Source: https://xunit.net/docs/getting-started/v3/code-coverage-with-mtp

Creates a class library targeting .NET 10.0 and adds it to the solution. The output shows the library was created and restored successfully.

```shell
dotnet new classlib -f net10.0 -o ClassLibrary
```

```shell
The template "Class Library" was created successfully.

Processing post-creation actions...
Restoring ClassLibrary\ClassLibrary.csproj:
Restore succeeded.
```

```shell
dotnet sln add ClassLibrary
```

```shell
Project `ClassLibrary\ClassLibrary.csproj` added to the solution.
```

--------------------------------

### TeamCity control message output example

Source: https://xunit.net/docs/getting-test-results-in-teamcity

Example output line starting with ##teamcity that TeamCity consumes. This appears when running with the detailed console logger and the TEAMCITY_PROJECT_NAME environment variable set.

```text
[xUnit.net 00:00:00.10] ##teamcity[flowStarted timestamp='2023-06-18T00:02:48.362+0000' flowId='my.tests.dll']
```

--------------------------------

### Compliant example: Assert.Single for single-item collection

Source: https://xunit.net/xunit.analyzers/rules/xUnit2023

Does not violate xUnit2023. Uses Assert.Single to get the item and then performs assertions on it.

```csharp
using Xunit;

public class xUnit2023
{
    [Fact]
    public void TestMethod()
    {
        var collection = new[] { 1 };

        var item = Assert.Single(collection);
        Assert.Equal(1, item);
    }
}
```

--------------------------------

### Default runner reporter console output

Source: https://xunit.net/docs/getting-started/v3/custom-runner-reporter

Example console output produced by the default runner reporter when running tests with the xUnit.net v3 in-process runner. Shows discovery, start, finish, and summary lines with test counts and timing.

```text
xUnit.net v3 In-Process Runner v0.5.0-pre.27-dev+03065987f3 (64-bit .NET 6.0.35)
  Discovering: xunit.v3.assert.tests (method display = ClassAndMethod, method display options = None)
  Discovered:  xunit.v3.assert.tests (1151 test cases to be run)
  Starting:    xunit.v3.assert.tests (parallel test collections = on [24 threads], stop on fail = off, explicit = off, seed = 309588804, culture = invariant)
  Finished:    xunit.v3.assert.tests
=== TEST EXECUTION SUMMARY ===
   xunit.v3.assert.tests  Total: 1389, Errors: 0, Failed: 0, Skipped: 0, Not Run: 0, Time: 0.172s

```

--------------------------------

### Create test project and add to solution

Source: https://xunit.net/docs/getting-started/v3/code-coverage-with-mtp

Creates an xUnit.net v3 test project targeting .NET 10.0 with MTP command-line support, adds it to the solution, and adds a reference to the class library. The output shows the project was created and restored successfully.

```shell
dotnet new xunit3 -f net10.0 -o Tests --command-line mtp
```

```shell
The template "xUnit.net v3 Test Project" was created successfully.

Processing post-creation actions...
Restoring Tests\Tests.csproj:
Restore succeeded.
```

```shell
dotnet sln add Tests
```

```shell
Project `Tests\Tests.csproj` added to the solution.
```

```shell
dotnet add Tests reference ClassLibrary
```

```shell
Reference `..\ClassLibrary\ClassLibrary.csproj` added to the project.
```

--------------------------------

### Test class as context pattern with nested classes

Source: https://xunit.net/docs/shared-context

This pattern uses nested test classes to represent different stack states, each with its own constructor setup. The parent class StackTests groups the contexts. This approach makes the starting point clear and is useful when tests need different initial states.

```csharp
public class StackTests
{
    public class EmptyStack
    {
        Stack<int> stack;

        public EmptyStack()
        {
            stack = new Stack<int>();
        }

        // ... tests for an empty stack ...
    }

    public class SingleItemStack
    {
        Stack<int> stack;

        public SingleItemStack()
        {
            stack = new Stack<int>();
            stack.Push(42);
        }

        // ... tests for a single-item stack ...
    }
}
```

--------------------------------

### xunit-console help output on Linux/macOS

Source: https://xunit.net/docs/getting-started/v3/getting-started

Example output from invoking xunit-console with no arguments on Linux/macOS. Shows the runner version, usage syntax, and a note that only v3 test projects are supported and configuration files must be JSON.

```shell
$ xunit-console
xUnit.net v3 Console Runner v4.0.0-pre.108+342e27492f [linux-x64]
Copyright (C) .NET Foundation.

usage: xunit.v3.runner.console <assemblyFile>[:seed] [configFile] [assemblyFile[:seed] [configFile]...] [options] [reporter] [resultFormat filename [...]]

Note: Only v3 test projects are supported (v1 and v2 are not supported by this runner)
      Configuration files must by JSON format, and the filename must end in .json

General options

  -assertEquivalentMaxDepth <option> : override the maximum recursive depth when comparing objects with Assert.Equivalent
                                     :   any integer value >= 1 is valid (default value is 50)
[...]
```

--------------------------------

### xunit-console help output on Windows

Source: https://xunit.net/docs/getting-started/v3/getting-started

Example output from invoking xunit-console with no arguments on Windows. Shows the runner version, usage syntax, and a note about configuration file formats.

```shell
$ xunit-console
xUnit.net v3 Console Runner v4.0.0-pre.108+342e27492f [net472/AnyCPU] (64-bit .NET Framework 4.8.9325.0)
Copyright (C) .NET Foundation.

usage: xunit.v3.runner.console <assemblyFile>[:seed] [configFile] [assemblyFile[:seed] [configFile]...] [options] [reporter] [resultFormat filename [...]]

Note: Configuration files must end in .json (for JSON) or .config (for XML)
      XML is supported for v1 and v2 only, on .NET Framework only
      JSON is supported for v2 and later, on all supported platforms

General options

  -assertEquivalentMaxDepth <option> : override the maximum recursive depth when comparing objects with Assert.Equivalent
                                     :   any integer value >= 1 is valid (default value is 50)
[...]
```

--------------------------------

### Update installed templates

Source: https://xunit.net/docs/getting-started/v3/whats-new

Updates all installed templates, including xUnit.net v3 templates, to their latest versions.

```shell
$ dotnet new update
```

--------------------------------

### dotnet test command line with xUnit RunSettings

Source: https://xunit.net/docs/config-runsettings

Shows how to pass RunSettings via the dotnet test command line using xUnit.key=value pairs. This example disables app domains and parallelization.

```text
dotnet test path/to/myproject -- xUnit.AppDomain=denied xUnit.ParallelizeTestCollections=false
```

--------------------------------

### Compliant example: MemberData with provided argument

Source: https://xunit.net/xunit.analyzers/rules/xUnit1067

This example does not violate the rule because the required argument is provided in the MemberData attribute.

```csharp
using Xunit;

public class xUnit1067
{
    public static TheoryData<int> DataSource(int multiplier) => [42 * multiplier];

    [Theory]
    [MemberData(nameof(DataSource), 1)]
    public void TestMethod(int _)
    { }
}
```

--------------------------------

### Run tests with --xunit-info

Source: https://xunit.net/docs/getting-started/v3/microsoft-testing-platform

Run the test project with the --xunit-info switch to see the combined output from the native xUnit.net command line experience and Microsoft Testing Platform. The output shows discovery, test results, and a summary with failure details.

```shell
$ dotnet run -- --xunit-info
xUnit.net v3 Microsoft.Testing.Platform Runner v3.1.0+03a071627b (64-bit .NET 8.0.20)

xUnit.net v3 In-Process Runner v3.1.0+03a071627b (64-bit .NET 8.0.20)
  Discovering: MyFirstUnitTests
  Discovered:  MyFirstUnitTests
  Starting:    MyFirstUnitTests
    MyFirstUnitTests.UnitTest1.FailingTest [FAIL]
      Assert.Equal() Failure: Values differ
      Expected: 5
      Actual:   4
      Stack Trace:
        UnitTest1.cs(14,0): at MyFirstUnitTests.UnitTest1.FailingTest()
    MyFirstUnitTests.UnitTest1.MyFirstTheory(value: 6) [FAIL]
      Assert.True() Failure
      Expected: True
      Actual:   False
      Stack Trace:
        UnitTest1.cs(28,0): at MyFirstUnitTests.UnitTest1.MyFirstTheory(Int32 value)
failed MyFirstUnitTests.UnitTest1.FailingTest (7ms)
  Assert.Equal() Failure: Values differ
  Expected: 5
  Actual:   4
    at MyFirstUnitTests.UnitTest1.FailingTest() in UnitTest1.cs:14
failed MyFirstUnitTests.UnitTest1.MyFirstTheory(value: 6) (0ms)
  Assert.True() Failure
  Expected: True
  Actual:   False
    at MyFirstUnitTests.UnitTest1.MyFirstTheory(Int32 value) in UnitTest1.cs:28
  Finished:    MyFirstUnitTests (ID = '80800e0af62d4c98efccd4ccc97bc5732c1c4655418cf54e297426d4f586eeff')
=== TEST EXECUTION SUMMARY ===
   MyFirstUnitTests  Total: 5, Errors: 0, Failed: 2, Skipped: 0, Not Run: 0, Time: 0.060s

Test run summary: Failed! - bin\Debug\net8.0\MyFirstUnitTests.dll (net8.0|x64)
  total: 5
  failed: 2
  succeeded: 3
  skipped: 0
  duration: 126ms
```

--------------------------------

### Compliant example: MemberData with optional parameter

Source: https://xunit.net/xunit.analyzers/rules/xUnit1067

This example does not violate the rule because the method parameter is optional, so no arguments are required.

```csharp
using Xunit;

public class xUnit1067
{
    public static TheoryData<int> DataSource(int multiplier = 1) => [42 * multiplier];

    [Theory]
    [MemberData(nameof(DataSource))]
    public void TestMethod(int _)
    { }
}
```

--------------------------------

### Run tests with coverage settings from GitHub Actions

Source: https://xunit.net/docs/getting-started/v3/code-coverage-with-mtp

Example command for GitHub Actions that passes a full path to a .runsettings file using the --coverage-settings switch.

```shell
dotnet test --coverage --coverage-settings '${{ github.workspace }}/src/.runsettings'
```

--------------------------------

### Compliant example: MemberData with parameterless method

Source: https://xunit.net/xunit.analyzers/rules/xUnit1067

This example does not violate the rule because the method DataSource has no parameters, so no arguments are needed.

```csharp
using Xunit;

public class xUnit1067
{
    public static TheoryData<int> DataSource() => [42];

    [Theory]
    [MemberData(nameof(DataSource))]
    public void TestMethod(int _)
    { }
}
```

--------------------------------

### Using a response file to avoid the 32K command line limit

Source: https://xunit.net/docs/getting-started/v3/getting-started

Shows the original command line, the response file content with one argument per line, and the command line using the response file. The response file mode requires the command line to contain only '@@ filename' and the file must contain one argument per line without quoting.

```text
/path/to/MyTestProject.exe -culture en-GB -noLogo -maxThreads 32 -xml "/path/to/The XML Output File.xml"
```

```text
-culture
en-GB
-noLogo
-maxThreads
32
-xml
/path/to/The XML Output File.xml
```

```text
/path/to/MyTestProject.exe @@ /path/to/response-file
```

--------------------------------

### Compliant example with a single public constructor

Source: https://xunit.net/xunit.analyzers/rules/xUnit1056

This example does not violate the rule because MyFixture has exactly one public constructor.

```csharp
using Xunit;

public class xUnit1056 : IClassFixture<MyFixture>
{
    [Fact]
    public void TestMethod() { }
}

public class MyFixture
{
    public MyFixture(int _) { }
}

```

--------------------------------

### Install xunit-console-tool globally

Source: https://xunit.net/docs/getting-started/v3/getting-started

Install the xunit-console-tool .NET tool globally. Use the first command for the latest release version and the second for the latest prerelease version. Requires .NET 10 SDK or later.

```shell
dotnet tool install xunit-console-tool --global
```

```shell
dotnet tool install xunit-console-tool --global --prerelease
```

--------------------------------

### Compliant example with multiple cultures

Source: https://xunit.net/xunit.analyzers/rules/xUnit1060

This example complies with the rule by declaring at least one culture, ensuring the test runs for each culture.

```csharp
using Xunit;

public class xUnit1060
{
    [CulturedFact(["en-US", "fr-FR"])]
    public void FactMethod()
    { }
}
```

--------------------------------

### Compliant examples: [Fact] and [Theory, InlineData(1)]

Source: https://xunit.net/xunit.analyzers/rules/xUnit1005

Two compliant examples: a non-parameterized fact method without test data, and a parameterized theory method using InlineData.

```csharp
using Xunit;

public class xUnit1005
{
    [Fact]
    public void TestMethod()
    { }
}
```

```csharp
using Xunit;

public class xUnit1005
{
    [Theory, InlineData(1)]
    public void TestMethod(int _)
    { }
}
```

--------------------------------

### Violating example with empty culture list

Source: https://xunit.net/xunit.analyzers/rules/xUnit1060

This example violates the rule by declaring an empty culture list, resulting in zero tests.

```csharp
using Xunit;

public class xUnit1060
{
    [CulturedFact([])]
    public void FactMethod()
    { }
}
```

--------------------------------

### Compliant example: setting only SkipWhen

Source: https://xunit.net/xunit.analyzers/rules/xUnit1055

This example does not violate the rule because it sets only the SkipWhen property. It shows the correct way to use conditional skipping.

```csharp
using Xunit;

public class xUnit1055
{
    public static bool AlwaysTrue => true;

    [Fact(Skip = "Don't run", SkipWhen = nameof(AlwaysTrue))]
    public void Fact()
    { }
}
```

--------------------------------

### Create F# xUnit.net v3 test project with dotnet new xunit3

Source: https://xunit.net/index.html

Creates a new xUnit.net v3 test project in F#. The output confirms the project creation and restore.

```bash
dotnet new xunit3 --language F#
```

```text
The template "xUnit.net v3 Test Project" was created successfully.

Processing post-creation actions...
Restoring C:\Dev\SampleProject\SampleProject.fsproj:
Restore succeeded.

Successfully modified global.json.
```

--------------------------------

### Compliant example: MemberData with public getter

Source: https://xunit.net/xunit.analyzers/rules/xUnit1020

This example does not violate the rule because the TestData property has a public getter, allowing MemberData to read the data.

```csharp
using System.Collections.Generic;
using Xunit;

public class xUnit1020
{
    public static IEnumerable<object[]> TestData { get; set; }

    [Theory]
    [MemberData(nameof(TestData))]
    public void TestMethod(string greeting, int age) { }
}
```
Tokens:
Raw