swift-protocol-di-testing

透過 Swift Protocol 實作可測試的相依性注入

將檔案系統、網路、iCloud 等外部相依性抽象化為輕巧且職責專一的 Protocol，進而提升 Swift 程式碼的可測試性。讓您無需進行實際 I/O 即可執行可預期的單元測試。

啟用時機

• 撰寫需要存取檔案系統、網路或外部 API 的 Swift 程式碼時
• 需要測試錯誤處理流程，但不想觸發真實失敗時
• 打造需跨環境運作的模組時（App、測試、SwiftUI 預覽）
• 使用 Swift 並發（actors、Sendable）設計可測試的架構時

核心模式

1. 定義輕巧且職責專一的 Protocol

每個 Protocol 僅處理單一外部關注點。

// 檔案系統存取
public protocol FileSystemProviding: Sendable {
    func containerURL(for purpose: Purpose) -> URL?
}

// 檔案讀取/寫入操作
public protocol FileAccessorProviding: Sendable {
    func read(from url: URL) throws -> Data
    func write(_ data: Data, to url: URL) throws
    func fileExists(at url: URL) -> Bool
}

// 書籤儲存（例如用於沙盒化應用程式）
public protocol BookmarkStorageProviding: Sendable {
    func saveBookmark(_ data: Data, for key: String) throws
    func loadBookmark(for key: String) throws -> Data?
}

2. 建立預設（正式環境）實作

public struct DefaultFileSystemProvider: FileSystemProviding {
    public init() {}

    public func containerURL(for purpose: Purpose) -> URL? {
        FileManager.default.url(forUbiquityContainerIdentifier: nil)
    }
}

public struct DefaultFileAccessor: FileAccessorProviding {
    public init() {}

    public func read(from url: URL) throws -> Data {
        try Data(contentsOf: url)
    }

    public func write(_ data: Data, to url: URL) throws {
        try data.write(to: url, options: .atomic)
    }

    public func fileExists(at url: URL) -> Bool {
        FileManager.default.fileExists(atPath: url.path)
    }
}

3. 建立用於測試的 Mock 實作

public final class MockFileAccessor: FileAccessorProviding, @unchecked Sendable {
    public var files: [URL: Data] = [:]
    public var readError: Error?
    public var writeError: Error?

    public init() {}

    public func read(from url: URL) throws -> Data {
        if let error = readError { throw error }
        guard let data = files[url] else {
            throw CocoaError(.fileReadNoSuchFile)
        }
        return data
    }

    public func write(_ data: Data, to url: URL) throws {
        if let error = writeError { throw error }
        files[url] = data
    }

    public func fileExists(at url: URL) -> Bool {
        files[url] != nil
    }
}

4. 使用預設參數注入相依性

正式環境程式碼預設使用實體物件；測試時則注入 Mock 物件。

public actor SyncManager {
    private let fileSystem: FileSystemProviding
    private let fileAccessor: FileAccessorProviding

    public init(
        fileSystem: FileSystemProviding = DefaultFileSystemProvider(),
        fileAccessor: FileAccessorProviding = DefaultFileAccessor()
    ) {
        self.fileSystem = fileSystem
        self.fileAccessor = fileAccessor
    }

    public func sync() async throws {
        guard let containerURL = fileSystem.containerURL(for: .sync) else {
            throw SyncError.containerNotAvailable
        }
        let data = try fileAccessor.read(
            from: containerURL.appendingPathComponent("data.json")
        )
        // 處理資料...
    }
}

5. 使用 Swift Testing 撰寫測試

import Testing

@Test("Sync manager handles missing container")
func testMissingContainer() async {
    let mockFileSystem = MockFileSystemProvider(containerURL: nil)
    let manager = SyncManager(fileSystem: mockFileSystem)

    await #expect(throws: SyncError.containerNotAvailable) {
        try await manager.sync()
    }
}

@Test("Sync manager reads data correctly")
func testReadData() async throws {
    let mockFileAccessor = MockFileAccessor()
    mockFileAccessor.files[testURL] = testData

    let manager = SyncManager(fileAccessor: mockFileAccessor)
    let result = try await manager.loadData()

    #expect(result == expectedData)
}

@Test("Sync manager handles read errors gracefully")
func testReadError() async {
    let mockFileAccessor = MockFileAccessor()
    mockFileAccessor.readError = CocoaError(.fileReadCorruptFile)

    let manager = SyncManager(fileAccessor: mockFileAccessor)

    await #expect(throws: SyncError.self) {
        try await manager.sync()
    }
}

最佳實踐

• 單一職責（Single Responsibility）：每個 Protocol 應只處理一個關注點 — 避免包攬過多方法的「萬能 Protocol」（god protocols）
• 符合 Sendable 協定：當 Protocol 需要跨 actor 邊界使用時為必要條件
• 預設參數：讓正式環境程式碼預設使用真實實作；僅在測試時指定 Mock
• 錯誤模擬：為 Mock 設計可設定的錯誤屬性，以便測試失敗路徑
• 僅 Mock 系統邊界：只對外部相依性（檔案系統、網路、API）進行 Mock，不要 Mock 內部型別

應避免的反模式 (Anti-Patterns)

• 建立包山包海、涵蓋所有外部存取的大型 Protocol
• 針對沒有外部相依性的內部型別進行 Mock
• 使用 #if DEBUG 條件編譯代替良好的相依性注入
• 與 actor 搭配使用時忘記遵循 Sendable 協定
• 過度工程：若型別本身沒有外部相依性，就不需要建立 Protocol

使用時機

• 任何需要存取檔案系統、網路或外部 API 的 Swift 程式碼
• 測試在真實環境中難以觸發的錯誤處理流程
• 開發需在 App、測試及 SwiftUI 預覽環境中執行的模組
• 使用 Swift 並發（actors、結構化並發）且需要可測試架構的 App