# Migrating from xUnit.net

Performance Boost

Migrating from xUnit to TUnit can improve test execution speed. Check the [benchmarks](/docs/benchmarks/.md) to see how TUnit compares.

## Quick Reference[​](#quick-reference "Direct link to Quick Reference")

| xUnit                            | TUnit                                                           |
| -------------------------------- | --------------------------------------------------------------- |
| `[Fact]`                         | `[Test]`                                                        |
| `[Theory]`                       | `[Test]`                                                        |
| `[InlineData(...)]`              | `[Arguments(...)]`                                              |
| `[MemberData(nameof(...))]`      | `[MethodDataSource(nameof(...))]`                               |
| `[ClassData(typeof(...))]`       | `[MethodDataSource(nameof(ClassName.Method))]`                  |
| `[Trait("key", "value")]`        | `[Property("key", "value")]`                                    |
| `IClassFixture<T>`               | `[ClassDataSource<T>(Shared = SharedType.PerClass)]`            |
| `[Collection("name")]`           | `[ClassDataSource<T>(Shared = SharedType.Keyed, Key = "name")]` |
| Constructor                      | Constructor or `[Before(Test)]`                                 |
| `IDisposable`                    | `IDisposable` or `[After(Test)]`                                |
| `IAsyncLifetime`                 | `[Before(Test)]` / `[After(Test)]`                              |
| `ITestOutputHelper`              | `TestContext` parameter                                         |
| `Assert.Equal(expected, actual)` | `await Assert.That(actual).IsEqualTo(expected)`                 |
| `Assert.Throws<T>(() => ...)`    | `Assert.Throws<T>(() => ...)`                                   |

## Automated Migration with Code Fixers[​](#automated-migration-with-code-fixers "Direct link to Automated Migration with Code Fixers")

TUnit includes Roslyn analyzers and code fixers that automate most of the migration work. The `TUXU0001` diagnostic identifies xUnit code patterns and provides automatic fixes to convert them to TUnit equivalents.

**What gets converted automatically:**

* `[Fact]` → `[Test]`
* `[Theory]` → `[Test]`
* `[InlineData(...)]` → `[Arguments(...)]`
* `[MemberData(nameof(...))]` → `[MethodDataSource(nameof(...))]`
* `[Trait("key", "value")]` → `[Property("key", "value")]`
* `Assert.Equal(expected, actual)` → `await Assert.That(actual).IsEqualTo(expected)`
* `Assert.True(condition)` → `await Assert.That(condition).IsTrue()`
* `Assert.Throws<T>(...)` → `Assert.Throws<T>(...)`
* `Assert.Contains(item, collection)` → `await Assert.That(collection).Contains(item)`
* Test methods converted to `async Task` with `await` on assertions

The code fixer handles roughly 80-90% of typical test suites automatically.

**What requires manual adjustment:**

* `IClassFixture<T>` → `[ClassDataSource<T>(Shared = SharedType.PerClass)]` on the class
* `ICollectionFixture<T>` and `[Collection("name")]` → `[ClassDataSource<T>(Shared = SharedType.Keyed, Key = "name")]`
* `IAsyncLifetime` → `[Before(Test)]` and `[After(Test)]` methods
* `ITestOutputHelper` → `TestContext` parameter injection
* Custom `MemberData` return types (convert `IEnumerable<object[]>` to `IEnumerable<(...)>` tuples)
* `[ClassData(typeof(...))]` → `[MethodDataSource(nameof(ClassName.Method))]`
* Constructor injection of fixtures → primary constructor with `[ClassDataSource<T>]` attribute
* Collection definitions → remove `ICollectionFixture` classes entirely

If you find a common pattern that should be automated but isn't, please [open an issue](https://github.com/thomhurst/TUnit/issues).

### Prerequisites[​](#prerequisites "Direct link to Prerequisites")

* .NET SDK 8.0 or later (for `dotnet format` with analyzer support)
* TUnit packages installed in your test project

### Step-by-Step Migration[​](#step-by-step-migration "Direct link to Step-by-Step Migration")

Safety First

Commit your changes or create a backup before running the code fixer. This allows you to review changes and revert if needed.

**1. Install TUnit packages**

Add the TUnit packages to your test project alongside xUnit (temporarily):

```
dotnet add package TUnit
```

**2. Disable TUnit's implicit usings (temporary)**

