Background processing — change feed processors, message handlers, hosted services, timer triggers — runs on threads where the test framework's execution context is unavailable. This page explains how to correlate those operations back to the originating test.

Event-driven architectures? If your SUT is triggered entirely by consuming messages (no direct HTTP calls from the test), see Event-Driven Architecture Testing for the complete end-to-end guide. This page covers the lower-level mechanisms used under the hood.

Parallel test execution? If you need parallel-safe background correlation (v2.36.0+), see Parallel-Safe Background Correlation for TestCorrelationStore — a thread-safe alternative to GlobalFallback that requires no production code changes.

CurrentTestInfo.Fetcher (xUnit3, and equivalents in other frameworks) uses TestContext.Current.Test to determine the active test. This only works on the test runner thread — any background thread, task continuation, or callback will see TestContext.Current.Test as null, and the fetcher will return ("Unknown", "unknown").

Common scenarios where this occurs:

• Diagnostic report shows a large number of "Unknown" entries
• Sequence diagrams for tests that trigger background processing are missing operations
• Service Bus publishes triggered by change feed events don't appear in diagrams

TestIdentityScope is an AsyncLocal-based ambient scope that propagates test identity across async boundaries. It is the recommended approach when you control the code that dispatches background work.

// Before dispatching background work, push the test identity into scope:
using (TestIdentityScope.Begin(testName, testId))
{
    await TriggerBackgroundProcessing();
    // All tracking within this scope (and any async continuations) will use testName/testId
}

For SUT code that dispatches work via Task.Run or similar fire-and-forget patterns within an HTTP request, you can automatically establish TestIdentityScope from the incoming request's tracking headers using AddTestTrackingContextPropagation():

builder.ConfigureTestServices(services =>
{
    services.AddTestTrackingContextPropagation();
});

This registers TestTrackingContextMiddleware (via IStartupFilter) which reads the test-tracking-current-test-name and test-tracking-current-test-id headers from each incoming request and calls TestIdentityScope.Begin(name, id) for the duration of the request. Because AsyncLocal propagates into Task.Run, any background work dispatched during that request will inherit the test identity automatically — no manual TestIdentityScope.Begin() calls needed.

Idempotent (v3.0.20+): AddTestTrackingContextPropagation() is safe to call more than once — for example, from both a base WebApplicationFactory and a derived one. Only one TestTrackingContextStartupFilter will be registered regardless of how many times the method is called.

When to use this: Your SUT receives an HTTP request from the test, then dispatches fire-and-forget work (e.g. Task.Run(() => httpClient.PostAsync(...))) within that request. Without this middleware, the background thread would have no HttpContext and no TestIdentityScope, causing the tracking handler to silently skip logging. With it, the AsyncLocal scope flows into the background thread.

Resolution order for all trackers (v2.28.16+):

v2.28.22+: Priority 2 (CurrentTestInfoFetcher) now throws InvalidOperationException when invoked outside a test context. The resolver catches this and falls through to priorities 3–6. See Tracking Custom Dependencies#Test Context Availability for details.

See Tracking Custom Dependencies#Tracking Background Processing with TestIdentityScope (v2.28.5+) for full details and examples.

For event-driven architectures where an ASP.NET application listens to messages (Kafka, Service Bus, Event Hubs, Google Pub/Sub, MassTransit), test identity is automatically propagated through message headers — no manual TestIdentityScope.Begin() or GlobalFallback needed.

When a tracked producer sends a message during a test, the kronikol-test-name and kronikol-test-id headers are injected into the message metadata. When a tracked consumer receives that message, the headers are extracted and established as the ambient TestIdentityScope via SetFromMessage().

Test Thread                    Producer                         Consumer (Background Thread)
    │                              │                                │
    │── Produce("order-created") ──│                                │
    │   [headers injected:         │                                │
    │    kronikol-test-name + id]       │                                │
    │                              │── Message on topic ───────────>│
    │                              │                                │── Headers extracted
    │                              │                                │── TestIdentityScope.SetFromMessage()
    │                              │                                │── All tracking resolves to test

Propagation is enabled by default. To disable it (e.g. for performance-sensitive benchmarks):

var options = new KafkaTrackingOptions
{
    PropagateTestIdentity = false,  // Disable header injection/extraction
    // ...
};

All messaging extension option classes expose the same PropagateTestIdentity property.

