fix(app-start): Fixes cold/warm start spans not attaching if TTFD takes more than 3 seconds to report (#3404)

* fix(native_app_start): ensure app start spans are attached before TTFD tracking completes

This update modifies the NativeAppStartHandler to attach app start spans prior to the completion of time-to-full-display (TTFD) tracking. A regression test has been added to verify that app start spans are present when TTFD tracking is enabled, addressing a previous issue where spans could be missing if reportFullyDisplayed() was called after autoFinishAfter.

* refactor(native_app_start): improve test isolation and clarity for app start spans

This commit enhances the test for app start spans by ensuring they are attached before time-to-full-display (TTFD) tracking starts. A new spy wrapper is introduced to capture transaction state during tracking, improving test reliability and clarity. The test now verifies that the 'Cold Start' span is present when track() is called, addressing potential race conditions in span attachment.

* Update CHANGELOG

* Update CHANGELOG

Author: buenaflor

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### Fixes
+
+- Cold/warm start spans not attaching if TTFD takes more than 3 seconds to report ([#3404](https://github.com/getsentry/sentry-dart/pull/3404))
+
 ## 9.9.0
 
 ### Features

packages/flutter/lib/src/integrations/native_app_start_handler.dart

@@ -64,11 +64,11 @@ class NativeAppStartHandler {
     SentryMeasurement? measurement = appStartInfo.toMeasurement();
     sentryTracer.measurements[measurement.name] = appStartInfo.toMeasurement();
 
+    await _attachAppStartSpans(appStartInfo, sentryTracer);
     await options.timeToDisplayTracker.track(
       rootScreenTransaction,
       ttidEndTimestamp: appStartInfo.end,
     );
-    await _attachAppStartSpans(appStartInfo, sentryTracer);
   }
 
   _AppStartInfo? _infoNativeAppStart(

packages/flutter/test/integrations/native_app_start_handler_test.dart

@@ -10,6 +10,7 @@ import 'package:sentry_flutter/src/integrations/native_app_start_handler.dart';
 import 'package:sentry_flutter/src/integrations/native_app_start_integration.dart';
 import 'package:sentry/src/sentry_tracer.dart';
 import 'package:sentry_flutter/src/native/native_app_start.dart';
+import 'package:sentry_flutter/src/navigation/time_to_display_tracker.dart';
 
 import '../mocks.dart';
 import '../mocks.mocks.dart';
@@ -222,6 +223,51 @@ void main() {
       // skip this test for now as it's extremely flaky
     }, skip: true);
 
+    // Regression test: App start spans must be attached to the transaction
+    // BEFORE track() is called. This verifies the fix for a race condition
+    // where calling reportFullyDisplayed() after autoFinishAfter could cause
+    // app start spans to be missing from the captured transaction.
+    test('app start spans are attached before TTFD tracking starts', () async {
+      // Create fresh fixture and mocks for test isolation
+      final testFixture = Fixture();
+      setupMocks(testFixture);
+
+      testFixture.options.enableTimeToFullDisplayTracing = true;
+
+      // Set sentrySetupStartTime to a value consistent with the mock timestamps
+      // (pluginRegistrationTime is 10ms, so this should be after that)
+      SentryFlutter.sentrySetupStartTime =
+          DateTime.fromMillisecondsSinceEpoch(15);
+
+      // Capture transaction state at the moment track() is called
+      List<SentrySpan>? spansWhenTrackCalled;
+      final originalTracker = testFixture.options.timeToDisplayTracker;
+      testFixture.options.timeToDisplayTracker = _FakeTimeToDisplayTracker(
+        originalTracker,
+        onTrack: (transaction) {
+          if (transaction is SentryTracer) {
+            spansWhenTrackCalled = List.from(transaction.children);
+          }
+        },
+      );
+
+      final future = testFixture.call(
+        appStartEnd: DateTime.fromMillisecondsSinceEpoch(50),
+      );
+
+      await Future.delayed(Duration(milliseconds: 50));
+      await testFixture.options.timeToDisplayTracker.reportFullyDisplayed();
+      await future;
+
+      expect(spansWhenTrackCalled, isNotNull,
+          reason: 'track() should have been called');
+      expect(
+        spansWhenTrackCalled!.any((s) => s.context.description == 'Cold Start'),
+        isTrue,
+        reason: 'Cold Start span must be attached before track() is called',
+      );
+    });
+
     test('no transaction if app start takes more than 60s', () async {
       await fixture.call(
         appStartEnd: DateTime.fromMillisecondsSinceEpoch(60001),
@@ -536,3 +582,30 @@ class MockScope extends Mock implements Scope {
     _span = value;
   }
 }
+
+/// Spy wrapper that intercepts track() calls to capture transaction state
+class _FakeTimeToDisplayTracker extends TimeToDisplayTracker {
+  final TimeToDisplayTracker _delegate;
+  final void Function(ISentrySpan transaction) onTrack;
+
+  _FakeTimeToDisplayTracker(this._delegate, {required this.onTrack})
+      : super(options: _delegate.options);
+
+  @override
+  SpanId? get transactionId => _delegate.transactionId;
+
+  @override
+  set transactionId(SpanId? value) => _delegate.transactionId = value;
+
+  @override
+  Future<void> track(ISentrySpan transaction,
+      {DateTime? ttidEndTimestamp}) async {
+    onTrack(transaction);
+    return _delegate.track(transaction, ttidEndTimestamp: ttidEndTimestamp);
+  }
+
+  @override
+  Future<void> reportFullyDisplayed({SpanId? spanId, DateTime? endTimestamp}) =>
+      _delegate.reportFullyDisplayed(
+          spanId: spanId, endTimestamp: endTimestamp);
+}