test: add FormInputStateManager and AnnouncementService tests (+19 tests)

perditavojo · Copilot · perditavojo · commit 3d4d19b39206 · 2026-04-10T14:15:02.000+08:00
- FormInputStateManagerTests: 15 tests for TryBegin*/End* Interlocked state flags
- AnnouncementServiceTests: 4 tests for Enqueue guard logic and Dispose idempotency

Total: 150 -&gt; 169 tests

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/tests/InputBox.Tests/AnnouncementServiceTests.cs b/tests/InputBox.Tests/AnnouncementServiceTests.cs
@@ -0,0 +1,109 @@
+using InputBox.Core.Services;
+using Xunit;
+
+namespace InputBox.Tests;
+
+/// <summary>
+/// AnnouncementService 的入隊守衛邏輯與生命週期行為測試
+/// <para>驗證空字串過濾、Dispose 後不再處理，以及有效訊息最終被播報的基本合約。</para>
+/// </summary>
+public class AnnouncementServiceTests : IDisposable
+{
+    private AnnouncementService? _svc;
+
+    /// <summary>
+    /// 在每個測試後確保服務被正確釋放。
+    /// </summary>
+    public void Dispose()
+    {
+        _svc?.Dispose();
+        _svc = null;
+    }
+
+    // ── Enqueue 守衛邏輯 ────────────────────────────────────────────────────
+
+    /// <summary>
+    /// Enqueue 空字串時，委派不應被呼叫（守衛提前返回）。
+    /// </summary>
+    [Fact]
+    public async Task Enqueue_EmptyString_DoesNotInvokeDelegate()
+    {
+        bool invoked = false;
+
+        _svc = new AnnouncementService(async (msg, interrupt, ct) =>
+        {
+            invoked = true;
+            await Task.CompletedTask;
+        });
+
+        _svc.Enqueue(string.Empty);
+
+        // 等待足夠時間讓背景工作有機會執行
+        await Task.Delay(600);
+
+        Assert.False(invoked);
+    }
+
+    /// <summary>
+    /// Dispose 後 Enqueue 有效訊息，委派不應被呼叫（已設置 disposeSignaled）。
+    /// </summary>
+    [Fact]
+    public async Task Enqueue_AfterDispose_DoesNotInvokeDelegate()
+    {
+        bool invoked = false;
+
+        _svc = new AnnouncementService(async (msg, interrupt, ct) =>
+        {
+            invoked = true;
+            await Task.CompletedTask;
+        });
+
+        _svc.Dispose();
+        _svc.Enqueue("hello after dispose");
+
+        await Task.Delay(600);
+
+        Assert.False(invoked);
+    }
+
+    /// <summary>
+    /// 有效訊息應在背景延遲後被委派接收並播報。
+    /// </summary>
+    [Fact]
+    public async Task Enqueue_ValidMessage_EventuallyInvokesDelegate()
+    {
+        var tcs = new TaskCompletionSource<string>(TaskCreationOptions.RunContinuationsAsynchronously);
+
+        _svc = new AnnouncementService(async (msg, interrupt, ct) =>
+        {
+            tcs.TrySetResult(msg);
+            await Task.CompletedTask;
+        });
+
+        _svc.Enqueue("測試廣播");
+
+        // 等待最多 2 秒讓背景工作完成（含 ducking 延遲與 jitter）
+        string? received = await Task.WhenAny(tcs.Task, Task.Delay(2000)) == tcs.Task
+            ? tcs.Task.Result
+            : null;
+
+        Assert.Equal("測試廣播", received);
+    }
+
+    /// <summary>
+    /// Dispose 應可安全呼叫多次而不拋出例外（冪等保護）。
+    /// </summary>
+    [Fact]
+    public void Dispose_CalledMultipleTimes_DoesNotThrow()
+    {
+        _svc = new AnnouncementService(async (_, _, _) => await Task.CompletedTask);
+
+        var ex = Record.Exception(() =>
+        {
+            _svc.Dispose();
+            _svc.Dispose();
+        });
+
+        Assert.Null(ex);
+    }
+}
diff --git a/tests/InputBox.Tests/FormInputStateManagerTests.cs b/tests/InputBox.Tests/FormInputStateManagerTests.cs
@@ -0,0 +1,199 @@
+using InputBox.Core.Input;
+using Xunit;
+
+namespace InputBox.Tests;
+
+/// <summary>
+/// FormInputStateManager 的 Interlocked 狀態旗標管理邏輯測試
+/// <para>驗證所有「嘗試進入 / 結束」的互斥保護行為，確保並行狀態機正確防止重入。</para>
+/// </summary>
+public class FormInputStateManagerTests
+{
+    // ── TryBeginReturning / EndReturning ───────────────────────────────────
+
+    /// <summary>
+    /// 初始狀態下 TryBeginReturning 應成功（回傳 true）。
+    /// </summary>
+    [Fact]
+    public void TryBeginReturning_WhenIdle_ReturnsTrue()
+    {
+        var mgr = new FormInputStateManager();
+        Assert.True(mgr.TryBeginReturning());
+    }
+
+    /// <summary>
+    /// 已進入流程時，再次 TryBeginReturning 應失敗（回傳 false），防止重入。
+    /// </summary>
+    [Fact]
+    public void TryBeginReturning_WhenAlreadyReturning_ReturnsFalse()
+    {
+        var mgr = new FormInputStateManager();
+        mgr.TryBeginReturning();
+        Assert.False(mgr.TryBeginReturning());
+    }
+
+    /// <summary>
+    /// EndReturning 後，TryBeginReturning 應再次成功。
+    /// </summary>
+    [Fact]
+    public void EndReturning_ReleasesLock_AllowsNextTryBegin()
+    {
+        var mgr = new FormInputStateManager();
+        mgr.TryBeginReturning();
+        mgr.EndReturning();
+        Assert.True(mgr.TryBeginReturning());
+    }
+
+    // ── TryBeginTouchKeyboard / EndTouchKeyboard ───────────────────────────
+
+    /// <summary>
+    /// 初始狀態下 TryBeginTouchKeyboard 應成功。
+    /// </summary>
+    [Fact]
+    public void TryBeginTouchKeyboard_WhenIdle_ReturnsTrue()
+    {
+        var mgr = new FormInputStateManager();
+        Assert.True(mgr.TryBeginTouchKeyboard());
+    }
+
+    /// <summary>
+    /// 已進入流程時，再次嘗試應失敗。
+    /// </summary>
+    [Fact]
+    public void TryBeginTouchKeyboard_WhenBusy_ReturnsFalse()
+    {
+        var mgr = new FormInputStateManager();
+        mgr.TryBeginTouchKeyboard();
+        Assert.False(mgr.TryBeginTouchKeyboard());
+    }
+
+    /// <summary>
+    /// EndTouchKeyboard 後 IsShowingTouchKeyboard 屬性應為 false。
+    /// </summary>
+    [Fact]
+    public void EndTouchKeyboard_ResetsIsShowingTouchKeyboard()
+    {
+        var mgr = new FormInputStateManager();
+        mgr.TryBeginTouchKeyboard();
+        mgr.EndTouchKeyboard();
+        Assert.False(mgr.IsShowingTouchKeyboard);
+    }
+
+    /// <summary>
+    /// TryBeginTouchKeyboard 成功後，IsShowingTouchKeyboard 應為 true。
+    /// </summary>
+    [Fact]
+    public void IsShowingTouchKeyboard_AfterTryBegin_IsTrue()
+    {
+        var mgr = new FormInputStateManager();
+        mgr.TryBeginTouchKeyboard();
+        Assert.True(mgr.IsShowingTouchKeyboard);
+    }
+
+    // ── TryBeginFlashing / EndFlashing ─────────────────────────────────────
+
+    /// <summary>
+    /// 閃爍流程的互斥保護：進入後再次嘗試應失敗。
+    /// </summary>
+    [Fact]
+    public void TryBeginFlashing_WhenBusy_ReturnsFalse()
+    {
+        var mgr = new FormInputStateManager();
+        mgr.TryBeginFlashing();
+        Assert.False(mgr.TryBeginFlashing());
+    }
+
+    /// <summary>
+    /// EndFlashing 後應允許再次進入閃爍流程。
+    /// </summary>
+    [Fact]
+    public void EndFlashing_AllowsNextTryBeginFlashing()
+    {
+        var mgr = new FormInputStateManager();
+        mgr.TryBeginFlashing();
+        mgr.EndFlashing();
+        Assert.True(mgr.TryBeginFlashing());
+    }
+
+    // ── TryBeginProcessingActivated / EndProcessingActivated ───────────────
+
+    /// <summary>
+    /// Activated 事件處理流程的互斥保護：進入後再次嘗試應失敗。
+    /// </summary>
+    [Fact]
+    public void TryBeginProcessingActivated_WhenBusy_ReturnsFalse()
+    {
+        var mgr = new FormInputStateManager();
+        mgr.TryBeginProcessingActivated();
+        Assert.False(mgr.TryBeginProcessingActivated());
+    }
+
+    /// <summary>
+    /// EndProcessingActivated 後應允許再次進入。
+    /// </summary>
+    [Fact]
+    public void EndProcessingActivated_AllowsNextTryBegin()
+    {
+        var mgr = new FormInputStateManager();
+        mgr.TryBeginProcessingActivated();
+        mgr.EndProcessingActivated();
+        Assert.True(mgr.TryBeginProcessingActivated());
+    }
+
+    // ── BeginHotkeyCapture / EndHotkeyCapture / IsHotkeyCaptureActive ──────
+
+    /// <summary>
+    /// 初始狀態下 IsHotkeyCaptureActive 應為 false。
+    /// </summary>
+    [Fact]
+    public void IsHotkeyCaptureActive_Initially_IsFalse()
+    {
+        var mgr = new FormInputStateManager();
+        Assert.False(mgr.IsHotkeyCaptureActive);
+    }
+
+    /// <summary>
+    /// BeginHotkeyCapture 後 IsHotkeyCaptureActive 應為 true。
+    /// </summary>
+    [Fact]
+    public void BeginHotkeyCapture_SetsIsHotkeyCaptureActiveTrue()
+    {
+        var mgr = new FormInputStateManager();
+        mgr.BeginHotkeyCapture();
+        Assert.True(mgr.IsHotkeyCaptureActive);
+    }
+
+    /// <summary>
+    /// EndHotkeyCapture 後 IsHotkeyCaptureActive 應為 false。
+    /// </summary>
+    [Fact]
+    public void EndHotkeyCapture_ClearsIsHotkeyCaptureActive()
+    {
+        var mgr = new FormInputStateManager();
+        mgr.BeginHotkeyCapture();
+        mgr.EndHotkeyCapture();
+        Assert.False(mgr.IsHotkeyCaptureActive);
+    }
+
+    // ── 各流程互不干擾 ──────────────────────────────────────────────────────
+
+    /// <summary>
+    /// 各個狀態旗標應彼此獨立：進入 Returning 不影響 Flashing 的 TryBegin。
+    /// </summary>
+    [Fact]
+    public void MultipleLocks_AreIndependent()
+    {
+        var mgr = new FormInputStateManager();
+        mgr.TryBeginReturning();
+        mgr.TryBeginFlashing();
+
+        // 各自被鎖定
+        Assert.False(mgr.TryBeginReturning());
+        Assert.False(mgr.TryBeginFlashing());
+
+        // 釋放其中一個不影響另一個
+        mgr.EndReturning();
+        Assert.True(mgr.TryBeginReturning());
+        Assert.False(mgr.TryBeginFlashing());
+    }
+}
