Swift Protocol-Based Dependency Injection for Testing

Patterns for making Swift code testable by abstracting external dependencies (file system, network, iCloud) behind small, focused protocols. Enables deterministic tests without I/O.

When to Activate

• Writing Swift code that accesses file system, network, or external APIs
• Need to test error handling paths without triggering real failures
• Building modules that work across environments (app, test, SwiftUI preview)
• Designing testable architecture with Swift concurrency (actors, Sendable)

Core Pattern

1. Define Small, Focused Protocols

Each protocol handles exactly one external concern.

swift
1// File system access
2public protocol FileSystemProviding: Sendable {
3    func containerURL(for purpose: Purpose) -> URL?
4}
5
6// File read/write operations
7public protocol FileAccessorProviding: Sendable {
8    func read(from url: URL) throws -> Data
9    func write(_ data: Data, to url: URL) throws
10    func fileExists(at url: URL) -> Bool
11}
12
13// Bookmark storage (e.g., for sandboxed apps)
14public protocol BookmarkStorageProviding: Sendable {
15    func saveBookmark(_ data: Data, for key: String) throws
16    func loadBookmark(for key: String) throws -> Data?
17}

2. Create Default (Production) Implementations

swift
1public struct DefaultFileSystemProvider: FileSystemProviding {
2    public init() {}
3
4    public func containerURL(for purpose: Purpose) -> URL? {
5        FileManager.default.url(forUbiquityContainerIdentifier: nil)
6    }
7}
8
9public struct DefaultFileAccessor: FileAccessorProviding {
10    public init() {}
11
12    public func read(from url: URL) throws -> Data {
13        try Data(contentsOf: url)
14    }
15
16    public func write(_ data: Data, to url: URL) throws {
17        try data.write(to: url, options: .atomic)
18    }
19
20    public func fileExists(at url: URL) -> Bool {
21        FileManager.default.fileExists(atPath: url.path)
22    }
23}

3. Create Mock Implementations for Testing

swift
1public final class MockFileAccessor: FileAccessorProviding, @unchecked Sendable {
2    public var files: [URL: Data] = [:]
3    public var readError: Error?
4    public var writeError: Error?
5
6    public init() {}
7
8    public func read(from url: URL) throws -> Data {
9        if let error = readError { throw error }
10        guard let data = files[url] else {
11            throw CocoaError(.fileReadNoSuchFile)
12        }
13        return data
14    }
15
16    public func write(_ data: Data, to url: URL) throws {
17        if let error = writeError { throw error }
18        files[url] = data
19    }
20
21    public func fileExists(at url: URL) -> Bool {
22        files[url] != nil
23    }
24}

4. Inject Dependencies with Default Parameters

Production code uses defaults; tests inject mocks.

swift
1public actor SyncManager {
2    private let fileSystem: FileSystemProviding
3    private let fileAccessor: FileAccessorProviding
4
5    public init(
6        fileSystem: FileSystemProviding = DefaultFileSystemProvider(),
7        fileAccessor: FileAccessorProviding = DefaultFileAccessor()
8    ) {
9        self.fileSystem = fileSystem
10        self.fileAccessor = fileAccessor
11    }
12
13    public func sync() async throws {
14        guard let containerURL = fileSystem.containerURL(for: .sync) else {
15            throw SyncError.containerNotAvailable
16        }
17        let data = try fileAccessor.read(
18            from: containerURL.appendingPathComponent("data.json")
19        )
20        // Process data...
21    }
22}

5. Write Tests with Swift Testing

swift
1import Testing
2
3@Test("Sync manager handles missing container")
4func testMissingContainer() async {
5    let mockFileSystem = MockFileSystemProvider(containerURL: nil)
6    let manager = SyncManager(fileSystem: mockFileSystem)
7
8    await #expect(throws: SyncError.containerNotAvailable) {
9        try await manager.sync()
10    }
11}
12
13@Test("Sync manager reads data correctly")
14func testReadData() async throws {
15    let mockFileAccessor = MockFileAccessor()
16    mockFileAccessor.files[testURL] = testData
17
18    let manager = SyncManager(fileAccessor: mockFileAccessor)
19    let result = try await manager.loadData()
20
21    #expect(result == expectedData)
22}
23
24@Test("Sync manager handles read errors gracefully")
25func testReadError() async {
26    let mockFileAccessor = MockFileAccessor()
27    mockFileAccessor.readError = CocoaError(.fileReadCorruptFile)
28
29    let manager = SyncManager(fileAccessor: mockFileAccessor)
30
31    await #expect(throws: SyncError.self) {
32        try await manager.sync()
33    }
34}

Best Practices

• Single Responsibility: Each protocol should handle one concern — don't create "god protocols" with many methods
• Sendable conformance: Required when protocols are used across actor boundaries
• Default parameters: Let production code use real implementations by default; only tests need to specify mocks
• Error simulation: Design mocks with configurable error properties for testing failure paths
• Only mock boundaries: Mock external dependencies (file system, network, APIs), not internal types

Anti-Patterns to Avoid

• Creating a single large protocol that covers all external access
• Mocking internal types that have no external dependencies
• Using #if DEBUG conditionals instead of proper dependency injection
• Forgetting Sendable conformance when used with actors
• Over-engineering: if a type has no external dependencies, it doesn't need a protocol

When to Use

• Any Swift code that touches file system, network, or external APIs
• Testing error handling paths that are hard to trigger in real environments
• Building modules that need to work in app, test, and SwiftUI preview contexts
• Apps using Swift concurrency (actors, structured concurrency) that need testable architecture