Add these properties to your `.csproj` to prevent type name conflicts between xUnit and TUnit:

```
<PropertyGroup>

    <TUnitImplicitUsings>false</TUnitImplicitUsings>

    <TUnitAssertionsImplicitUsings>false</TUnitAssertionsImplicitUsings>

</PropertyGroup>
```

This allows the code fixer to distinguish between `Xunit.Assert` and `TUnit.Assertions.Assert`.

**3. Rebuild the project**

```
dotnet build
```

This restores packages and loads the TUnit analyzers.

Optional: Verify analyzer is working

The `TUXU0001` diagnostic is information-level and won't appear in standard build output. If you want to verify the analyzer is detecting xUnit code before applying changes, run:

```
dotnet format analyzers --severity info --diagnostics TUXU0001 --verify-no-changes
```

This command checks for `TUXU0001` diagnostics without modifying any files. If xUnit code is detected, you'll see messages like "Would fix N files" or specific file paths that would be changed.

**4. Run the automated code fixer**

```
dotnet format analyzers --severity info --diagnostics TUXU0001
```

This command applies all available fixes for the `TUXU0001` diagnostic. You'll see output indicating which files were modified.

Multi-targeting Projects

If your project targets multiple .NET versions (e.g., `net10.0;net11.0`), you **must** specify a single target framework when running the code fixer. Multi-targeting can cause the code fixer to crash with the error `Changes must be within bounds of SourceText` due to a limitation in Roslyn's linked file handling.

**Option 1:** Specify a single framework via command line:

```
dotnet format analyzers --severity info --diagnostics TUXU0001 --framework net10.0
```

**Option 2:** Temporarily modify your project file to single-target:

```
<!-- Before migration -->

<TargetFramework>net10.0</TargetFramework>

<!-- <TargetFrameworks>net10.0;net11.0</TargetFrameworks> -->
```

Run the code fixer, then restore multi-targeting afterward. Replace `net10.0` with your project's highest supported target framework.

**5. Remove the implicit usings workaround**

Remove or comment out the properties you added in step 2:

```
<!-- Remove these lines -->

<PropertyGroup>

    <TUnitImplicitUsings>false</TUnitImplicitUsings>

    <TUnitAssertionsImplicitUsings>false</TUnitAssertionsImplicitUsings>

</PropertyGroup>
```

**6. Fix remaining issues manually**

Build the project and address any remaining compilation errors:

```
dotnet build
```

Common manual fixes needed:

* Replace `IClassFixture<T>` with `[ClassDataSource<T>(Shared = SharedType.PerClass)]` attribute
* Replace `IAsyncLifetime` with `[Before(Test)]`/`[After(Test)]` methods
* Replace `ITestOutputHelper` constructor parameter with `TestContext` method parameter
* Convert data source methods to return tuples instead of `object[]`
* Add `using TUnit.Core;` and `using TUnit.Assertions;` if not using implicit usings
* Remove `ICollectionFixture` and collection definition classes

**7. Remove xUnit packages**

Once everything compiles and tests pass:

```
dotnet remove package xunit

dotnet remove package xunit.runner.visualstudio
```

**8. Verify the migration**

```
dotnet build

dotnet run -- --list-tests
```

### Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

**Code fixer doesn't run / no files changed:**

* Ensure you rebuilt after adding TUnit packages
* Check that `TUXU0001` warnings appear in build output
* Try running with verbose output: `dotnet format analyzers --severity info --diagnostics TUXU0001 --verbosity detailed`

**Build errors after running code fixer:**

* Missing `await` keywords: ensure test methods are `async Task`
* Ambiguous `Assert`: remove xUnit usings or fully qualify types
* Type mismatch in data sources: convert `IEnumerable<object[]>` returns to `IEnumerable<(...)>` tuples

**IClassFixture not converted:**

* This requires manual conversion - add `[ClassDataSource<T>(Shared = SharedType.PerClass)]` to the class
* Use a primary constructor to receive the fixture: `public class MyTests(MyFixture fixture)`

**Analyzers not loading:**

* Verify TUnit package is installed: `dotnet list package`
* Try cleaning and rebuilding: `dotnet clean && dotnet build`

## Manual Migration Guide[​](#manual-migration-guide "Direct link to Manual Migration Guide")

### Basic Test Structure[​](#basic-test-structure "Direct link to Basic Test Structure")

