Add scope-aware initialization and disposal OpenTelemetry spans to trace timeline and HTML report

TUnit.Core/Attributes/TestData/ClassDataSourceAttribute.cs

@@ -31,7 +31,7 @@ namespace TUnit.Core;
 /// </code>
 /// </example>
 [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method | AttributeTargets.Property | AttributeTargets.Parameter, AllowMultiple = true)]
-public sealed class ClassDataSourceAttribute : UntypedDataSourceGeneratorAttribute
+public sealed class ClassDataSourceAttribute : UntypedDataSourceGeneratorAttribute, ITraceScopeProvider
 {
     private Type[] _types;
 
@@ -180,7 +180,7 @@ public ClassDataSourceAttribute(params Type[] types)
 /// </example>
 [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method | AttributeTargets.Property | AttributeTargets.Parameter, AllowMultiple = true)]
 public sealed class ClassDataSourceAttribute<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors | DynamicallyAccessedMemberTypes.NonPublicConstructors | DynamicallyAccessedMemberTypes.PublicProperties | DynamicallyAccessedMemberTypes.NonPublicProperties)] T>
-    : DataSourceGeneratorAttribute<T>
+    : DataSourceGeneratorAttribute<T>, ITraceScopeProvider
 {
     public SharedType Shared { get; set; } = SharedType.None;
     public string Key { get; set; } = string.Empty;

TUnit.Core/Attributes/TestData/ClassDataSourceAttribute_2.cs

@@ -7,7 +7,7 @@ namespace TUnit.Core;
 public sealed class ClassDataSourceAttribute<
     [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors | DynamicallyAccessedMemberTypes.NonPublicConstructors | DynamicallyAccessedMemberTypes.PublicProperties | DynamicallyAccessedMemberTypes.NonPublicProperties)] T1,
     [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors | DynamicallyAccessedMemberTypes.NonPublicConstructors | DynamicallyAccessedMemberTypes.PublicProperties | DynamicallyAccessedMemberTypes.NonPublicProperties)] T2>
-    : DataSourceGeneratorAttribute<T1, T2>
+    : DataSourceGeneratorAttribute<T1, T2>, ITraceScopeProvider
     where T1 : new()
     where T2 : new()
 {

TUnit.Core/Attributes/TestData/ClassDataSourceAttribute_3.cs

@@ -8,7 +8,7 @@ public sealed class ClassDataSourceAttribute<
     [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors | DynamicallyAccessedMemberTypes.NonPublicConstructors | DynamicallyAccessedMemberTypes.PublicProperties | DynamicallyAccessedMemberTypes.NonPublicProperties)] T1,
     [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors | DynamicallyAccessedMemberTypes.NonPublicConstructors | DynamicallyAccessedMemberTypes.PublicProperties | DynamicallyAccessedMemberTypes.NonPublicProperties)] T2,
     [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors | DynamicallyAccessedMemberTypes.NonPublicConstructors | DynamicallyAccessedMemberTypes.PublicProperties | DynamicallyAccessedMemberTypes.NonPublicProperties)] T3>
-    : DataSourceGeneratorAttribute<T1, T2, T3>
+    : DataSourceGeneratorAttribute<T1, T2, T3>, ITraceScopeProvider
     where T1 : new()
     where T2 : new()
     where T3 : new()

TUnit.Core/Attributes/TestData/ClassDataSourceAttribute_4.cs

@@ -9,7 +9,7 @@ public sealed class ClassDataSourceAttribute<
     [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors | DynamicallyAccessedMemberTypes.NonPublicConstructors | DynamicallyAccessedMemberTypes.PublicProperties | DynamicallyAccessedMemberTypes.NonPublicProperties)] T2,
     [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors | DynamicallyAccessedMemberTypes.NonPublicConstructors | DynamicallyAccessedMemberTypes.PublicProperties | DynamicallyAccessedMemberTypes.NonPublicProperties)] T3,
     [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors | DynamicallyAccessedMemberTypes.NonPublicConstructors | DynamicallyAccessedMemberTypes.PublicProperties | DynamicallyAccessedMemberTypes.NonPublicProperties)] T4>
