@

feat(aspire): tear down Aspire on test-run abort via session token

AspireFixture startup (CreateAsync/BuildAsync/StartAsync and the
resource-wait) previously only observed its own ResourceTimeout, so a
run abort (Ctrl+C / IDE stop / ProcessExit) could neither interrupt a
stuck startup nor stop the application before the process was forcefully
killed, leaking containers.

Expose the engine-wide abort token on TestSessionContext (populated once
in TUnitTestFramework.ExecuteRequestAsync, covering both reflection and
source-generated modes) so session-scoped fixtures can observe run
cancellation. AspireFixture links it into all startup/wait operations
via a virtual RunCancellationToken and registers a single-shot teardown
that stops and disposes the application as soon as the run is aborted;
DisposeAsync awaits the same task so teardown runs exactly once.

The token lives on TestSessionContext (not a per-test context) because a
session- or class-scoped fixture outlives any single test; a per-test
token would tear the shared application down when its first consuming
test ends. RunCancellationToken is virtual for the rare per-test fixture.

Abort is distinguished from a genuine resource timeout so it surfaces as
cancellation rather than a misleading TimeoutException.
@

Author: thomhurst

TUnit.Aspire.Core/AspireFixture.cs

@@ -40,6 +40,29 @@ public class AspireFixture<TAppHost> : IAsyncInitializer, IAsyncDisposable
     private readonly object _timelineGate = new();
     private Stopwatch? _timelineClock;
 
+    // Single-shot teardown so the run-abort callback and the normal DisposeAsync path
+    // converge on the same StopAsync/DisposeAsync work instead of racing each other.
+    private readonly object _teardownGate = new();
+    private Task? _teardownTask;
+    private CancellationTokenRegistration _abortRegistration;
+
+    /// <summary>
+    /// The run-abort token whose lifetime governs this fixture. Defaults to the test session's
+    /// cancellation token (Ctrl+C, IDE stop, process exit), which matches the lifetime of a
+    /// session- or class-scoped fixture. It is linked into the startup and resource-wait
+    /// operations so an abort interrupts them promptly instead of blocking for the full
+    /// <see cref="ResourceTimeout"/>, and triggers teardown of the Aspire application.
+    /// Override-provided <see cref="WaitForResourcesAsync"/> implementations should honor it too.
+    /// </summary>
+    /// <remarks>
+    /// Override this only if the fixture is genuinely per-test (<c>Shared = SharedType.None</c>)
+    /// and you want a per-test token folded in. Do NOT return a per-test token from a shared
+    /// fixture: it is cancelled when the first consuming test ends, which would tear the shared
+    /// application down underneath every later test.
+    /// </remarks>
+    protected virtual CancellationToken RunCancellationToken =>
+        TestSessionContext.Current?.CancellationToken ?? CancellationToken.None;
+
     /// <summary>
     /// The running Aspire distributed application.
     /// </summary>
