refactor: separate test and lifecycle tracing

[thomhurst]

Summary

• keep exported backend traces as simple per-test parent-child trees for request navigation and log correlation
• auto-export the runner's TUnit test spans from TUnit.Aspire to the same OTLP backend used by the Aspire dashboard when DOTNET_DASHBOARD_OTLP_ENDPOINT_URL is present
• normalize the runner exporter endpoint to .../v1/traces so path-based OTLP backends like Seq also work correctly
• add a richer Aspire trace demo request that emits internal spans and nested HTTP calls for backend validation
• update the Aspire docs to describe the out-of-box backend trace behavior

Out-of-Box Backend Validation

Local Jaeger validation on April 16, 2026 using only DOTNET_DASHBOARD_OTLP_ENDPOINT_URL=http://127.0.0.1:4318 in the test runner and a real OtlpCorrelationIntegrationTests/TraceDemo_Request_ProducesNestedCorrelatedLogs run. No manual tracer provider was added to the test project.

Jaeger search/timeline view showing one trace with 10 spans across both services (TUnit.Aspire.Tests and api-service).

Jaeger trace waterfall showing the full request tree: test case -> test body -> GET /trace-demo -> internal spans -> nested HTTP spans.

Testing

• dotnet test TUnit.Aspire.Tests\TUnit.Aspire.Tests.csproj --framework net10.0 -- --treenode-filter "/*/*/TestTraceExporterTests/*"
• dotnet test TUnit.Aspire.Tests\TUnit.Aspire.Tests.csproj --framework net10.0 -- --treenode-filter "/*/*/BaggagePropagationHandlerTests/*"
• dotnet test TUnit.Aspire.Tests\TUnit.Aspire.Tests.csproj --framework net10.0 -- --treenode-filter "/*/*/OtlpReceiverTests/*"
• dotnet test TUnit.Aspire.Tests\TUnit.Aspire.Tests.csproj --framework net10.0 -- --treenode-filter "/*/*/OtlpCorrelationIntegrationTests/TraceDemo_Request_ProducesNestedCorrelatedLogs"
• DOTNET_DASHBOARD_OTLP_ENDPOINT_URL=http://127.0.0.1:4318 dotnet test TUnit.Aspire.Tests\TUnit.Aspire.Tests.csproj --framework net10.0 -- --treenode-filter "/*/*/OtlpCorrelationIntegrationTests/TraceDemo_Request_ProducesNestedCorrelatedLogs"
• dotnet build TUnit.Aspire\TUnit.Aspire.csproj -c Debug

[azure-pipelines]

Azure Pipelines:
1 pipeline(s) were filtered out due to trigger conditions.

[codacy-production]

Not up to standards ⛔

🔴 Issues 1 medium

Alerts:
⚠ 1 issue (≤ 0 issues of at least minor severity)

Results:
1 new issue

Category	Results
BestPractice	1 medium

View in Codacy

🟢 Metrics 74 complexity

Metric	Results
Complexity	74

View in Codacy

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

[azure-pipelines]

Azure Pipelines:
1 pipeline(s) were filtered out due to trigger conditions.

[claude]

Code Review: Separate Test and Lifecycle Tracing

This is a well-motivated architectural change that solves a real problem — per-test traces were polluted by session/class/assembly spans, making log correlation and backend rendering awkward. The refactor is largely clean and well-documented. Here are the issues I found, from most to least significant.

---

Issue 1: Double-Pass Baggage Injection in ActivityPropagationHandler — May Conflict with Registered Propagators

File: TUnit.AspNetCore.Core/Http/ActivityPropagationHandler.cs

InjectTraceContext(propagationActivity, request.Headers);
InjectBaggage(propagationActivity, request.Headers);

InjectTraceContext calls DistributedContextPropagator.Current.Inject(...). On .NET 8+ with OTel SDK configured, the current propagator is typically a composite of TraceContextPropagator + BaggagePropagator, so it already emits a W3C baggage header. Then InjectBaggage does headers.Remove("baggage") and re-adds a manually built version. This creates two problems:

1. It silently overrides the user's propagator configuration. If someone registers a custom BaggagePropagator (e.g., to add extra fields or use a different encoding), InjectBaggage will replace its output.
2. The two outputs can diverge. DistributedContextPropagator.Current.Inject may encode entries not directly on activity.Baggage (e.g., from Baggage.Current), while the manual builder only iterates activity.Baggage.

The comment says "Older target frameworks still default to Correlation-Context for baggage" — but this should be solved by always installing a known-good propagator at setup time (e.g., OpenTelemetry.Context.Propagation.TraceContextPropagator + BaggagePropagator) rather than patching the output after the fact.

Suggested approach: Either use TextMapPropagator directly to control exactly which propagators run, or check whether the baggage header is already present (as TUnitBaggagePropagationHandler does with !httpRequest.Headers.Contains(key)) before emitting the fallback. This would avoid silently overriding OTel SDK configuration.

---

Issue 2: ActivityPropagationHandlerTests Uses Reflection Magic Strings

