feat: integrate TestTerminalContext with Terminal.Instance

- TestTerminalContext.Current setter now syncs with Terminal.Instance
- Saves previous Terminal.Instance and restores on clear
- TestTerminal.Dispose clears context if it's the current terminal
- Added Terminal property for direct access to current test terminal
- Added integration tests

Closes #11

Author: StevenTCramer

source/timewarp-terminal/test-terminal-context.cs

@@ -2,7 +2,7 @@ namespace TimeWarp.Terminal;
 
 /// <summary>
 /// Provides an ambient context for <see cref="TestTerminal"/> that enables zero-configuration testing
-/// of CLI applications.
+/// of CLI applications with automatic <see cref="TimeWarp.Terminal.Terminal.Instance"/> synchronization.
 /// </summary>
 /// <remarks>
 /// <para>
@@ -11,38 +11,58 @@ namespace TimeWarp.Terminal;
 /// running tests in parallel.
 /// </para>
 /// <para>
+/// When <see cref="Current"/> is set, it automatically updates <see cref="TimeWarp.Terminal.Terminal.Instance"/>
+/// and restores the previous instance when cleared.
+/// </para>
+/// <para>
 /// Resolution order when determining which terminal to use:
 /// <list type="number">
 ///   <item><description><see cref="Current"/> (if set)</description></item>
 ///   <item><description><c>ITerminal</c> from DI (if registered)</description></item>
 ///   <item><description><see cref="TimeWarpTerminal.Default"/> (fallback)</description></item>
 /// </list>
 /// </para>
+/// </remarks>
 /// <example>
+/// Simple test pattern with automatic TimeWarp.Terminal.Terminal.Instance synchronization:
 /// <code>
 /// public static async Task Should_display_greeting()
 /// {
 ///     using TestTerminal terminal = new();
 ///     TestTerminalContext.Current = terminal;
 ///     
+///     // TimeWarp.Terminal.Terminal.Instance is now set to terminal
+///     Terminal.WriteLine("Hello");  // Routes to test terminal
+///     
 ///     await Program.Main(["greet", "World"]);
 ///     
 ///     terminal.OutputContains("Hello, World!").ShouldBeTrue();
+///     
+///     // On dispose, TestTerminal clears context and restores previous TimeWarp.Terminal.Terminal.Instance
 /// }
 /// </code>
 /// </example>