@@ -198,7 +221,8 @@ protected virtual void ConfigureBuilder(IDistributedApplicationTestingBuilder bu
     /// Override for full control over the resource waiting logic.
     /// </summary>
     /// <param name="app">The running distributed application.</param>
-    /// <param name="cancellationToken">A cancellation token that will be cancelled after <see cref="ResourceTimeout"/>.</param>
+    /// <param name="cancellationToken">A cancellation token that is cancelled after <see cref="ResourceTimeout"/>
+    /// or when the test run is aborted (see <see cref="RunCancellationToken"/>).</param>
     protected virtual async Task WaitForResourcesAsync(DistributedApplication app, CancellationToken cancellationToken)
     {
         var notificationService = app.Services.GetRequiredService<ResourceNotificationService>();
@@ -259,7 +283,7 @@ public virtual async Task InitializeAsync()
         }
 
         LogProgress($"Creating distributed application builder for {typeof(TAppHost).Name}...");
-        var builder = await DistributedApplicationTestingBuilder.CreateAsync<TAppHost>(Args, ConfigureAppHost);
+        var builder = await DistributedApplicationTestingBuilder.CreateAsync<TAppHost>(Args, ConfigureAppHost, RunCancellationToken);
         ConfigureBuilder(builder);
         RemoveResources(builder);
 
@@ -272,9 +296,14 @@ public virtual async Task InitializeAsync()
         LogProgress($"Builder created in {sw.Elapsed.TotalSeconds:0.0}s");
 
         LogProgress("Building application...");
-        _app = await builder.BuildAsync();
+        _app = await builder.BuildAsync(RunCancellationToken);
         LogProgress($"Application built in {sw.Elapsed.TotalSeconds:0.0}s");
 
+        // Now that the app exists, hook the run-abort token so a Ctrl+C / IDE stop tears the
+        // application down immediately, rather than leaking containers while the rest of the
+        // session unwinds (or the process is forcefully killed on the abort timeout).
+        RegisterAbortTeardown();
+
         var model = _app.Services.GetRequiredService<DistributedApplicationModel>();
         var resourceList = string.Join(", ", model.Resources.Select(r => r.Name));
         LogProgress($"Starting application with resources: [{resourceList}]");
@@ -288,32 +317,45 @@ public virtual async Task InitializeAsync()
         var monitorTask = MonitorResourceEventsAsync(_app, monitorCts.Token);
         var notificationService = _app.Services.GetRequiredService<ResourceNotificationService>();
 
+        // Linked to the run-abort token so an abort interrupts startup promptly; the timeout
+        // is layered on top via CancelAfter.
+        using var startCts = CancellationTokenSource.CreateLinkedTokenSource(RunCancellationToken);
+        startCts.CancelAfter(ResourceTimeout);
         try
         {
-            using (var startCts = new CancellationTokenSource(ResourceTimeout))
+            try
             {
-                try
-                {
-                    await _app.StartAsync(startCts.Token);
-                }
-                catch (OperationCanceledException) when (startCts.IsCancellationRequested)
-                {
-                    var headline = $"Timed out after {ResourceTimeout.TotalSeconds:0}s waiting for the Aspire application to start.";
-                    throw new TimeoutException(
-                        await BuildDiagnosticsAndAttachAsync(_app, notificationService, headline,
-                            model.Resources.Select(r => r.Name).ToList()));
-                }
+                await _app.StartAsync(startCts.Token);
+            }
+            catch (OperationCanceledException) when (RunCancellationToken.IsCancellationRequested)
+            {
+                // Run aborted — propagate cancellation; DisposeAsync (and the abort callback) tear down.
+                throw;
+            }
+            catch (OperationCanceledException) when (startCts.IsCancellationRequested)
+            {
+                var headline = $"Timed out after {ResourceTimeout.TotalSeconds:0}s waiting for the Aspire application to start.";
+                throw new TimeoutException(
+                    await BuildDiagnosticsAndAttachAsync(_app, notificationService, headline,
+                        model.Resources.Select(r => r.Name).ToList()));
             }
 
             LogProgress($"Application started in {sw.Elapsed.TotalSeconds:0.0}s. Waiting for resources (timeout: {ResourceTimeout.TotalSeconds:0}s, behavior: {WaitBehavior})...");
 
-            using (var cts = new CancellationTokenSource(ResourceTimeout))
+            using (var cts = CancellationTokenSource.CreateLinkedTokenSource(RunCancellationToken))
             {
+                cts.CancelAfter(ResourceTimeout);
+
                 try
                 {
                     await WaitForResourcesAsync(_app, cts.Token);
                     LogProgress("All resources ready.");
                 }
+                catch (OperationCanceledException) when (RunCancellationToken.IsCancellationRequested)
+                {
+                    // Run aborted — propagate cancellation; teardown is handled by DisposeAsync / abort callback.
+                    throw;
+                }
                 catch (OperationCanceledException) when (cts.IsCancellationRequested)
                 {
                     // Fallback for custom WaitForResourcesAsync overrides that don't use the default
@@ -361,6 +403,44 @@ private void RemoveResources(IDistributedApplicationTestingBuilder builder)
     /// </code>
     /// </summary>
     public virtual async ValueTask DisposeAsync()
+    {
+        _abortRegistration.Dispose();
+        await StopAndDisposeAsync();
+        GC.SuppressFinalize(this);
+    }
+
+    /// <summary>
+    /// Registers the run-abort token so an aborted test run begins tearing down the Aspire
+    /// application immediately, in parallel with the rest of session shutdown. The callback and
+    /// the normal <see cref="DisposeAsync"/> path share a single teardown task, so the work runs
+    /// exactly once regardless of which fires first.
+    /// </summary>
+    private void RegisterAbortTeardown()
+    {
+        if (!RunCancellationToken.CanBeCanceled)
+        {
+            return;
+        }
+
+        _abortRegistration = RunCancellationToken.Register(static state =>
+        {
+            var fixture = (AspireFixture<TAppHost>) state!;
+            fixture.LogProgress("Test run aborted — tearing down Aspire application...");
+            // Fire-and-forget: don't block the thread raising cancellation. DisposeAsync awaits
+            // the same task, so completion is still observed during session shutdown.
+            _ = fixture.StopAndDisposeAsync();
+        }, this);
+    }
+
+    private Task StopAndDisposeAsync()
+    {
+        lock (_teardownGate)
+        {
+            return _teardownTask ??= StopAndDisposeCoreAsync();
+        }
+    }
+
+    private async Task StopAndDisposeCoreAsync()
     {
         if (_otlpReceiver is not null && _app is not null)
         {
@@ -387,8 +467,6 @@ public virtual async ValueTask DisposeAsync()
             await _otlpReceiver.DisposeAsync();
             _otlpReceiver = null;
         }
-
-        GC.SuppressFinalize(this);
     }
 
     // --- OTLP Telemetry ---
@@ -719,6 +797,13 @@ await BuildDiagnosticsAndAttachAsync(
         }
         catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
         {
+            // A run-abort cancels the linked token too — surface it as cancellation, not a
+            // misleading resource timeout, so the engine sees the abort and teardown proceeds.
+            if (RunCancellationToken.IsCancellationRequested)
+            {
+                throw;
+            }
+
             // Timeout - diagnose each pending resource (state, exit code, health, dependencies)
             // and attach the full timeline + untruncated logs as an artifact.
             failureCts.Cancel();

TUnit.Core/Models/TestSessionContext.cs

@@ -59,6 +59,20 @@ internal TestSessionContext(TestDiscoveryContext beforeTestDiscoveryContext) : b
 
     public required string? TestFilter { get; init; }
 
+    /// <summary>
+    /// The engine-wide cancellation token for this test session. Signalled when the run is
+    /// aborted (e.g. Ctrl+C, IDE stop, or process exit). Session-scoped fixtures
+    /// (<see cref="Interfaces.IAsyncInitializer"/> implementations such as long-running
+    /// containers or distributed applications) can observe this to abort startup and tear
+    /// themselves down promptly on an abort request.
+    /// </summary>
+    /// <remarks>
+    /// Defaults to <see cref="System.Threading.CancellationToken.None"/> until the engine
+    /// populates it at the start of execution. Per-test cancellation flows through
+    /// <see cref="TestContext.CancellationToken"/> instead; this token spans the whole session.
+    /// </remarks>
+    public CancellationToken CancellationToken { get; internal set; }
+
     private readonly Lock _lock = new();
     private readonly List<AssemblyHookContext> _assemblies = [];
     private ClassHookContext[]? _cachedTestClasses;

TUnit.Engine/Framework/TUnitTestFramework.cs

@@ -59,6 +59,10 @@ public async Task ExecuteRequestAsync(ExecuteRequestContext context)
             GlobalContext.Current.GlobalLogger = serviceProvider.Logger;
             BeforeTestDiscoveryContext.Current = serviceProvider.ContextProvider.BeforeTestDiscoveryContext;
             TestDiscoveryContext.Current = serviceProvider.ContextProvider.TestDiscoveryContext;
+            // Expose the engine-wide abort token on the session context so session-scoped
+            // fixtures (containers, Aspire apps, etc.) can observe run cancellation and tear
+            // themselves down.
+            serviceProvider.ContextProvider.TestSessionContext.CancellationToken = serviceProvider.CancellationToken.Token;
             TestSessionContext.Current = serviceProvider.ContextProvider.TestSessionContext;
 
             serviceProvider.Initializer.Initialize();

TUnit.PublicAPI/Tests.Core_Library_Has_No_API_Changes.DotNet10_0.verified.txt

@@ -1721,6 +1721,7 @@ namespace
     {
         public .<.TestContext> AllTests { get; }
         public .<.AssemblyHookContext> Assemblies { get; }
+        public .CancellationToken CancellationToken { get; }
         public required string Id { get; init; }
         public .<.ClassHookContext> TestClasses { get; }
         public .TestDiscoveryContext TestDiscoveryContext { get; }

TUnit.PublicAPI/Tests.Core_Library_Has_No_API_Changes.DotNet8_0.verified.txt

@@ -1721,6 +1721,7 @@ namespace
     {
         public .<.TestContext> AllTests { get; }
         public .<.AssemblyHookContext> Assemblies { get; }
+        public .CancellationToken CancellationToken { get; }
         public required string Id { get; init; }
         public .<.ClassHookContext> TestClasses { get; }
         public .TestDiscoveryContext TestDiscoveryContext { get; }

TUnit.PublicAPI/Tests.Core_Library_Has_No_API_Changes.DotNet9_0.verified.txt

@@ -1721,6 +1721,7 @@ namespace
     {
         public .<.TestContext> AllTests { get; }
         public .<.AssemblyHookContext> Assemblies { get; }
+        public .CancellationToken CancellationToken { get; }
         public required string Id { get; init; }
         public .<.ClassHookContext> TestClasses { get; }
         public .TestDiscoveryContext TestDiscoveryContext { get; }

TUnit.PublicAPI/Tests.Core_Library_Has_No_API_Changes.Net4_7.verified.txt

@@ -1660,6 +1660,7 @@ namespace
     {
         public .<.TestContext> AllTests { get; }
         public .<.AssemblyHookContext> Assemblies { get; }
+        public .CancellationToken CancellationToken { get; }
         public required string Id { get; init; }
         public .<.ClassHookContext> TestClasses { get; }
         public .TestDiscoveryContext TestDiscoveryContext { get; }