Mockable

Mockable is a macro-driven testing framework for Swift that automatically generates mock implementations for your protocols. By leveraging the Swift macro system, it eliminates the need for external code-generation dependencies like Sourcery.

Key features include:

• Declarative API: Rapidly specify return values and verify method invocations in a readable format.
• Advanced Swift Support: Supports associated types, generic functions, where clauses, and constrained generic arguments.
• Build Safety: Generated mock implementations can be excluded from release builds using a built-in compile condition.

Mockable supports a wide range of Swift protocol requirements for zero-boilerplate mock generation, including:

• Protocols with associated types and constrained associated types
• init requirements
• Generic function parameters and return values (including those with where clauses)
• Computed and mutable property requirements
• @escaping closure parameters
• Implicitly unwrapped optionals
• throwing, rethrowing, and async requirements
• Custom non-equatable types

Mockable uses a declarative builder syntax: clause type(service).function builder.behavior builder.

Parameter Matching

When calling function builders, you must specify a condition for every parameter using the Parameter<Value> type:

• .any: Matches any value.
• .value(Value): Matches an identical value.
• .matching((Value) -> Bool): Matches based on a custom closure.

For mutable properties, use the (newValue:) parameter to constrain behavior on property assignment.

// Match any ID
given(productService).fetch(for: .any).willThrow(error)

// Match specific property value
when(productService).checkout(with: .matching { $0.name == "iPhone 15 Pro" }).perform { print("Ouch!") }

// Match exact value
verify(productService).fetch(for: .value(id)).called(.once)

The @Mockable macro wraps generated code in a compile-time check for the MOCKING flag. This ensures that mock implementations are only included in builds where the flag is defined (typically debug/test builds) and are excluded from release bundles.

Because MOCKING is not defined by default, you must manually configure your build system to define this flag in your debug configurations to use the mocks.

#if MOCKING
public final class MockService: Service, Mockable {
    // generated code...
}
#endif

Because @Mockable is a peer macro, generated code exists in the same scope as the protocol. To prevent mock implementations from being included in release builds, the macro expansion is wrapped in the MOCKING compile-time flag.

You must define this flag in your project to use mocks.

If you are working with Swift Package Manager (SPM) modules or testing an SPM package, add Mockable as a dependency in your Package.swift file. You should add the Mockable product to both your main target and your test target definitions to ensure protocols can be mocked in both production and test environments.

let package = Package(
    ...
    dependencies: [
        .package(url: "https://github.com/Kolos65/Mockable", from: "0.0.1"),
    ],
    targets: [
        .target(
            ...
            dependencies: [
                .product(name: "Mockable", package: "Mockable")
            ]
        ),
        .testTarget(
            ...
            dependencies: [
                .product(name: "Mockable", package: "Mockable")
            ]
        )
    ]
)

For Tuist users, define the MOCKING flag in the target's settings under the debug configuration using the SWIFT_ACTIVE_COMPILATION_CONDITIONS key.

.target(
    ...
    settings: .settings(
        configurations: [
            .debug(
                name: .debug, 
                settings: [
                    "SWIFT_ACTIVE_COMPILATION_CONDITIONS": "$(inherited) MOCKING"
                ]
            )
        ]
    )
)

For Swift Package Manager (SPM) modules, define the MOCKING condition within your Package.swift manifest. It is recommended to use .when(configuration:) to ensure the flag is only active during debug builds.

.target(
    ...
    swiftSettings: [
        .define("MOCKING", .when(configuration: .debug))
    ]
)

Add the Mockable target to all targets containing the protocols you wish to mock. Note that Mockable does not depend on XCTest, so it can be added to any target.

When using the plugin for the first time, you must trust and enable it when prompted by Xcode.

For unattended environments like CI, you can disable macro validation using one of these methods:

• Use the xcodebuild flag: -skipMacroValidation
• Set Xcode defaults: defaults write com.apple.dt.Xcode IDESkipMacroFingerprintValidation -bool YES

# Example xcodebuild flag for CI
xcodebuild -skipMacroValidation

# Example setting Xcode defaults
defaults write com.apple.dt.Xcode IDESkipMacroFingerprintValidation -bool YES

If your project uses standard Xcode build settings, follow these steps to enable mocks for your targets:

1. Open your Xcode project.
2. Select your target and go to the Build Settings tab.
3. Search for Swift Compiler - Custom Flags.
4. Locate the Active Compilation Conditions section.
5. Add the MOCKING flag under your debug build configuration(s).
6. Repeat this for every target where you intend to use the @Mockable macro.