feat: auto-propagate test trace context through IHttpClientFactory

[thomhurst]

Summary

• Registers TUnitHttpClientFilter : IHttpMessageHandlerBuilderFilter in TestWebApplicationFactory.GetIsolatedFactory so every IHttpClientFactory pipeline built inside the SUT (AddHttpClient<T>(), named clients, typed clients) auto-prepends ActivityPropagationHandler + TUnitTestIdHandler. Outbound HTTP from the SUT to downstream services now carries traceparent, baggage, and X-TUnit-TestId without the user having to call .AddHttpMessageHandler<>() per registration.
• New opt-out: WebApplicationTestOptions.AutoPropagateHttpClientFactory (default true). Set false when the SUT already instruments outbound HTTP (e.g. OpenTelemetry HttpClient instrumentation).
• De-duplicates the shared handler-prepending logic across TestWebApplicationFactory.CreateDefaultClient, TracedWebApplicationFactory.CreateClient/CreateDefaultClient, and the new filter via TUnitHttpClientFilter.PrependPropagationHandlers.
• Defensive guard in TUnitTestIdHandler.SendAsync so the X-TUnit-TestId header is never added twice when an outer handler already set it (matches the pre-existing traceparent guard).
• Docs: removes the manual .AddHttpMessageHandler<ActivityPropagationHandler>() recipe from distributed-tracing.md + opentelemetry.md, and lists the new auto-behavior (plus opt-out) in aspnet.md Quick Start.

Closes #5590.

Test plan

• New IHttpClientFactoryPropagationTests asserts outbound call via SUT's named IHttpClientFactory client carries traceparent, baggage, X-TUnit-TestId, and the current test's TraceId.
• New IHttpClientFactoryPropagationOptOutTests asserts no propagation headers on the downstream hop when AutoPropagateHttpClientFactory = false.
• Full TUnit.AspNetCore.Tests suite green (23/23 on net10.0) — covers existing ActivityPropagationHandler, baggage correlation, hosted-service flow suppression, minimal API, and HTTP exchange capture tests.
• CI to confirm on net8.0 + net9.0.

[claude]

Code Review

Summary

This is a well-designed feature. Using IHttpMessageHandlerBuilderFilter is the correct ASP.NET Core extension point for intercepting every IHttpClientFactory pipeline, TryAddEnumerable is the right registration call, and the PrependPropagationHandlers static helper nicely removes the duplicated array-construction code that existed in three places. Tests cover both the happy-path and the opt-out case. Good work overall.

---

Issues to address

1. Handler instances in the filter are shared across concurrent requests

// TUnitHttpClientFilter.cs
builder.AdditionalHandlers.Insert(0, new ActivityPropagationHandler());
builder.AdditionalHandlers.Insert(1, new TUnitTestIdHandler());

IHttpClientFactory caches handler pipelines per named client — the same handler objects are reused for every request on that client until the pipeline expires. If multiple tests run in parallel and each makes an outbound HTTP call through the same named client, the same TUnitTestIdHandler instance handles all of them concurrently.

TUnitTestIdHandler.SendAsync reads from TestContext.Current (ambient/async-local), which is per-async-flow, so that specific access is fine. However, both handler classes should be documented as intentionally stateless and thread-safe — a future contributor adding instance state to either handler would break parallel test runs silently. A brief comment in TUnitHttpClientFilter noting this expectation would prevent that footgun.

2. Handler insertion order is subtly fragile

next(builder);  // may leave AdditionalHandlers non-empty
builder.AdditionalHandlers.Insert(0, new ActivityPropagationHandler());
builder.AdditionalHandlers.Insert(1, new TUnitTestIdHandler());

After next(builder) runs, AdditionalHandlers could already contain SUT-registered handlers. Insert(0) then Insert(1) correctly places TUnit handlers at the front (outermost position), but the intent is non-obvious. A comment would prevent future refactors from accidentally reversing the order:

next(builder);
// Insert at outermost positions so TUnit headers are written before
// any SUT-configured handlers execute.
builder.AdditionalHandlers.Insert(0, new ActivityPropagationHandler());
builder.AdditionalHandlers.Insert(1, new TUnitTestIdHandler());

3. Opt-out test does not assert absence of baggage

// IHttpClientFactoryPropagationOptOutTests.cs
await Assert.That(echoed).DoesNotContain(TUnitTestIdHandler.HeaderName);
await Assert.That(echoed).DoesNotContain("traceparent:");
// baggage is not checked

The positive test asserts all three headers (traceparent, baggage, X-TUnit-TestId). The opt-out test should mirror that by asserting absence of baggage: as well — unless ActivityPropagationHandler intentionally omits baggage when there is no ambient activity. If so, add a comment explaining the asymmetry so future reviewers don't flag it as an oversight.

---

Minor observations

• WebApplicationTestOptions is a record — mutating properties in ConfigureTestOptions is a bit surprising for a record type. Not a new issue introduced by this PR; the new property follows the existing pattern correctly.
• IHttpMessageHandlerBuilderFilter is not deprecated across net8.0/net9.0/net10.0, so the extension point is sound.
• The docs updates are accurate and removing the stale "tracking automation: #5590" note is appreciated.

---

Verdict

The feature solves a real pain point using the right ASP.NET Core primitives. The handler-sharing concern (point 1) is the most important thing to verify — confirm both handlers are safe under concurrent invocations, then document that expectation in TUnitHttpClientFilter so it stays true.

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 0 complexity

Metric	Results
Complexity	0

View in Codacy

_{TIP This summary will be updated as you push new changes. Give us feedback}

[claude]

Code Review — Follow-up

All three issues raised in the previous review have been addressed. Here's the verification:

Previous issues — resolved

1. Handler-sharing / thread-safety documentation ✅
The TUnitHttpClientFilter XML doc now explicitly states:

"Both handler types must remain stateless and thread-safe … do not add instance fields capturing per-request state to either handler."

This is exactly the right place for the warning — it's on the type itself so future contributors will see it before touching the handlers.

2. Insertion-order comment ✅

// Insert at outermost positions so TUnit headers are emitted before any
// SUT-registered handler can run. Order must stay ActivityPropagationHandler
// first (writes traceparent/baggage) then TUnitTestIdHandler (writes X-TUnit-TestId).
builder.AdditionalHandlers.Insert(0, new ActivityPropagationHandler());
builder.AdditionalHandlers.Insert(1, new TUnitTestIdHandler());

Intent is now clear.

3. Opt-out test missing baggage: assertion ✅

await Assert.That(echoed).DoesNotContain(TUnitTestIdHandler.HeaderName);
await Assert.That(echoed).DoesNotContain("traceparent:");
await Assert.That(echoed).DoesNotContain("baggage:");

All three headers are now asserted absent in the opt-out path, matching the positive-path test.

---

Fresh observations

Design: two-sided instrumentation is correctly separated. CreateDefaultClient / TracedWebApplicationFactory instrument the test→SUT side; the IHttpMessageHandlerBuilderFilter instruments the SUT→downstream side. These are orthogonal, non-overlapping, and the AutoPropagateHttpClientFactory flag correctly scopes only the latter. No conflict.

TryAddEnumerable with ServiceDescriptor.Singleton — correct choice. Prevents double-registration if GetIsolatedFactory is called more than once or if user registers their own filter.

HeaderEchoHandler in TestWebApp is a clean, minimal test double. The explicit Activity start in SutHttpClientFactory_Propagates_TestContextHeaders ensures Activity.Current is non-null for the propagation handlers — this is the right setup, not a test smell.

TracedWebApplicationFactory always prepends via PrependPropagationHandlers regardless of AutoPropagateHttpClientFactory. This is correct since TracedWebApplicationFactory predates and is independent of the WebApplicationTestOptions lifecycle.

---

Verdict

The implementation is clean, well-documented, and the tests are thorough. Nothing new to block on. Ready to merge pending CI on net8.0 + net9.0 (as noted in the test plan).