-/// </remarks>
 public static class TestTerminalContext
 {
   private static readonly AsyncLocal<TestTerminal?> Context = new();
+  private static readonly AsyncLocal<ITerminal?> PreviousInstance = new();
 
   /// <summary>
   /// Gets or sets the current <see cref="TestTerminal"/> for the async execution context.
   /// </summary>
   /// <remarks>
   /// <para>
-  /// Setting this property to a non-null value causes all terminal resolution
-  /// to use the provided <see cref="TestTerminal"/> instead of the real terminal.
+  /// Setting this property to a non-null value causes:
+  /// <list type="bullet">
+  ///   <item><description>The current <see cref="TimeWarp.Terminal.Terminal.Instance"/> to be saved</description></item>
+  ///   <item><description><see cref="TimeWarp.Terminal.Terminal.Instance"/> to be set to the provided terminal</description></item>
+  /// </list>
+  /// </para>
+  /// <para>
+  /// Setting this property to <c>null</c> causes:
+  /// <list type="bullet">
+  ///   <item><description><see cref="TimeWarp.Terminal.Terminal.Instance"/> to be restored to its previous value</description></item>
+  /// </list>
   /// </para>
   /// <para>
   /// The value is scoped to the current async execution context, so parallel tests
@@ -55,14 +75,41 @@ public static class TestTerminalContext
   public static TestTerminal? Current
   {
     get => Context.Value;
-    set => Context.Value = value;
+    set
+    {
+      if (value is not null)
+      {
+        // Save current TimeWarp.Terminal.Terminal.Instance before replacing
+        PreviousInstance.Value = TimeWarp.Terminal.Terminal.Instance;
+        Context.Value = value;
+        TimeWarp.Terminal.Terminal.Instance = value;
+      }
+      else if (Context.Value is not null)
+      {
+        // Restore previous TimeWarp.Terminal.Terminal.Instance
+        Context.Value = null;
+        if (PreviousInstance.Value is not null)
+        {
+          TimeWarp.Terminal.Terminal.Instance = PreviousInstance.Value;
+          PreviousInstance.Value = null;
+        }
+      }
+    }
   }
 
   /// <summary>
   /// Gets a value indicating whether a <see cref="TestTerminal"/> is set for the current context.
   /// </summary>
   public static bool HasValue => Context.Value is not null;
 
+  /// <summary>
+  /// Gets the <see cref="TestTerminal"/> for the current context, or throws if not set.
+  /// </summary>
+  /// <returns>The current <see cref="TestTerminal"/>.</returns>
+  /// <exception cref="InvalidOperationException">Thrown when no test terminal is set.</exception>
+  public static TestTerminal Terminal
+    => Context.Value ?? throw new InvalidOperationException("No TestTerminal set in current context. Set TestTerminalContext.Current first.");
+
   /// <summary>
   /// Resolves a terminal using the standard resolution order:
   /// TestTerminalContext.Current → provided terminal → fallback.

source/timewarp-terminal/test-terminal.cs

@@ -332,11 +332,20 @@ public string[] GetOutputLines()
   /// <summary>
   /// Disposes the resources used by this instance.
   /// </summary>
+  /// <summary>
+  /// Disposes the resources used by this instance and clears the test context if this is the current terminal.
+  /// </summary>
   public void Dispose()
   {
     if (Disposed)
       return;
 
+    // Clear context if this is the current terminal (restores previous Terminal.Instance)
+    if (TestTerminalContext.Current == this)
+    {
+      TestTerminalContext.Current = null;
+    }
+
     InputReader.Dispose();
     OutputWriter.Dispose();
     ErrorWriter.Dispose();

tests/test-terminal-context-01-integration.cs

@@ -0,0 +1,123 @@
+#!/usr/bin/dotnet --
+#:project $(SourceDirectory)timewarp-terminal/timewarp-terminal.csproj
+
+// Tests for TestTerminalContext integration with Terminal.Instance
+#pragma warning disable CA1849
+
+#if !JARIBU_MULTI
+return await RunAllTests();
+#endif
+
+namespace TimeWarp.Terminal.Tests.Core.TestTerminalContextIntegration
+{
+
+[TestTag("TestTerminalContext")]
+public class TestTerminalContextIntegrationTests
+{
+  [ModuleInitializer]
+  internal static void Register() => RegisterTests<TestTerminalContextIntegrationTests>();
+
+  public static async Task Should_set_terminal_instance_when_context_set()
+  {
+    // Arrange
+    ITerminal original = TimeWarp.Terminal.Terminal.Instance;
+    using TestTerminal testTerminal = new();
+
+    // Act
+    TestTerminalContext.Current = testTerminal;
+
+    // Assert
+    TimeWarp.Terminal.Terminal.Instance.ShouldBe(testTerminal);
+
+    // Cleanup
+    TestTerminalContext.Current = null;
+    TimeWarp.Terminal.Terminal.Instance = original;
+
+    await Task.CompletedTask;
+  }
+
+  public static async Task Should_restore_terminal_instance_when_context_cleared()
+  {
+    // Arrange
+    ITerminal original = TimeWarp.Terminal.Terminal.Instance;
+    using TestTerminal testTerminal = new();
+    TestTerminalContext.Current = testTerminal;
+
+    // Act
+    TestTerminalContext.Current = null;
+
+    // Assert
+    TimeWarp.Terminal.Terminal.Instance.ShouldBe(original);
+
+    await Task.CompletedTask;
+  }
+
+  public static async Task Should_restore_terminal_instance_on_dispose()
+  {
+    // Arrange
+    ITerminal original = TimeWarp.Terminal.Terminal.Instance;
+
+    // Act
+    using (TestTerminal testTerminal = new())
+    {
+      TestTerminalContext.Current = testTerminal;
+      TimeWarp.Terminal.Terminal.Instance.ShouldBe(testTerminal);
+    }
+
+    // Assert - Terminal.Instance should be restored after dispose
+    TimeWarp.Terminal.Terminal.Instance.ShouldBe(original);
+
+    await Task.CompletedTask;
+  }
+
+  public static async Task Should_route_static_terminal_calls_to_test_terminal()
+  {
+    // Arrange
+    ITerminal original = TimeWarp.Terminal.Terminal.Instance;
+    using TestTerminal testTerminal = new();
+    TestTerminalContext.Current = testTerminal;
+
+    // Act
+    TimeWarp.Terminal.Terminal.WriteLine("Hello from static API");
+
+    // Assert
+    testTerminal.OutputContains("Hello from static API").ShouldBeTrue();
+
+    // Cleanup
+    TestTerminalContext.Current = null;
+    TimeWarp.Terminal.Terminal.Instance = original;
+
+    await Task.CompletedTask;
+  }
+
+  public static async Task Should_provide_terminal_property()
+  {
+    // Arrange
+    using TestTerminal testTerminal = new();
+    TestTerminalContext.Current = testTerminal;
+
+    // Act
+    TestTerminal retrieved = TestTerminalContext.Terminal;
+
+    // Assert
+    retrieved.ShouldBe(testTerminal);
+
+    // Cleanup
+    TestTerminalContext.Current = null;
+
+    await Task.CompletedTask;
+  }
+
+  public static async Task Should_throw_when_terminal_accessed_without_context()
+  {
+    // Arrange - ensure no context
+    TestTerminalContext.Current = null;
+
+    // Act & Assert
+    Should.Throw<InvalidOperationException>(() => _ = TestTerminalContext.Terminal);
+
+    await Task.CompletedTask;
+  }
+}
+
+}