#### Simple Test (Fact → Test)[​](#simple-test-fact--test "Direct link to Simple Test (Fact → Test)")

**xUnit Code:**

```
public class CalculatorTests

{

    [Fact]

    public void Add_TwoNumbers_ReturnsSum()

    {

        var calculator = new Calculator();

        var result = calculator.Add(2, 3);

        Assert.Equal(5, result);

    }

}
```

**TUnit Equivalent:**

```
public class CalculatorTests

{

    [Test]

    public async Task Add_TwoNumbers_ReturnsSum()

    {

        var calculator = new Calculator();

        var result = calculator.Add(2, 3);

        await Assert.That(result).IsEqualTo(5);

    }

}
```

**Key Changes:**

* `[Fact]` → `[Test]`
* Test method returns `async Task`
* Assertions use fluent syntax with `await Assert.That(...)`

### Parameterized Tests[​](#parameterized-tests "Direct link to Parameterized Tests")

#### Theory with InlineData → Arguments[​](#theory-with-inlinedata--arguments "Direct link to Theory with InlineData → Arguments")

**xUnit Code:**

```
public class StringTests

{

    [Theory]

    [InlineData("hello", 5)]

    [InlineData("world", 5)]

    [InlineData("", 0)]

    public void Length_ReturnsCorrectValue(string input, int expectedLength)

    {

        Assert.Equal(expectedLength, input.Length);

    }

}
```

**TUnit Equivalent:**

```
public class StringTests

{

    [Test]

    [Arguments("hello", 5)]

    [Arguments("world", 5)]

    [Arguments("", 0)]

    public async Task Length_ReturnsCorrectValue(string input, int expectedLength)

    {

        await Assert.That(input.Length).IsEqualTo(expectedLength);

    }

}
```

**Key Changes:**

* `[Theory]` → `[Test]`
* `[InlineData(...)]` → `[Arguments(...)]`
* Method is async and assertions are awaited

### Data Sources[​](#data-sources "Direct link to Data Sources")

#### MemberData → MethodDataSource[​](#memberdata--methoddatasource "Direct link to MemberData → MethodDataSource")

**xUnit Code:**

```
public class DataDrivenTests

{

    [Theory]

    [MemberData(nameof(GetTestData))]

    public void ProcessData_WithVariousInputs(int value, string text, bool expected)

    {

        var result = SomeLogic(value, text);

        Assert.Equal(expected, result);

    }



    public static IEnumerable<object[]> GetTestData()

    {

        yield return new object[] { 1, "test", true };

        yield return new object[] { 2, "demo", false };

        yield return new object[] { 3, "example", true };

    }

}
```

**TUnit Equivalent:**

```
public class DataDrivenTests

{

    [Test]

    [MethodDataSource(nameof(GetTestData))]

    public async Task ProcessData_WithVariousInputs(int value, string text, bool expected)

    {

        var result = SomeLogic(value, text);

        await Assert.That(result).IsEqualTo(expected);

    }



    public static IEnumerable<(int value, string text, bool expected)> GetTestData()

    {

        yield return (1, "test", true);

        yield return (2, "demo", false);

        yield return (3, "example", true);

    }

}
```

**Key Changes:**

* `[MemberData(nameof(...))]` → `[MethodDataSource(nameof(...))]`
* Data source returns tuples instead of `object[]` (strongly typed)
* No need for boxing/unboxing values

#### ClassData → MethodDataSource[​](#classdata--methoddatasource "Direct link to ClassData → MethodDataSource")

**xUnit Code:**

```
public class TestDataGenerator : IEnumerable<object[]>

{

    public IEnumerator<object[]> GetEnumerator()

    {

        yield return new object[] { 1, "one" };

        yield return new object[] { 2, "two" };

    }



    IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();

}



public class MyTests

{

    [Theory]

    [ClassData(typeof(TestDataGenerator))]

    public void TestWithClassData(int number, string text)

    {

        Assert.True(number > 0);

        Assert.NotNull(text);

    }

}
```

**TUnit Equivalent:**

```
public class MyTests

{

    [Test]

    [MethodDataSource(nameof(TestDataGenerator.GetTestData))]

    public async Task TestWithClassData(int number, string text)

    {

        await Assert.That(number).IsGreaterThan(0);

        await Assert.That(text).IsNotNull();

    }

}



public class TestDataGenerator

{

    public static IEnumerable<(int, string)> GetTestData()

    {

        yield return (1, "one");

        yield return (2, "two");

    }

}
```