-    : DataSourceGeneratorAttribute<T1, T2, T3, T4>
+    : DataSourceGeneratorAttribute<T1, T2, T3, T4>, ITraceScopeProvider
     where T1 : new()
     where T2 : new()
     where T3 : new()

TUnit.Core/Attributes/TestData/ClassDataSourceAttribute_5.cs

@@ -10,7 +10,7 @@ public sealed class ClassDataSourceAttribute<
     [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors | DynamicallyAccessedMemberTypes.NonPublicConstructors | DynamicallyAccessedMemberTypes.PublicProperties | DynamicallyAccessedMemberTypes.NonPublicProperties)] T3,
     [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors | DynamicallyAccessedMemberTypes.NonPublicConstructors | DynamicallyAccessedMemberTypes.PublicProperties | DynamicallyAccessedMemberTypes.NonPublicProperties)] T4,
     [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors | DynamicallyAccessedMemberTypes.NonPublicConstructors | DynamicallyAccessedMemberTypes.PublicProperties | DynamicallyAccessedMemberTypes.NonPublicProperties)] T5>
-    : DataSourceGeneratorAttribute<T1, T2, T3, T4, T5>
+    : DataSourceGeneratorAttribute<T1, T2, T3, T4, T5>, ITraceScopeProvider
     where T1 : new()
     where T2 : new()
     where T3 : new()

TUnit.Core/Attributes/TestData/ITraceScopeProvider.cs

@@ -0,0 +1,13 @@
+namespace TUnit.Core;
+
+/// <summary>
+/// Implemented by data source attributes that expose <see cref="SharedType"/> information.
+/// Used by the engine to parent initialization spans under the correct activity.
+/// </summary>
+internal interface ITraceScopeProvider
+{
+    /// <summary>
+    /// Returns the <see cref="SharedType"/> for each generated object, in parameter order.
+    /// </summary>
+    IEnumerable<SharedType> GetSharedTypes();
+}

TUnit.Core/TUnitActivitySource.cs

@@ -11,17 +11,95 @@ internal static class TUnitActivitySource
 
     internal static readonly ActivitySource Source = new("TUnit", Version);
 
+    // Span names used across the engine and HTML report.
+    internal const string SpanTestSession = "test session";
+    internal const string SpanTestAssembly = "test assembly";
+    internal const string SpanTestSuite = "test suite";
+    internal const string SpanTestCase = "test case";
+
+    // Tag keys used across init/dispose spans and the HTML report.
+    internal const string TagTestId = "tunit.test.id";
+    internal const string TagTestClass = "tunit.test.class";
+    internal const string TagTraceScope = "tunit.trace.scope";
+
+    /// <summary>
+    /// Returns a human-readable type name suitable for span labels.
+    /// Strips the namespace but preserves nesting (Outer.Inner) and cleans up
+    /// generic arity suffixes (MySource`1 → MySource&lt;T&gt;).
+    /// </summary>
+    internal static string GetReadableTypeName(Type type)
+    {
+        var name = type.FullName ?? type.Name;
+
+        // Strip namespace: take everything after the last '.' that isn't part of nesting
+        var nsEnd = name.LastIndexOf('.');
+        if (nsEnd >= 0 && type.Namespace is { Length: > 0 })
+        {
+            name = name[type.Namespace.Length..].TrimStart('.');
+        }
+
+        // Replace '+' nesting separator with '.'
+        name = name.Replace('+', '.');
+
+        // Clean up generic arity suffixes: MySource`1 → MySource
+        var backtick = name.IndexOf('`');
+        if (backtick >= 0)
+        {
+            name = name[..backtick];
+        }
+
+        return name;
+    }
+
     internal static Activity? StartActivity(
         string name,
         ActivityKind kind = ActivityKind.Internal,
         ActivityContext parentContext = default,
         IEnumerable<KeyValuePair<string, object?>>? tags = null)
     {
-        // StartActivity returns null when no listener is sampling this source,
-        // so the HasListeners() check is implicit. We rely on the framework behavior.
         return Source.StartActivity(name, kind, parentContext, tags);
     }
 
