Cuckoo Mocking Framework for Swift

Cuckoo is a mocking framework for Swift that operates using two components: a runtime and a command-line tool called Cuckoonator.

Because Swift lacks full reflection, Cuckoo uses a compile-time generation approach. The Cuckoonator tool scans your specified files and generates supporting structs and classes. These generated files allow the runtime to create mocks via inheritance and protocol adoption.

Key Limitation: Only overridable code can be mocked. If a component cannot be overridden (e.g., due to final modifiers or being a struct), Cuckoo cannot mock it directly.

Cuckoo relies on inheritance and protocol adoption to create mocks. This determines what can and cannot be mocked.

Supported

• Inheritance (including grandparent methods)
• Generics
• Simple type inference for instance variables (via initializers, as TYPE notation, or explicit type specification)
• Objective-C mocks (utilizing OCMock)

Unsupported

Due to Swift's language constraints, the following cannot be mocked:

• struct (Workaround: use a common protocol instead)
• Anything with final or private modifiers
• Global constants and functions
• Static properties and methods

Add Cuckoo to your test targets only.

1. Add the Cuckoo repository URL: https://github.com/Brightify/Cuckoo.git.
2. In your test target's Build Phases, add the CuckooPluginSingleFile plug-in to the Run Build Tool Plug-ins section.

If your project has multiple modules and you want to generate separate mock files per dependency, use CuckooPluginModular instead. This plugin automatically detects source modules from your test target's dependencies and generates a dedicated mock file for each one (e.g., GeneratedMocks_<ModuleName>.swift).

To contribute to Cuckoo or run the project locally, follow these steps:

1. Clone the repository.
2. Install Mise.
3. Run make at the root of the repository. This installs dependencies, generates the project using Tuist, and opens the workspace in Xcode.
4. Important: Re-run make whenever you switch branches to ensure the project files are correctly regenerated by Tuist.

Project Structure

When opening Cuckoo.xcworkspace in Xcode, the project is organized as follows:

• Source: Contains the runtime sources.
• Tests: Contains tests for the runtime.
• Generator.xcodeproj: Contains the generator source code. Use the Generator scheme to run the generator code.

Cuckoo can automatically discover source files by inspecting an .xcodeproj file.

If you provide an xcodeproj path and a target name in your module configuration:

• The generator will locate the .xcodeproj file.
• It will find the specific target within that project.
• It will extract all source files associated with that target.

Note on Merging: If you define both an xcodeproj and a manual list of sources, Cuckoo will merge both lists together to form the complete set of input files. If glob is enabled in your options, Cuckoo will also expand any glob patterns found within the source paths.

When generating mocks, you can filter which classes and protocols are processed using several options in the Module configuration:

• Protocols only: If protocolsOnly is enabled, all classes are ignored, and only protocols are used to generate mocks.
• Regex matching: You can provide a regex pattern. Only classes or protocols whose names match this regular expression will be included.
• Exclusion list: You can provide a list of names in exclude. Any class or protocol matching a name in this list will be ignored.

These filters are applied during the generation process to ensure only the desired types are mocked.

Cuckoo can handle inheritance hierarchies during mock generation. If enableInheritance is set to true in your module options, the generator performs two main tasks:

1. Merging Inheritance: It merges member containers across files to resolve inheritance relationships.
2. NSObject Support: It identifies protocols that recursively inherit from NSObjectProtocol and applies inheritNSObject logic to ensure compatibility with Objective-C/NSObject-based types.

This is particularly useful when mocking types that rely on the NSObject hierarchy.

Use ArgumentCaptor to inspect the actual arguments passed to a mock during verification. This is recommended for verification rather than stubbing.

let argumentCaptor = ArgumentCaptor<Int>()

// Perform actions
mock.readWriteProperty = 10
mock.readWriteProperty = 20
mock.readWriteProperty = 30

// Verify and capture
verify(mock, times(3)).readWriteProperty.set(argumentCaptor.capture())

print(argumentCaptor.value)    // Returns the last captured argument: 30
print(argumentCaptor.allValues) // Returns all captured values: [10, 20, 30]

let argumentCaptor = ArgumentCaptor<Int>()
verify(mock, times(3)).readWriteProperty.set(argumentCaptor.capture())
argumentCaptor.value // Returns 30
argumentCaptor.allValues // Returns [10, 20, 30]

You can provide an instance of the original class to a mock so that any method/property not explicitly stubbed uses the original implementation.

For Classes:

let original = OriginalClass<Int>(value: 12)
mock.enableDefaultImplementation(original)

For Structs: If you are mocking a protocol that a struct conforms to, you must decide if you need to track changes to the struct.

• enableDefaultImplementation(_:): Creates a copy of the struct. Changes to the original struct are not reflected in the mock.
• enableDefaultImplementation(mutating:): Takes a reference to the struct. Changes made during mock calls are reflected in the original struct.

let original = ConformingStruct<String>(value: "Hello, Cuckoo!")
mock.enableDefaultImplementation(original)
// or to track changes:
mock.enableDefaultImplementation(mutating: &original)