File: TUnit.AspNetCore.Tests/ActivityPropagationHandlerTests.cs

var activityPropagationHandlerType = typeof(TUnitTestIdHandler).Assembly
    .GetType("TUnit.AspNetCore.ActivityPropagationHandler", throwOnError: true)!;

This uses a hardcoded fully-qualified type name to reflect into an internal sealed class. A rename or namespace change would compile fine but fail at runtime. Even with throwOnError: true, that's still a runtime breakage with an obscure error message.

Why this matters: The internal ActivityPropagationHandler(Func<HttpRequestMessage, Activity?> startActivity) constructor already exists purely for testing, so the seam is there. The missing piece is access.

Suggested approach: Add [assembly: InternalsVisibleTo("TUnit.AspNetCore.Tests")] to the TUnit.AspNetCore.Core project and reference the type directly. This preserves the internal visibility contract but makes the test refactor-safe.

---

Issue 3: Inconsistent Header Overwrite Behavior Between Handlers

ActivityPropagationHandler.InjectTraceContext always overwrites:

h.Remove(key);
h.TryAddWithoutValidation(key, value);

TUnitBaggagePropagationHandler (new code) never overwrites:

if (carrier is HttpRequestMessage httpRequest && key is not null && !httpRequest.Headers.Contains(key))
{
    httpRequest.Headers.TryAddWithoutValidation(key, value);
}

If a test author pre-sets a custom traceparent header on a request (a valid integration test pattern), ActivityPropagationHandler will silently discard it, while TUnitBaggagePropagationHandler would respect it. This asymmetry could produce hard-to-diagnose tracing issues when both handlers are in the pipeline. The two should agree on one policy.

---

Issue 4: FinishTestActivity Signature Change — Cancelled/Timeout Exception Visibility

File: TUnit.Engine/TestExecutor.cs

Previously FinishTestActivity(executableTest, capturedException) received the exception directly from the catch block. Now:

else if (result?.Exception is { } exception)
{
    TUnitActivitySource.RecordException(activity, exception);
}

The PR correctly adds:

TestState.Timeout => "fail",
TestState.Cancelled => "fail",

But result?.Exception may be null for cancellation (which sometimes surfaces as OperationCanceledException that isn't stored in the result). If the exception goes unrecorded, the span will show status=fail but have no error.type or exception.* attributes — backends like Seq/Jaeger will flag the test as failed with no trace of why.

Worth adding a test that verifies a cancelled test's activity has error.type set, or documenting that cancel exceptions aren't attributed.

---

Issue 5: Activity.Current = null in TestCoordinator Is an Implicit Contract

File: TUnit.Engine/Services/TestExecution/TestCoordinator.cs

// Per-test cleanup has completed...
System.Diagnostics.Activity.Current = null;
// ...
var hookExceptions = await _testExecutor.ExecuteAfterClassAssemblyHooks(...);
// ...
TestExecutor.FinishTestActivity(test);

Setting Activity.Current = null mid-method before calling async cleanup is an implicit convention that future contributors need to understand. The comment is good, but this creates a subtle invariant: the test activity must never be set as Activity.Current anywhere between cleanup and FinishTestActivity, or it'll be leaked into class/session cleanup.

Suggested approach: Extract the null-setting into a small method with a clear name like DetachTestActivityFromAmbientContext(), or restructure so the post-cleanup logic runs in a new async context (fresh AsyncLocal snapshot). This makes the contract explicit rather than implicit via comment.

---

Minor: GetSourceForSharedType Moves Shared Fixture Spans to Opt-In Source

File: TUnit.Core/TUnitActivitySource.cs

internal static ActivitySource GetSourceForSharedType(SharedType? sharedType) =>
    sharedType is not null and not SharedType.None
        ? LifecycleSource
        : Source;

Shared fixture setup/teardown now emits to TUnit.Lifecycle. Users who subscribe only to "TUnit" (common pattern from existing docs) will silently lose shared fixture spans from their traces and HTML report. Since shared fixture failures often explain test failures, this could make debugging harder.

The docs do mention adding "TUnit.Lifecycle", but the migration path for existing users who only see "TUnit" should be clearer — perhaps a note in the HTML report or a diagnostic message when lifecycle spans are present but unsubscribed.

---

Positive notes

• Removing ActivityLink from test case to class activity is the right call — links are poorly supported in most backends and added complexity without clear benefit.
• The CopyBaggage fallback for WebApplicationFactory is a pragmatic fix with a good explanatory comment.
• Adding tunit.session.id, tunit.assembly.name, and tunit.class.namespace directly to the test case span is excellent for backends that need to correlate without navigating the lifecycle source.
• The TestState.Timeout/Cancelled => "fail" fix is a genuine correctness improvement.
• Backend validation with real Seq screenshots is a great addition to the PR description.

Overall this is solid work. The main concerns are the double-pass baggage injection potentially conflicting with OTel SDK propagators, and the reflection-based test instantiation pattern. The others are smaller design points worth addressing.