+    /// <summary>
+    /// Runs <paramref name="action"/> inside an OpenTelemetry span, handling
+    /// Activity.Current save/restore, error recording, and span stop/dispose.
+    /// </summary>
+    internal static async Task RunWithSpanAsync(
+        string name,
+        ActivityContext parentContext,
+        IEnumerable<KeyValuePair<string, object?>> tags,
+        Func<Task> action)
+    {
+        Activity? activity = null;
+        var previousActivity = Activity.Current;
+
+        if (Source.HasListeners())
+        {
+            activity = Source.StartActivity(name, ActivityKind.Internal, parentContext, tags);
+            if (activity is not null)
+            {
+                Activity.Current = activity;
+            }
+        }
+
+        try
+        {
+            await action();
+        }
+        catch (Exception ex)
+        {
+            RecordException(activity, ex);
+            throw;
+        }
+        finally
+        {
+            // Activity.Current is AsyncLocal — restore so the ambient context on this
+            // execution path is not permanently set to the span we just stopped.
+            StopActivity(activity);
+            Activity.Current = previousActivity;
+        }
+    }
+
     internal static void RecordException(Activity? activity, Exception exception)
     {
         if (activity is null)
@@ -51,6 +129,20 @@ internal static void StopActivity(Activity? activity)
         activity.Stop();
         activity.Dispose();
     }
+
+    /// <summary>
+    /// Maps a <see cref="SharedType"/> to its trace scope tag value.
+    /// Keyed objects map to "session" because their lifetime is session-scoped
+    /// (shared across classes and assemblies via matching keys).
+    /// </summary>
+    internal static string GetScopeTag(SharedType? sharedType) => sharedType switch
+    {
+        SharedType.PerTestSession => "session",
+        SharedType.PerAssembly => "assembly",
+        SharedType.PerClass => "class",
+        SharedType.Keyed => "session",
+        _ => "test"
+    };
 }
 
 #endif

TUnit.Core/TraceScopeRegistry.cs

@@ -0,0 +1,64 @@
+#if NET
+using System.Runtime.CompilerServices;
+
+namespace TUnit.Core;
+
+/// <summary>
+/// Thread-safe registry that maps data source objects to their trace scope.
+/// Used by the engine to parent initialization and disposal OpenTelemetry spans
+/// under the correct activity (session, assembly, class, or test).
+/// </summary>
+/// <remarks>
+/// Objects are registered by the engine (TestBuilder, PropertyInjector) when data source
+/// attributes implement <see cref="ITraceScopeProvider"/>. The engine reads the scope
+/// during initialization to determine the parent activity for each object's trace span.
+/// Uses <see cref="ConditionalWeakTable{TKey,TValue}"/> so that per-test data source objects
+/// can be garbage-collected after their tests complete, rather than being held alive for the
+/// entire session. ConditionalWeakTable inherently uses reference equality.
+/// </remarks>
+internal static class TraceScopeRegistry
+{
+    private static readonly ConditionalWeakTable<object, StrongBox<SharedType>> Scopes = new();
+
+    /// <summary>
+    /// Registers trace scopes for data objects produced by a data source attribute.
+    /// If the attribute implements <see cref="ITraceScopeProvider"/>, each object is
+    /// paired with the corresponding <see cref="SharedType"/> from the provider.
+    /// First registration wins — subsequent calls for the same instance are no-ops.
+    /// </summary>
+    internal static void RegisterFromDataSource(IDataSourceAttribute dataSource, object?[]? objects)
+    {
+        if (objects is null || objects.Length == 0)
+        {
+            return;
+        }
+
+        if (dataSource is not ITraceScopeProvider traceScopeProvider)
+        {
+            return;
+        }
+
+        using var enumerator = traceScopeProvider.GetSharedTypes().GetEnumerator();
+        for (var i = 0; i < objects.Length; i++)
+        {
+            var sharedType = enumerator.MoveNext() ? enumerator.Current : SharedType.None;
+            if (objects[i] is not null && !Scopes.TryGetValue(objects[i]!, out _))
+            {
+                // TryGetValue above is a fast-path to avoid allocating the closure below
+                // on re-registration. GetValue is the atomic operation that enforces
+                // first-registration-wins semantics.
+                Scopes.GetValue(objects[i]!, _ => new StrongBox<SharedType>(sharedType));
+            }
+        }
+    }
+
+    /// <summary>
+    /// Returns the <see cref="SharedType"/> for an object, or <c>null</c> if unregistered.
+    /// Unregistered objects (e.g., the test class instance) default to per-test scope.
+    /// </summary>
+    internal static SharedType? GetSharedType(object obj)
+    {
+        return Scopes.TryGetValue(obj, out var box) ? box.Value : null;
+    }
+}
+#endif