**Key Changes:**

* `[ClassData(typeof(...))]` → `[MethodDataSource(nameof(ClassName.MethodName))]`
* Point to a static method rather than implementing IEnumerable
* Use tuples for type safety

### Setup and Teardown[​](#setup-and-teardown "Direct link to Setup and Teardown")

#### Constructor and IDisposable → Before/After Hooks[​](#constructor-and-idisposable--beforeafter-hooks "Direct link to Constructor and IDisposable → Before/After Hooks")

**xUnit Code:**

```
public class DatabaseTests : IDisposable

{

    private readonly DatabaseConnection _connection;



    public DatabaseTests()

    {

        _connection = new DatabaseConnection();

        _connection.Open();

    }



    [Fact]

    public void Query_ReturnsData()

    {

        var result = _connection.Query("SELECT * FROM Users");

        Assert.NotNull(result);

    }



    public void Dispose()

    {

        _connection?.Close();

        _connection?.Dispose();

    }

}
```

**TUnit Equivalent (Option 1: Using IDisposable):**

```
public class DatabaseTests : IDisposable

{

    private DatabaseConnection _connection = null!;



    public DatabaseTests()

    {

        _connection = new DatabaseConnection();

        _connection.Open();

    }



    [Test]

    public async Task Query_ReturnsData()

    {

        var result = _connection.Query("SELECT * FROM Users");

        await Assert.That(result).IsNotNull();

    }



    public void Dispose()

    {

        _connection?.Close();

        _connection?.Dispose();

    }

}
```

**TUnit Equivalent (Option 2: Using Hooks):**

```
public class DatabaseTests

{

    private DatabaseConnection _connection = null!;



    [Before(Test)]

    public async Task Setup()

    {

        _connection = new DatabaseConnection();

        await _connection.OpenAsync();

    }



    [Test]

    public async Task Query_ReturnsData()

    {

        var result = _connection.Query("SELECT * FROM Users");

        await Assert.That(result).IsNotNull();

    }



    [After(Test)]

    public async Task Cleanup()

    {

        if (_connection != null)

        {

            await _connection.CloseAsync();

            _connection.Dispose();

        }

    }

}
```

**Key Changes:**

* Constructor setup can remain, or use `[Before(Test)]`
* IDisposable can remain, or use `[After(Test)]`
* Hooks support async operations natively
* Multiple `[After(Test)]` methods are guaranteed to run even if one fails

#### IAsyncLifetime → Before/After Hooks[​](#iasynclifetime--beforeafter-hooks "Direct link to IAsyncLifetime → Before/After Hooks")

**xUnit Code:**

```
public class AsyncSetupTests : IAsyncLifetime

{

    private HttpClient _client = null!;



    public async ValueTask InitializeAsync()

    {

        _client = new HttpClient();

        await _client.GetAsync("https://api.example.com/warm-up", Xunit.TestContext.Current.CancellationToken);

    }



    [Fact]

    public async Task FetchData_ReturnsSuccess()

    {

        var response = await _client.GetAsync(

            "https://api.example.com/data",

            Xunit.TestContext.Current.CancellationToken);

        Assert.True(response.IsSuccessStatusCode);

    }



    public async ValueTask DisposeAsync()

    {

        _client?.Dispose();

        await Task.CompletedTask;

    }

}
```

**TUnit Equivalent:**

```
public class AsyncSetupTests

{

    private HttpClient _client = null!;



    [Before(Test)]

    public async Task Setup()

    {

        _client = new HttpClient();

        await _client.GetAsync("https://api.example.com/warm-up");

    }



    [Test]

    public async Task FetchData_ReturnsSuccess()

    {

        var response = await _client.GetAsync("https://api.example.com/data");

        await Assert.That(response.IsSuccessStatusCode).IsTrue();

    }



    [After(Test)]

    public async Task Cleanup()

    {

        _client?.Dispose();

    }

}
```

**Key Changes:**

* `IAsyncLifetime.InitializeAsync()` → `[Before(Test)]`
* `IAsyncLifetime.DisposeAsync()` → `[After(Test)]`
* More explicit and easier to understand at a glance

### Shared Context and Fixtures[​](#shared-context-and-fixtures "Direct link to Shared Context and Fixtures")

