Quick Start (xUnit)

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

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

1. Install Packages

dotnet add package TestTrackingDiagrams.XUnit
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.XUnit;

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.XUnit;

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
                        {
                            CallingServiceName = "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"
        });
}

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\net8.0\Reports\:

File	Description
ComponentSpecifications.yml	YAML specification document
ComponentSpecificationsWithExamples.html	HTML specification with embedded diagrams
FeaturesReport.html	HTML test run report with diagrams and execution summary