TUnit.Core/Tracking/ObjectTracker.cs

@@ -220,6 +220,9 @@ private async ValueTask UntrackObject(object? obj)
 
         if (shouldDispose)
         {
+            // TODO: Add disposal span for shared objects here to match the init spans
+            // created in ObjectLifecycleService.InitializeWithSpanAsync. Currently only
+            // per-test disposal gets a span (via TestCoordinator.DisposeTestInstanceWithSpanAsync).
             await disposer.DisposeAsync(obj).ConfigureAwait(false);
         }
     }

TUnit.Engine/Building/TestBuilder.cs

@@ -210,6 +210,12 @@ public async Task<IEnumerable<AbstractExecutableTest>> BuildTestsFromMetadataAsy
                     var classDataResult = await classDataFactory() ?? [];
                     var classData = DataUnwrapper.Unwrap(classDataResult);
 
+#if NET
+                    // Register scope for class data objects from the simple path.
+                    // Also registered in the repeat loop below for re-fetched instances.
+                    TraceScopeRegistry.RegisterFromDataSource(classDataSource, classData);
+#endif
+
                     // Initialize objects before method data sources are evaluated.
                     // ObjectInitializer is phase-aware and will only initialize IAsyncDiscoveryInitializer during Discovery.
                     await InitializeClassDataAsync(classData);
