MockSix

MockSix is a microframework to make object mocking in Swift somewhat easier. MockSix is built upon Daniel Burbank’s MockFive.

If you are using Quick+Nimble, make sure you check out the Nimble matcher extensions at NimbleMockSix as well.

Elevator pitch

MockSix simplifies manual object mocking by taking over some of the boilerplate and offering an API that is hard to use incorrectly.

Sample code:

// original interface
protocol MyClassProtocol {
   func myFunc(_ string: String) -> [Int]
}

// actual implementation
class MyClass: MyClassProtocol {
    func myFunc(_ string: String) -> [Int] {
        // ... whatever ...
        return result
    }
}

// mock implementation
class MockMyClass: MyClassProtocol, Mock {
    enum Methods: Int {
        case myFunc
    }    
    typealias MockMethod = Methods
    
    func myFunc(_ string: String) -> [Int] {
        return registerInvocation(for: .myFunc, 
                                  args: string, 
                                  andReturn: [])
    }
    
    init() {}
}

// in the test case
let mock = MockMyClass()
mock.myFunc("foobar") == []     // true
mock.stub(.myFunc, andReturn: [42])
mock.myFunc("foobar") == [42]   // true
mock.stub(.myFunc) { $0.isEmpty ? [] : [42] }
mock.myFunc("foobar") == [42]   // true

Requirements

To build: Swift 4.2
To use: macOS 10.10+, iOS 8.4+, tvOS 9.2+, Linux

Installation

Via Cocoapods: add the following line to your Podfile:

pod 'MockSix'

Via Carthage: add the following line to your Cartfile (or Cartfile.private):

github "lvsti/MockSix"

Via the Swift Package Manager: add it to the dependencies in your Package.swift:

// swift-tools-version:4.0
let package = Package(
    name: "MyAwesomeApp",
    dependencies: [
        .package(url: "https://github.com/lvsti/MockSix", from: "0.1.7"),
        // ... other dependencies ...
    ],
    targets: [
        .target(name: "MyAwesomeApp", dependencies: []),
        .testTarget(
            name: "MyAwesomeAppTests",
            dependencies: ["MyAwesomeApp", "MockSix"]
        )
    ],
)

Or just add MockSix.swift and MockSixInternal.swift to your test target.

Usage

Creating the mock implementation

Conform to Mock besides the actual protocol you are creating the mock for:
```
class MockFoobar: FoobarProtocol, Mock {
```
Declare an enum for the methods (“method ID”) you want to make available in the mock and set it for the MockMethod typealias:
```
    enum Methods: Int {
        case doThis
        case doThat
    }    
    typealias MockMethod = Methods
```
The enum must have a RawValue of Int.

Implement the methods by calling through registerInvocation or registerThrowingInvocation:

    func doThis(_ string: String, _ number: Int) -> [Int] {
        return registerInvocation(for: .doThis, 
                                  args: string, number, 
                                  andReturn: [])
    }
    func doThat() throws -> Double {
        return registerThrowingInvocation(for: .doThat, 
                                          andReturn: 0.0)
    }

Define any properties mandated by the protocol:
```
    var stuff: Int = 0
}
```

Using the mock

call resetMockSix() at the beginning of each test (typically in a beforeEach block)

instantiate and inject as usual:

let foobar = MockFoobar()
let sut = MyClass(foobar: foobar)

stub methods by referring to their method ID:

// return value override
foobar.stub(.doThis, andReturn: [42])

// replace implementation with closure
foobar.stub(.doThis) { (args: [Any?]) in
    let num = args[1]! as! Int
    return [num]
}
foobar.stub(.doThat) { _ in
    if arc4random() % 2 == 1 { throw FoobarError.unknown }
    return 3.14
}

// invocation count aware stubbing
foobar.stub(.doThis, andReturn: [42], times: 1, afterwardsReturn: [43])

CAVEAT: the return value type must exactly match that of the function, e.g. to return a conforming SomeClass instance from a function with SomeClassProtocol return type, use explicit casting:

foobar.stub(.whatever, andReturn: SomeClass() as SomeClassProtocol)

remove stubs to restore the behavior defined in the mock implementation:
```
foobar.unstub(.doThat)
```

access raw invocation logs (if you really need to; otherwise you are better off with the Nimble matchers):

// the mock has not been accessed
foobar.invocations.isEmpty

// doThis(_:_:) has been called twice
foobar.invocations
    .filter { $0.methodID == MockFoobar.Methods.doThis.rawValue }
    .count == 2

// doThis(_:_:) has been called with ("42", 42)
!foobar.invocations
    .filter { 
        $0.methodID == MockFoobar.Methods.doThis.rawValue &&
        $0.args[0]! as! String == "42" &&
        $0.args[1]! as! Int == 42
    }
    .isEmpty

Other stuff

I also wrote two blogposts about MockSix which may help you get started:

Lightweight Object Mocking in Swift: motivation and design decisions, and also an overview of the MockSix Nimble matchers
MockSix + Sourcery: Happily Ever After?: how to use Sourcery to automatically generate MockSix-style mocks without writing a single line of boilerplate

Troubleshooting

Invocation logs are showing unrelated calls => try calling resetMockSix() in the setup phase of each test case
Test crashes with cast error => make sure the types of the returned values match the return type of the stubbed function; use explicit casting where required

License

MockSix is released under the MIT license.