#### IClassFixture → ClassDataSource[​](#iclassfixture--classdatasource "Direct link to IClassFixture → ClassDataSource")

**xUnit Code:**

```
public class DatabaseFixture : IDisposable

{

    public DatabaseConnection Connection { get; }



    public DatabaseFixture()

    {

        Connection = new DatabaseConnection();

        Connection.Open();

    }



    public void Dispose()

    {

        Connection?.Close();

        Connection?.Dispose();

    }

}



public class UserRepositoryTests : IClassFixture<DatabaseFixture>

{

    private readonly DatabaseFixture _fixture;



    public UserRepositoryTests(DatabaseFixture fixture)

    {

        _fixture = fixture;

    }



    [Fact]

    public void GetUser_ReturnsUser()

    {

        var repo = new UserRepository(_fixture.Connection);

        var user = repo.GetUser(1);

        Assert.NotNull(user);

    }



    [Fact]

    public void GetAllUsers_ReturnsUsers()

    {

        var repo = new UserRepository(_fixture.Connection);

        var users = repo.GetAllUsers();

        Assert.NotEmpty(users);

    }

}
```

**TUnit Equivalent:**

```
public class DatabaseFixture : IDisposable

{

    public DatabaseConnection Connection { get; }



    public DatabaseFixture()

    {

        Connection = new DatabaseConnection();

        Connection.Open();

    }



    public void Dispose()

    {

        Connection?.Close();

        Connection?.Dispose();

    }

}



[ClassDataSource<DatabaseFixture>(Shared = SharedType.PerClass)]

public class UserRepositoryTests(DatabaseFixture fixture)

{

    [Test]

    public async Task GetUser_ReturnsUser()

    {

        var repo = new UserRepository(fixture.Connection);

        var user = repo.GetUser(1);

        await Assert.That(user).IsNotNull();

    }



    [Test]

    public async Task GetAllUsers_ReturnsUsers()

    {

        var repo = new UserRepository(fixture.Connection);

        var users = repo.GetAllUsers();

        await Assert.That(users).IsNotEmpty();

    }

}
```

**Key Changes:**

* `IClassFixture<T>` interface → `[ClassDataSource<T>(Shared = SharedType.PerClass)]` attribute
* Fixture injected via primary constructor
* `Shared = SharedType.PerClass` ensures one instance per test class

#### Collection Fixtures → Shared ClassDataSource[​](#collection-fixtures--shared-classdatasource "Direct link to Collection Fixtures → Shared ClassDataSource")

**xUnit Code:**

```
[CollectionDefinition("Database collection")]

public class DatabaseCollection : ICollectionFixture<DatabaseFixture>

{

}



public class DatabaseFixture : IDisposable

{

    public DatabaseConnection Connection { get; }



    public DatabaseFixture()

    {

        Connection = new DatabaseConnection();

        Connection.Open();

    }



    public void Dispose() => Connection?.Dispose();

}



[Collection("Database collection")]

public class UserTests : IClassFixture<DatabaseFixture>

{

    private readonly DatabaseFixture _fixture;



    public UserTests(DatabaseFixture fixture)

    {

        _fixture = fixture;

    }



    [Fact]

    public void CreateUser_Succeeds()

    {

        // Test using _fixture.Connection

    }

}



[Collection("Database collection")]

public class ProductTests : IClassFixture<DatabaseFixture>

{

    private readonly DatabaseFixture _fixture;



    public ProductTests(DatabaseFixture fixture)

    {

        _fixture = fixture;

    }



    [Fact]

    public void CreateProduct_Succeeds()

    {

        // Test using _fixture.Connection

    }

}
```

**TUnit Equivalent:**

```
public class DatabaseFixture : IDisposable

{

    public DatabaseConnection Connection { get; }



    public DatabaseFixture()

    {

        Connection = new DatabaseConnection();

        Connection.Open();

    }



    public void Dispose() => Connection?.Dispose();

}



[ClassDataSource<DatabaseFixture>(Shared = SharedType.Keyed, Key = "DatabaseCollection")]

public class UserTests(DatabaseFixture fixture)

{

    [Test]

    public async Task CreateUser_Succeeds()

    {

        _ = fixture.Connection;

    }

}



[ClassDataSource<DatabaseFixture>(Shared = SharedType.Keyed, Key = "DatabaseCollection")]

public class ProductTests(DatabaseFixture fixture)

{

    [Test]

    public async Task CreateProduct_Succeeds()

    {

        _ = fixture.Connection;

    }

}
```