@@ -293,6 +299,14 @@ await _objectLifecycleService.RegisterObjectAsync(
                                 classData = classDataUnwrapped;
                                 var (methodData, methodRowMetadata) = DataUnwrapper.UnwrapWithTypesAndMetadata(await methodDataFactory() ?? [], metadata.MethodMetadata.Parameters);
 
+#if NET
+                                // Re-register: classDataFactory() was called again above and may return
+                                // a different instance for non-shared objects. First-registration-wins
+                                // semantics make this a no-op for the same instance.
+                                TraceScopeRegistry.RegisterFromDataSource(classDataSource, classData);
+                                TraceScopeRegistry.RegisterFromDataSource(methodDataSource, methodData);
+#endif
+
                                 // Extract and merge metadata from data source attributes and TestDataRow wrappers
                                 var classAttrMetadata = DataSourceMetadataExtractor.ExtractFromAttribute(classDataSource);
                                 var methodAttrMetadata = DataSourceMetadataExtractor.ExtractFromAttribute(methodDataSource);

TUnit.Engine/Reporters/Html/ActivityCollector.cs

@@ -169,9 +169,9 @@ private static string EnrichSpanName(Activity activity)
         // Look up the semantic name tag to produce a more descriptive label
         var tagKey = displayName switch
         {
-            "test case" => "test.case.name",
-            "test suite" => "test.suite.name",
-            "test assembly" => "tunit.assembly.name",
+            TUnitActivitySource.SpanTestCase => "test.case.name",
+            TUnitActivitySource.SpanTestSuite => "test.suite.name",
+            TUnitActivitySource.SpanTestAssembly => "tunit.assembly.name",
             _ => null
         };
 

TUnit.Engine/Reporters/Html/HtmlReportGenerator.cs

@@ -1476,9 +1476,19 @@ function renderSuiteTrace(className) {
     return '<div class="suite-trace"><div class="tl-toggle">' + tlArrow + 'Class Timeline</div><div class="tl-content"><div class="tl-content-inner"><div class="tl-content-pad">' + renderSpanRows(filtered, 'suite-' + className) + '</div></div></div></div>';
 }
 
-// Global timeline: session + assembly + suite spans
+// Global timeline: session + assembly + suite + shared init/dispose spans (not per-test)
+function isGlobalTimelineSpan(s) {
+    var t = s.spanType;
+    if (t === 'test session' || t === 'test assembly' || t === 'test suite') return true;
+    // Include init/dispose spans that are NOT per-test scope (shared prerequisites)
+    if (t && (t.startsWith('initialize ') || t.startsWith('dispose '))) {
+        var scopeTag = (s.tags||[]).find(function(tag){ return tag.key === 'tunit.trace.scope'; });
+        return scopeTag && scopeTag.value !== 'test';
+    }
+    return false;
+}
 function renderGlobalTimeline() {
-    const topSpans = spans.filter(s => s.spanType === 'test session' || s.spanType === 'test assembly' || s.spanType === 'test suite');
+    const topSpans = spans.filter(isGlobalTimelineSpan);
     if (!topSpans.length) return '';
     return '<div class="global-trace"><div class="tl-toggle">' + tlArrow + 'Execution Timeline</div><div class="tl-content"><div class="tl-content-inner"><div class="tl-content-pad">' + renderSpanRows(topSpans, 'global') + '</div></div></div></div>';
 }

TUnit.Engine/Reporters/Html/HtmlReporter.cs

@@ -335,6 +335,15 @@ private ReportData BuildReportData()
         if (_activityCollector != null)
         {
             spans = _activityCollector.GetAllSpans();
+
+            // Use the session span duration as the header duration when available,
+            // since it captures the full wall-clock time including initialization.
+            // The test-timing-based duration only covers test execution.
+            var sessionSpan = spans?.FirstOrDefault(s => s.SpanType == TUnitActivitySource.SpanTestSession);
+            if (sessionSpan != null)
+            {
+                totalDurationMs = sessionSpan.DurationMs;
+            }
         }
 #endif
 

TUnit.Engine/Services/HookExecutor.cs

@@ -69,7 +69,7 @@ public async ValueTask ExecuteBeforeTestSessionHooksAsync(CancellationToken canc
         if (TUnitActivitySource.Source.HasListeners())
         {
             sessionContext.Activity = TUnitActivitySource.StartActivity(
-                "test session",
+                TUnitActivitySource.SpanTestSession,
                 System.Diagnostics.ActivityKind.Internal,
                 default,
                 [
@@ -153,7 +153,7 @@ public async ValueTask ExecuteBeforeAssemblyHooksAsync(Assembly assembly, Cancel
         {
             var sessionActivity = _contextProvider.TestSessionContext.Activity;
             assemblyContext.Activity = TUnitActivitySource.StartActivity(
-                "test assembly",
+                TUnitActivitySource.SpanTestAssembly,
                 System.Diagnostics.ActivityKind.Internal,
                 sessionActivity?.Context ?? default,
                 [
@@ -311,7 +311,7 @@ public async ValueTask ExecuteBeforeClassHooksAsync(
         {
             var assemblyActivity = classContext.AssemblyContext.Activity;
             classContext.Activity = TUnitActivitySource.StartActivity(
-                "test suite",
+                TUnitActivitySource.SpanTestSuite,
                 System.Diagnostics.ActivityKind.Internal,
                 assemblyActivity?.Context ?? default,
                 [