雲端 Mac 上的 iOS AsyncStream 緩衝與終止契約測試

雲端 Mac 上的 iOS AsyncStream 緩衝與終止契約測試

雲端 Mac 上的 iOS AsyncStream 緩衝與終止契約測試

你的 iOS 頁面透過 AsyncStream 接收進度事件,偶爾操作時一切正常,連續觸發後卻會跳過中間狀態;離開頁面後,底層監聽器也仍在運作。先別增加等待時間。在 VPSPull 雲端 Mac 上固定事件產生與消費的順序,分別驗證緩衝、結束與清理契約,比反覆點擊遠端桌面更容易找出問題。

先決定哪些事件可以丟棄

進度百分比通常只需要最新狀態,但付款確認或檔案交付紀錄不能任意丟失。先為串流訂下三個條件:哪些值必須送達、事件積壓時如何處理,以及由誰負責停止生產者。不要讓預設緩衝策略替業務需求做決定。

unbounded 會保留尚未消費的元素,但持續產生事件可能讓記憶體用量不斷增加;bufferingNewest(2) 保留最新的兩個元素;bufferingOldest(2) 保留最早的兩個待消費元素。這裡的容量是元素數量,不是位元組數,大型物件仍可能占用大量記憶體。

有界緩衝不等於背壓。AsyncStream 的 yield 不會等待消費者騰出空間;如果業務要求無損傳輸,就需要另外建立確認、限速或持久化機制。

先只測試一個消費者。多個工作共同消費同一個串流,不能直接視為「每個訂閱者都會收到全部事件」的廣播模型。

建立不靠排程運氣的測試夾具

在已備妥 Swift 工具鏈的終端機中執行:

mkdir StreamContract
cd StreamContract
swift package init --type library --name StreamContract
swift --version

將產生的測試檔案內容替換為下列 XCTest 測試。檔案放在 Tests/StreamContractTests/StreamContractTests.swift;如果產生的範本還有其他測試檔案,先移除其中的範例測試,避免把無關結果混入報告。

import XCTest

final class StreamContractTests: XCTestCase {
    func testNewestBufferDrainsAfterFinish() async {
        let pair = AsyncStream<Int>.makeStream(
            bufferingPolicy: .bufferingNewest(2)
        )

        pair.continuation.yield(1)
        pair.continuation.yield(2)

        switch pair.continuation.yield(3) {
        case .dropped(let value):
            XCTAssertEqual(value, 1)
        default:
            XCTFail("Expected the oldest buffered value to be dropped")
        }

        pair.continuation.finish()

        var iterator = pair.stream.makeAsyncIterator()
        let first = await iterator.next()
        let second = await iterator.next()
        let end = await iterator.next()

        XCTAssertEqual(first, 2)
        XCTAssertEqual(second, 3)
        XCTAssertNil(end)

        switch pair.continuation.yield(4) {
        case .terminated:
            break
        default:
            XCTFail("Expected a terminated stream")
        }
    }
}

接著執行 swift test。這個測試先產生事件、再消費事件,刻意讓緩衝區溢位,不必靠休眠來猜測排程順序。如果工具鏈沒有 makeStream,應先確認 Swift 版本,或改用初始化閉包取得 continuation,不能為了「相容」而刪除溢位斷言。

驗收被丟棄的值,不只看消費結果

只斷言最後收到 2、3 並不夠:錯誤的實作可能主動過濾 1,碰巧得到相同結果。檢查 yield 回傳的 .dropped 值,才能確認事件是在緩衝策略這一層被丟棄。

接著複製測試,改用 bufferingOldest(2)。第三次 yield 應回報丟棄 3,消費結果應為 1、2。將這些預期寫成獨立的測試名稱,不要在測試內依照實際輸出調整答案。

還要增加一個邊界案例:容量設為零,且沒有正在等待的消費者時,yield 的元素會被丟棄。零容量不保證同步交接。如果測試提前啟動消費者,就必須建立「已經在等待」的同步訊號,否則結果會隨工作排程而變動。

對於實際物件,記錄穩定的事件編號即可。不要把完整承載資料寫入日誌;資料較大時,記錄編號、丟棄次數與緩衝策略,就足以進行分析。

分開測試 finish、取消與提早離開

finish() 表示不再接受新元素,不代表立即丟棄已緩衝的元素。上面的測試刻意驗證先讀完 2、3,接著 next 才回傳 nil;結束後的 yield 則應回傳 .terminated。

取消測試要另外建立夾具:讓消費工作等待 next,取消該工作,再等待工作退出。使用執行緒安全的計數器或測試預期記錄 onTermination,確認終止原因是取消,也確認底層監聽器已停止。設定有限的逾時時間只是為了防止測試卡住,並不是業務行為正確的證據。

提早離開必須有明確的擁有者

迴圈中的 break 只會離開迴圈。如果其他物件仍持有串流或 continuation,不能據此斷言監聽器已經釋放。為轉接器提供明確的 stop 操作,由頁面或服務擁有者呼叫,再檢查取消註冊的次數。

onTermination 可能在並行執行環境中執行。清理閉包擷取的狀態必須支援並行存取;不要直接修改只能由主執行緒存取的介面物件,也不要在持有內部鎖定時呼叫 finish,再讓終止回呼取得同一把鎖。

用失敗矩陣完成驗收,而不是延長等待

最後至少保留四類驗收測試:最新值緩衝淘汰舊值、最早值緩衝拒絕新值、正常結束後排空,以及取消後停止產生事件。每一類都要檢查值、結束狀態與清理次數,避免「測試通過,但資源仍在運作」。

再用假的監聽器製造停止時的競態:stop 之後再觸發一次回呼,轉接器必須安全地忽略它,或收到 terminated,不能重複交付業務事件。連續呼叫 stop 也應保持冪等,不得重複取消註冊同一個監聽控制代碼。

提交時一併保存工具鏈版本、測試命令與失敗案例名稱。如果固定順序的測試穩定,但實際頁面仍會丟失事件,下一步應檢查事件來源轉接器與消費者的處理速度;如果夾具本身不穩定,先修正同步方式,不要用更長的休眠把競態藏起來。

常見問題

bufferingNewest 會讓生產端等待消費端嗎?

不會。緩衝區滿時會淘汰較舊的元素,yield 回報遭捨棄的值,但不等待消費端騰出空間。若需要有界且無損的傳輸,必須另外設計確認或流量控制機制。

消費端執行 break 後,監聽器一定立即釋放嗎?

不一定。break 只離開迴圈,串流與 continuation 仍可能被持有。應由擁有者明確停止監聽,並分別測試工作取消、主動停止及正常結束的清理路徑。

用一台獨享 Mac 驗證你的工作流程

先確認機型、節點與租用期間,再按天試用。實際可用狀態請以控制台即時回報為準。