Quick Start (xUnit)

This is the simplest integration path. For other frameworks see the Framework Integration Guides page.

For the full xUnit v3 integration guide including architecture summary, customisation options, and troubleshooting, see Integration xUnit3. For xUnit v2, see Integration xUnit2.

1. Install Packages

dotnet add package TestTrackingDiagrams.xUnit3
dotnet add package Microsoft.AspNetCore.Mvc.Testing

2. Create the Test Run Fixture

The test run fixture is a collection fixture that lives for the entire test run. Reports are generated in its Dispose method.

using TestTrackingDiagrams;
using TestTrackingDiagrams.xUnit3;

public class TestRun : DiagrammedTestRun, IDisposable
{
    public void Dispose()
    {
        EndRunTime = DateTime.UtcNow;
        XUnitReportGenerator.CreateStandardReportsWithDiagrams(
            TestContexts, StartRunTime, EndRunTime,
            new ReportConfigurationOptions
            {
                SpecificationsTitle = "My API Specifications"
            });
    }
}

3. Define the Test Collection

[CollectionDefinition(DiagrammedComponentTest.DiagrammedTestCollectionName)]
public class DiagrammedTestCollection : ICollectionFixture<TestRun>;

4. Create a Base Fixture

The base fixture creates a WebApplicationFactory with HTTP tracking wired in, and provides each test with its own HttpClient.

using TestTrackingDiagrams.xUnit3;

public class BaseFixture : DiagrammedComponentTest
{
    private static readonly WebApplicationFactory<Program> Factory;

    static BaseFixture()
    {
        Factory = new WebApplicationFactory<Program>()
            .WithWebHostBuilder(builder =>
            {
                builder.ConfigureServices(services =>
                {
                    // Track HTTP calls FROM the SUT to its dependencies
                    services.TrackDependenciesForDiagrams(
                        new XUnitTestTrackingMessageHandlerOptions
                        {
                            CallerName = "My API",
                            PortsToServiceNames =
                            {
                                { 80, "My API" },
                                { 5001, "Downstream Service" }
                            }
                        });
                });
            });
    }

    // Track HTTP calls TO the SUT from the test
    protected HttpClient Client { get; } = Factory.CreateTestTrackingClient(
        new XUnitTestTrackingMessageHandlerOptions
        {
            FixedNameForReceivingService = "My API"
        });
}

⚠️ Using a custom fixture? If you're not inheriting from DiagrammedComponentTest, you must manually enqueue the test context in every test's DisposeAsync(). Without this, your report will be empty:

public ValueTask DisposeAsync()
{
    DiagrammedTestRun.TestContexts.Enqueue(TestContext.Current);
    return ValueTask.CompletedTask;
}

5. Write a Test

[Endpoint("/api/cake")]
public class CakeFeature : BaseFixture
{
    [Fact, HappyPath]
    public async Task Creating_a_cake_successfully()
    {
        var response = await Client.PostAsJsonAsync("/api/cake",
            new { Milk = "whole", Eggs = "free-range", Flour = "plain" });

        response.StatusCode.Should().Be(HttpStatusCode.OK);
    }
}

6. Run and View Reports

dotnet test

After the tests complete, open the three generated files in bin/Debug/net10.0/Reports/:

File	Description
Specifications.yml	YAML specification document
Specifications.html	HTML specification with embedded diagrams
TestRunReport.html	HTML test run report with diagrams and execution summary

See Generated Reports for the full list of output files, including optional CI summary and component diagrams.