When you cannot use TestIdentityScope (e.g. you don't control the dispatch point), use an instance-scoped tracker that explicitly sets the active test identity on the fixture:

public class ActiveTestTracker
{
    private readonly object _syncLock = new();
    private (string Name, string Id)? _activeTest;

    public void Set(string name, string id)
    {
        lock (_syncLock) { _activeTest = (name, id); }
    }

    public void Clear()
    {
        lock (_syncLock) { _activeTest = null; }
    }

    /// <summary>
    /// Tries TestContext.Current first (works on the test thread),
    /// falls back to the explicitly set active test (works on background threads).
    /// </summary>
    public (string Name, string Id) Fetcher()
    {
        var (name, id) = CurrentTestInfo.Fetcher();
        if (name != "Unknown")
            return (name, id);

        lock (_syncLock)
        {
            return _activeTest ?? ("Unknown", "unknown");
        }
    }
}

public class MyCollectionFixture : IAsyncLifetime
{
    public ActiveTestTracker TestTracker { get; } = new();

    public async ValueTask InitializeAsync()
    {
        // Pass TestTracker.Fetcher to ALL tracking configuration:

        // Cosmos tracking
        var cosmosOptions = new CosmosTrackingMessageHandlerOptions
        {
            ServiceName = "CosmosDB",
            CallerName = "My Service",
            CurrentTestInfoFetcher = TestTracker.Fetcher,
        };

        // HTTP tracking
        services.TrackDependenciesForDiagrams(new TestTrackingMessageHandlerOptions
        {
            CallerName = "My Service",
            CurrentTestInfoFetcher = TestTracker.Fetcher,
        });

        // Message tracking
        services.TrackMessagesForDiagrams(new MessageTrackerOptions
        {
            CallerName = "My Service",
            ServiceName = "Service Bus",
            CurrentTestInfoFetcher = TestTracker.Fetcher,
        });
    }

    public ValueTask DisposeAsync() => ValueTask.CompletedTask;
}

public class MyTestBase : IAsyncLifetime
{
    protected MyCollectionFixture Fixture { get; }

    public ValueTask InitializeAsync()
    {
        // Set BEFORE test runs — background threads from here on will resolve correctly
        // ⚠️ Safe here because InitializeAsync runs on the test thread.
        // v2.28.22+: Fetcher() throws InvalidOperationException if called
        // outside a test context (e.g. background thread or fixture constructor).
        var (name, id) = CurrentTestInfo.Fetcher();
        Fixture.TestTracker.Set(name, id);
        return ValueTask.CompletedTask;
    }

    public ValueTask DisposeAsync()
    {
        // Clear BEFORE logging — prevents stale attribution
        Fixture.TestTracker.Clear();

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

A static tracker breaks under parallel execution. Each fixture instance must own its tracker:

• Per-test fixtures: New fixture per test → new tracker → no contention
• Per-class fixtures: Tests within a class run sequentially (xUnit guarantee) → safe
• Per-collection fixtures: Tests within a collection run sequentially → safe
• Parallel collections: Each collection has its own fixture → own tracker → no cross-contamination

When pre-existing background threads (Change Feed Processor polling threads, Hangfire workers, hosted service loops) were started before TestIdentityScope.Begin(), the AsyncLocal value never propagates to them. GlobalFallback is a process-wide static fallback that these threads can read.

public class MyTestBase : IAsyncLifetime
{
    protected MyCollectionFixture Fixture { get; }

    public ValueTask InitializeAsync()
    {
        var (name, id) = CurrentTestInfo.Fetcher();
        // AsyncLocal scope for new async continuations:
        _scope = TestIdentityScope.Begin(name, id);
        // Static fallback for pre-existing threads:
        TestIdentityScope.SetGlobalFallback(name, id);
        return ValueTask.CompletedTask;
    }

    public ValueTask DisposeAsync()
    {
        _scope?.Dispose();
        TestIdentityScope.ClearGlobalFallback();
        DiagrammedTestRun.TestContexts.Enqueue(TestContext.Current);
        return ValueTask.CompletedTask;
    }

    private IDisposable? _scope;
}

Resolution order (v2.28.16+): Same as the #scenario-resolution-reference — HTTP headers → delegate → scope → GlobalFallback → null.

⚠ Parallel execution warning: GlobalFallback is a single process-wide value. It only works correctly when tests sharing the same background infrastructure run serially (e.g. within an xUnit collection fixture). This matches the existing ActiveTestTracker pattern's semantics — if your tests already run in parallel with shared infrastructure, use Solution 1 (TestIdentityScope.Begin) instead.

When a tracking handler captures an operation but cannot determine which test it belongs to, the operation is counted as Unknown in the diagnostic report.

Some Unknown entries are normal and expected:

• Background processing: Change feed processors, message handlers, hosted services — they have no HttpContext or test scope
• Application startup/teardown: Operations during WebApplicationFactory initialisation or disposal happen outside test scope
• Health checks and middleware: Periodic background operations from infrastructure

If all entries for a component are Unknown, investigate:

A typical diagnostic report shows:

• 0% Unknown for inbound HTTP handlers (API controller calls)
• 0% Unknown for synchronous outbound HTTP calls (typed HttpClients)
• 30-80% Unknown for Cosmos/Service Bus when async processing is involved
• 100% Unknown for components used only in background processing

When CosmosTrackingMessageHandler (or any extension handler) is constructed before IHttpContextAccessor is available (common with WebApplicationFactory where the Cosmos client is a singleton built during DI), use a lazy wrapper:

internal sealed class LazyHttpContextAccessor : IHttpContextAccessor
{
    private IHttpContextAccessor? _inner;

    public HttpContext? HttpContext
    {
        get => _inner?.HttpContext;
        set { if (_inner is not null) _inner.HttpContext = value; }
    }

    public void SetInner(IHttpContextAccessor inner) => _inner = inner;
}

Usage:

// 1. Create wrapper and assign to options BEFORE building the Cosmos client
var lazyAccessor = new LazyHttpContextAccessor();
cosmosTrackingOptions.HttpContextAccessor = lazyAccessor;

// 2. Build client — handler captures the lazyAccessor reference
var cosmos = InMemoryCosmos.Builder()
    .WrapHandler(h => new CosmosTrackingMessageHandler(cosmosTrackingOptions, h))
    .Build();

// 3. Wire the real accessor after WebApplicationFactory is available
lazyAccessor.SetInner(factory.Services.GetRequiredService<IHttpContextAccessor>());

Important: The wrapper must be assigned to options before calling WrapHandler. Setting options.HttpContextAccessor afterwards has no effect — the handler has already captured the value at construction time.

After implementing either solution, check the Diagnostic Report with DiagnosticMode = true. The "Unknown" count should either disappear or be reduced to expected background operations (e.g. initial container setup before any test starts).