**Key Changes:**

* `[Collection("name")]` → `[ClassDataSource<T>(Shared = SharedType.Keyed, Key = "name")]`
* No need for CollectionDefinition class
* All classes with same Key share the fixture instance

#### Assembly Fixture → ClassDataSource with PerAssembly[​](#assembly-fixture--classdatasource-with-perassembly "Direct link to Assembly Fixture → ClassDataSource with PerAssembly")

**xUnit doesn't have native assembly fixtures, but TUnit does:**

**TUnit Example:**

```
public class ApplicationFixture : IDisposable

{

    public IServiceProvider ServiceProvider { get; }



    public ApplicationFixture()

    {

        // Setup once for entire assembly

        ServiceProvider = ConfigureServices();

    }



    public void Dispose()

    {

        // Cleanup once after all tests

    }

}



[ClassDataSource<ApplicationFixture>(Shared = SharedType.PerAssembly)]

public class IntegrationTests(ApplicationFixture fixture)

{

    [Test]

    public async Task Test1()

    {

        var service = fixture.ServiceProvider.GetService<IMyService>();

        await Assert.That(service).IsNotNull();

    }

}
```

### Test Output[​](#test-output "Direct link to Test Output")

#### ITestOutputHelper → TestContext[​](#itestoutputhelper--testcontext "Direct link to ITestOutputHelper → TestContext")

**xUnit Code:**

```
public class LoggingTests

{

    private readonly ITestOutputHelper _output;



    public LoggingTests(ITestOutputHelper output)

    {

        _output = output;

    }



    [Fact]

    public void Test_WithLogging()

    {

        _output.WriteLine("Starting test");



        var result = CalculateResult();



        _output.WriteLine($"Result: {result}");

        Assert.True(result > 0);

    }

}
```

**TUnit Equivalent:**

```
public class LoggingTests

{

    [Test]

    public async Task Test_WithLogging(TestContext context)

    {

        context.Output.WriteLine("Starting test");



        var result = CalculateResult();



        context.Output.WriteLine($"Result: {result}");

        await Assert.That(result).IsGreaterThan(0);

    }

}
```

**Key Changes:**

* `ITestOutputHelper` injected in constructor → `TestContext` injected as method parameter
* Access output via `context.Output.WriteLine()`
* TestContext provides additional test metadata

#### Test Attachments[​](#test-attachments "Direct link to Test Attachments")

xUnit v3 introduced test attachments. TUnit also supports this capability:

**xUnit v3 Code:**

```
public class TestWithAttachments

{

    private readonly ITestContextAccessor _testContextAccessor;

    

    public TestWithAttachments(ITestContextAccessor testContextAccessor)

    {

        _testContextAccessor = testContextAccessor;

    }

    

    [Fact]

    public async Task Test_WithAttachment()

    {

        // Test logic

        var logPath = "test-log.txt";

        await File.WriteAllTextAsync(logPath, "test logs", Xunit.TestContext.Current.CancellationToken);

        

        Xunit.TestContext.Current.AddAttachment(logPath, "Test Log");

    }

}
```

**TUnit Equivalent:**

```
public class TestWithAttachments

{

    [Test]

    public async Task Test_WithAttachment()

    {

        // Test logic

        var logPath = "test-log.txt";

        await File.WriteAllTextAsync(logPath, "test logs");

        

        TestContext.Current!.Output.AttachArtifact(new Artifact

        {

            File = new FileInfo(logPath),

            DisplayName = "Test Log",

            Description = "Logs captured during test execution"  // Optional

        });

    }

}
```

For more information about working with test artifacts, including session-level artifacts and best practices, see the [Test Artifacts guide](/docs/writing-tests/artifacts.md).

### Traits and Categories[​](#traits-and-categories "Direct link to Traits and Categories")

#### Trait → Property[​](#trait--property "Direct link to Trait → Property")

**xUnit Code:**

```
public class FeatureTests

{

    [Fact]

    [Trait("Category", "Integration")]

    [Trait("Priority", "High")]

    public void ImportantIntegrationTest()

    {

        // Test implementation

    }

}
```

**TUnit Equivalent:**

