MockNRoll: A Swift repository from ullstrm

About Mock 'n' Roll

Mock 'n' Roll is a mocking library for Swift, that helps you mock functionality when unit testing. You can register return values, invoke method calls and inspect function executions on your mocks.

Mock 'n' Roll supports functions with optional and non-optional return values, as well as resultless ones. It supports values, structs, classes and enums and doesn't put any restrains on the code you write.

Creating a mock

Consider that you have the following protocol:

protocol TestProtocol {
    
    func functionWithIntResult(arg1: String, arg2: Int) -> Int
    func functionWithStringResult(arg1: String, arg2: Int) -> String
    func functionWithStructResult(arg1: String, arg2: Int) -> User
    func functionWithClassResult(arg1: String, arg2: Int) -> Thing
    
    func functionWithOptionalIntResult(arg1: String, arg2: Int) -> Int?
    func functionWithOptionalStringResult(arg1: String, arg2: Int) -> String?
    func functionWithOptionalStructResult(arg1: String, arg2: Int) -> User?
    func functionWithOptionalClassResult(arg1: String, arg2: Int) -> Thing?
    
    func functionWithVoidResult(arg1: String, arg2: Int)
}

To mock TestProtocol, you just have to create a class that inherits Mock and implements TestProtocol and then:

register any required return values for any non-optionaö functions you want to test
call invoke in each function, to record all function calls together with the input arguments and return values
check the mock's executions. to assert that the tests were successfully executed

Invoking function calls

Each mocked function must call invoke to record the function call together with the input arguments and possible return value.

For the TestClass above, it would look something like this:

class TestClass: Mock, TestProtocol {
    
    func functionWithIntResult(arg1: String, arg2: Int) -> Int {
        return invoke(functionWithIntResult, args: (arg1, arg2))
    }
    
    func functionWithStringResult(arg1: String, arg2: Int) -> String {
        return invoke(functionWithStringResult, args: (arg1, arg2))
    }
    
    func functionWithStructResult(arg1: String, arg2: Int) -> User {
        return invoke(functionWithStructResult, args: (arg1, arg2))
    }
    
    func functionWithClassResult(arg1: String, arg2: Int) -> Thing {
        return invoke(functionWithClassResult, args: (arg1, arg2))
    }
    
    
    func functionWithOptionalIntResult(arg1: String, arg2: Int) -> Int? {
        return invoke(functionWithOptionalIntResult, args: (arg1, arg2))
    }
    
    func functionWithOptionalStringResult(arg1: String, arg2: Int) -> String? {
        return invoke(functionWithOptionalStringResult, args: (arg1, arg2))
    }
    
    func functionWithOptionalStructResult(arg1: String, arg2: Int) -> User? {
        return invoke(functionWithOptionalStructResult, args: (arg1, arg2))
    }
    
    func functionWithOptionalClassResult(arg1: String, arg2: Int) -> Thing? {
        return invoke(functionWithOptionalClassResult, args: (arg1, arg2))
    }
    
    
    func functionWithVoidResult(arg1: String, arg2: Int) {
        invoke(functionWithVoidResult, args: (arg1, arg2))
    }
}

Void functions just have to call invoke while returning functions must call return invoke.

Whenever your unit tests touch any of these functions, you will now be able to inspect the recorded function calls to verify that the mock is called as expected.

Registering values

For functions that return a non-optional value, your tests must register the actual return values before touching the mocked functions. Failing to do so will make your tests crash with a preconditionFailure.

You register return values by calling the mock's registerResult(for:result:) function, like this:

let mock = TestClass()
mock.registerResult(for: mock.functionWithIntResult) { _ in return 123 }

Since the result block takes in the same arguments as the actual function, you can return different result values depending on the input arguments:

let mock = TestClass()
mock.registerResult(for: mock.functionWithIntResult) { _, arg2 in  return arg2 }
mock.registerResult(for: mock.functionWithStringResult) { arg1, _ in  return arg1 }

You don't have to register a return value for void functions or functions that return an optional value, but you should do so whenever you want to affect your tests.

Inspecting executions

To verify that a mock receives the expected function calls, you can use executions(for:) to get information on how many times a function did receive a call, with which input arguments and what result it returned:

_ = mock.functionWithIntResult(arg1: "abc", arg2: 123)
_ = mock.functionWithIntResult(arg1: "abc", arg2: 456)
_ = mock.functionWithIntResult(arg1: "abc", arg2: 789)
_ = mock.functionWithStringResult(arg1: "abc", arg2: 123)
_ = mock.functionWithStringResult(arg1: "def", arg2: 123)

let intExecutions = mock.executions(of: mock.functionWithIntResult)
let stringExecutions = mock.executions(of: mock.functionWithStringResult)
expect(intExecutions.count).to(equal(3))
expect(stringExecutions.count).to(equal(2))
expect(intExecutions[0].arguments.0).to(equal("abc"))
expect(intExecutions[0].arguments.1).to(equal(123))
expect(intExecutions[1].arguments.0).to(equal("abc"))
expect(intExecutions[1].arguments.1).to(equal(456))
expect(intExecutions[2].arguments.0).to(equal("abc"))
expect(intExecutions[2].arguments.1).to(equal(789))
expect(stringExecutions[0].arguments.0).to(equal("abc"))
expect(stringExecutions[0].arguments.1).to(equal(123))
expect(stringExecutions[1].arguments.0).to(equal("def"))
expect(stringExecutions[1].arguments.1).to(equal(123))

Note that the code above uses Quick/Nimble, in case you don't recognize the syntax.

Registering and throwing errors

There is currently no support for registering and throwing errors, which means that async functions can't (yet) register custom return values. Until this is implemented, you can use the Mock class' error property.

Installation

CocoaPods

To install Mock 'n' Roll with CocoaPods, add this to your Podfile:

pod 'MockNRoll'

Carthage

To install Mock 'n' Roll with Carthage, add this to your Cartfile:

github "danielsaidi/MockNRoll"

Manual installation

To add Mock 'n' Roll to your app without using Carthage or CocoaPods, clone this repository and place it somewhere on disk, then add MockNRoll.xcodeproj to your project and add MockNRoll.framework as an embedded app binary and target dependency.

Important device limitations

Mock 'n' Roll uses unsafe bit casts to get the memory address of mocked functions. This only works on 64-bit devices, which means that mock-based unit tests will not work on old devices or simulators like iPad 2, iPad Retina etc.

Contact me

I hope you like this library. Feel free to reach out if you have questions or if you want to contribute in any way:

Acknowledgements

Mock 'n' Roll is inspired by Stubber, and would not have been possible without it. The entire function address approach and escape support etc. comes from Stubber, and this mock implementation comes from there as well.

However, while Stubber uses global functions (which requires you to reset the global state every now and then), Mock 'n' Roll moves this logic to each mock, which means that any recorded exeuctions are automatically reset when the mock is disposed. Mock 'n' Roll also adds some extra functionality, like support for optional and void results.

License

Mock 'n' Roll is available under the MIT license. See the LICENSE file for more info.

ullstrm/MockNRoll