```
public class FeatureTests

{

    [Test]

    [Property("Category", "Integration")]

    [Property("Priority", "High")]

    public async Task ImportantIntegrationTest()

    {

        // Test implementation

    }

}
```

**Key Changes:**

* `[Trait("key", "value")]` → `[Property("key", "value")]`
* Can be used for filtering: `--treenode-filter "/*/*/*/*[Category=Integration]"`

### Assertions[​](#assertions "Direct link to Assertions")

#### Basic Assertions[​](#basic-assertions "Direct link to Basic Assertions")

**xUnit Code:**

```
[Fact]

public void Assertions_Examples()

{

    Assert.Equal(5, 2 + 3);

    Assert.NotEqual(5, 2 + 2);

    Assert.True(5 > 3);

    Assert.False(5 < 3);

    Assert.Null(null);

    Assert.NotNull("value");

    Assert.Same(obj1, obj2);

    Assert.NotSame(obj1, obj3);

}
```

**TUnit Equivalent:**

```
[Test]

public async Task Assertions_Examples()

{

    await Assert.That(2 + 3).IsEqualTo(5);

    await Assert.That(2 + 2).IsNotEqualTo(5);

    await Assert.That(5 > 3).IsTrue();

    await Assert.That(5 < 3).IsFalse();

    await Assert.That((object?)null).IsNull();

    await Assert.That("value").IsNotNull();

    await Assert.That(obj1).IsSameReferenceAs(obj2);

    await Assert.That(obj1).IsNotSameReferenceAs(obj3);

}
```

#### Collection Assertions[​](#collection-assertions "Direct link to Collection Assertions")

**xUnit Code:**

```
[Fact]

public void Collection_Assertions()

{

    var list = new[] { 1, 2, 3 };



    Assert.Contains(2, list);

    Assert.DoesNotContain(5, list);

    Assert.Empty(Array.Empty<int>());

    Assert.NotEmpty(list);

    Assert.Equal(3, list.Length);

}
```

**TUnit Equivalent:**

```
[Test]

public async Task Collection_Assertions()

{

    var list = new[] { 1, 2, 3 };



    await Assert.That(list).Contains(2);

    await Assert.That(list).DoesNotContain(5);

    await Assert.That(Array.Empty<int>()).IsEmpty();

    await Assert.That(list).IsNotEmpty();

    await Assert.That(list).Count().IsEqualTo(3);

}
```

#### String Assertions[​](#string-assertions "Direct link to String Assertions")

**xUnit Code:**

```
[Fact]

public void String_Assertions()

{

    var text = "Hello, World!";



    Assert.Contains("World", text);

    Assert.DoesNotContain("xyz", text);

    Assert.StartsWith("Hello", text);

    Assert.EndsWith("!", text);

    Assert.Matches(@"H\w+", text);

}
```

**TUnit Equivalent:**

```
[Test]

public async Task String_Assertions()

{

    var text = "Hello, World!";



    await Assert.That(text).Contains("World");

    await Assert.That(text).DoesNotContain("xyz");

    await Assert.That(text).StartsWith("Hello");

    await Assert.That(text).EndsWith("!");

    await Assert.That(text).Matches(@"H\w+");

}
```

#### Exception Assertions[​](#exception-assertions "Direct link to Exception Assertions")

**xUnit Code:**

```
[Fact]

public void Exception_Assertions()

{

    Assert.Throws<ArgumentException>(() => ThrowsException());



    var ex = Assert.Throws<ArgumentException>(() => ThrowsException());

    Assert.Equal("paramName", ex.ParamName);

}



[Fact]

public async Task Async_Exception_Assertions()

{

    await Assert.ThrowsAsync<InvalidOperationException>(() => ThrowsExceptionAsync());

}
```

**TUnit Equivalent:**

```
[Test]

public async Task Exception_Assertions()

{

    Assert.Throws<ArgumentException>(() => ThrowsException());



    var ex = Assert.Throws<ArgumentException>(() => ThrowsException());

    await Assert.That(ex.ParamName).IsEqualTo("paramName");

}



[Test]

public async Task Async_Exception_Assertions()

{

    await Assert.ThrowsAsync<InvalidOperationException>(() => ThrowsExceptionAsync());

}
```

**Key Changes:**

* Sync exception assertions use `Assert.Throws`
* Async exception assertions use `Assert.ThrowsAsync`
* Returned exception can be further asserted on

### Complete Example: Real-World Test Class[​](#complete-example-real-world-test-class "Direct link to Complete Example: Real-World Test Class")

**xUnit Code:**

```
public class UserServiceTests : IClassFixture<DatabaseFixture>, IAsyncLifetime

{

    private readonly DatabaseFixture _dbFixture;

    private readonly ITestOutputHelper _output;

    private UserService _userService = null!;



    public UserServiceTests(DatabaseFixture dbFixture, ITestOutputHelper output)

    {

        _dbFixture = dbFixture;

        _output = output;

    }



    public async ValueTask InitializeAsync()

    {

        _userService = new UserService(_dbFixture.Connection);

        await _userService.InitializeAsync();

    }



    public ValueTask DisposeAsync() => ValueTask.CompletedTask;



    [Theory]

    [InlineData("john@example.com", "John")]

    [InlineData("jane@example.com", "Jane")]

    public async Task CreateUser_WithValidData_Succeeds(string email, string name)

    {

        _output.WriteLine($"Creating user: {name}");



        var user = await _userService.CreateUserAsync(email, name);



        Assert.NotNull(user);

        Assert.Equal(email, user.Email);

        Assert.Equal(name, user.Name);



        _output.WriteLine($"User created with ID: {user.Id}");

    }



    [Fact]

    public async Task GetUser_WhenNotFound_ThrowsException()

    {

        await Assert.ThrowsAsync<UserNotFoundException>(

            () => _userService.GetUserAsync(99999));

    }



    [Theory]

    [MemberData(nameof(GetInvalidEmails))]

    public async Task CreateUser_WithInvalidEmail_ThrowsException(string invalidEmail)

    {

        await Assert.ThrowsAsync<ArgumentException>(

            () => _userService.CreateUserAsync(invalidEmail, "Test"));

    }



    public static IEnumerable<object[]> GetInvalidEmails()

    {

        yield return new object[] { "" };

        yield return new object[] { "not-an-email" };

        yield return new object[] { "@example.com" };

    }

}
```

**TUnit Equivalent:**

```
[ClassDataSource<DatabaseFixture>(Shared = SharedType.PerClass)]

public class UserServiceTests(DatabaseFixture dbFixture)

{

    private UserService _userService = null!;



    [Before(Test)]

    public async Task Setup()

    {

        _userService = new UserService(dbFixture.Connection);

        await _userService.InitializeAsync();

    }



    [Test]

    [Arguments("john@example.com", "John")]

    [Arguments("jane@example.com", "Jane")]

    public async Task CreateUser_WithValidData_Succeeds(string email, string name, TestContext context)

    {

        context.Output.WriteLine($"Creating user: {name}");



        var user = await _userService.CreateUserAsync(email, name);



        await Assert.That(user).IsNotNull();

        await Assert.That(user.Email).IsEqualTo(email);

        await Assert.That(user.Name).IsEqualTo(name);



        context.Output.WriteLine($"User created with ID: {user.Id}");

    }



    [Test]

    public async Task GetUser_WhenNotFound_ThrowsException()

    {

        await Assert.ThrowsAsync<UserNotFoundException>(

            () => _userService.GetUserAsync(99999));

    }



    [Test]

    [MethodDataSource(nameof(GetInvalidEmails))]

    public async Task CreateUser_WithInvalidEmail_ThrowsException(string invalidEmail)

    {

        await Assert.ThrowsAsync<ArgumentException>(

            () => _userService.CreateUserAsync(invalidEmail, "Test"));

    }



    public static IEnumerable<string> GetInvalidEmails()

    {

        yield return "";

        yield return "not-an-email";

        yield return "@example.com";

    }

}
```

**Key Differences Summary:**

* Class-level fixtures use attributes instead of interfaces
* Setup/teardown use `[Before]`/`[After]` attributes instead of IAsyncLifetime
* Primary constructor for fixture injection
* TestContext injected as method parameter when needed
* All tests are async by default
* Data sources return strongly-typed values (not object\[])
* Fluent assertion syntax

## Code Coverage[​](#code-coverage "Direct link to Code Coverage")

TUnit includes built-in code coverage support. Do **not** use Coverlet — it is incompatible with TUnit's Microsoft.Testing.Platform.

See the [Code Coverage guide](/docs/extending/code-coverage.md) for setup and configuration.
