InstantMock

Create Mocks Easily in Swift

InstantMock aims at creating mocks easily in Swift, and configuring them with expectations or stubbed implementations.

For examples, see Example.playground.

Swift versions compatibility:

Swift version	InstantMock version
5.0	2.5.X
4.2	2.2.X
4.0	2.0/2.1
3.X	1.1.X

How to Create a Mock?

InstantMock enables to create a single mock that can be used in many tests, for a protocol or a class.

For a Protocol

The easiest way to create a mock for a protocol is to inherit from the Mock class.

// MARK: Protocol to be mocked
protocol Foo {
    func bar(arg1: String, arg2: Int) -> Bool
}

// MARK: Mock class inherits from `Mock` and adopts the `Foo` protocol
class FooMock: Mock, Foo {

    // implement `bar` of the `Foo` protocol
    func bar(arg1: String, arg2: Int) -> Bool {
        return super.call(arg1, arg2)! // provide values to parent class
    }

}

For a Class

To create a mock for a class, the mock must adopt the MockDelegate protocol.

// MARK: Class to be mocked
class Foo {
    func bar(arg1: String, arg2: Int) -> Bool
}

// MARK: Mock class inherits from `Foo` and adopts the `MockDelegate` protocol
class FooMock: Foo, MockDelegate {

    // create `Mock` delegate instance
    private let mock = Mock()

    // conform to the `MockDelegate` protocol, by providing the `Mock` instance
    var it: Mock {
        return mock
    }

    // implement `bar` of the `Foo` class
    override func bar(arg1: String, arg2: Int) -> Bool {
        return mock.call(arg1, arg2)! // provide values to the delegate
    }

}

Rules

To work properly, mocks must comply with a few rules regarding return values, due to Swift strong typing.

Optional Return Value

The syntax is as follow:

func returnsOptional() -> Bool? {
    return mock.call()
}

Here, call() returns nil or Void.

Non-Optional Return Value

For some methods, mocks must return non-optional values. If a return value type adopts the MockUsable protocol (which is the case for the most common types like Bool, Int…), just force unwrapping the result to call(), like in the following example:

func returnsMockUsable() -> Bool { // `Bool` adopts `MockUsable`
    return mock.call()! // force unwrapping
}

For other types, make sure to provide a default value, like in the following example:

func returnsCustom() -> CustomType {
    return mock.call() ?? CustomType() // return a `CustomType` default value
}

Throwing

For catching errors on throwing methods, simply use callThrowing() instead of call().

If a return value type adopts the MockUsable protocol (which is the case for the most common types like Bool, Int…), just force unwrapping the result to callThrowing(), like in the following example:

func bazMockUsable() throws -> Bool {
    return try callThrowing()!
}

For other types, make sure to provide a default value, like in the following example:

func bazCustom() throws -> CustomType {
    return try callThrowing() ?? CustomType() // return a `CustomType` default value
}

Properties

It is possible to mock properties declared in a protocol, like in the following example:

// define protocol with a property `prop` that has a getter and a setter
protocol FooProperty {
    var prop: String { get set }
}

// mock of `FooProperty`
class FooPropertyMock: Mock, FooProperty {
    var prop: String {
        get { return super.call()! }
        set { return super.call(newValue) }
    }
}

How to Set Expectations?

Expectations aim at verifying that a call is done with some arguments. They are set using a syntax like in the following example:

// create mock instance
let mock = FooMock()

// create expectation on `mock`, that is verified when `bar` is called
// with "hello" for `arg1` and any value of the type of `arg2`
mock.expect().call(
    mock.bar(arg1: Arg.eq("hello"), arg2: Arg.any())
)

Reject

Rejections are the contrary of expectations. They make sure no call is being done with some arguments. Simply use reject() instead of expect().

Number of calls

In addition, expectations and rejections can be set on the number of calls: Use the following syntax:

// create expectation on `mock`, that is verified when 2 calls are done on `bar`
// with "hello" for `arg1` and any value of the type of `arg2`
mock.expect().call(
    mock.bar(arg1: Arg.eq("hello"), arg2: Arg.any()),
    count: 2
)

Properties

Setting expectations on properties can be done using the following syntax:

// create mock instance
let mock = FooPropertyMock()

// create expectation on `mock`, that is verified when the property `prop` is called
mock.expect().call(mock.prop)

// create expectation on `mock`, that is verified when the property `prop` is set
// with the exact value "hello"
mock.expect().call(
    mock.property.set(mock.prop, value: Arg.eq("hello"))
)

Verifications

Verifying expectations and rejections is done this way:

// test fails when any of the expectations or rejections set on `mock` is not verified
mock.verify()

Reset Expectations

Expecations can be reset this way:

mock.resetExpectations()

How to Stub Calls?

Stubs aim at performing actions when a function is called with some arguments. They are set using a syntax like in the following example:

// create mock instance
let mock = FooMock()

// create stubbed implementation of the `bar` method, which returns `true` when called
// with "hello" for `arg1` and any value of the type of `arg2`
mock.stub().call(
    mock.bar(arg1: Arg.eq("hello"), arg2: Arg.any())
).andReturn(true)

Return Value

Set the return value with andReturn(…) on the stub instance.

Compute a Return Value

This is done with andReturn(closure: { _ in return … }) on the stub instance. This enables to return different values on the same stub, depending on some conditions.

Call Another Function

This is done with andDo { _ in … } on the stub instance.

Throw an Error

This is done with andThrow(…) on the stub instance.

Chaining

Chaining several actions on the same stub is possible, given they don't confict. For example, it is possible to return a value and call another function, like in andReturn(true).andDo { _ in print("something") }.

Rules:

the last closure registered by andDo is called first
the last error registered by andThrow is thrown
the last return value registered by andReturn is returned
otherwise, the last return value computation method, registered by andReturn(closure:), is called

Reset Stubs

Stubs can be reset this way:

mock.resetStubs()

Example:

// configure mock to return "string" when calling `basic` whatever provided arguments
mock.stub().call(mock.basic(arg1: Arg.any(), arg2: Arg.any())).andReturn("string")

// reset the previously configured stubs
mock.resetStubs()

// calling `basic` does not return "string"
let ret = mock.basic(arg1: "", arg2: 2)
XCTAssertNotEqual(ret, "string")

Argument Matching

Expectations are verified only if arguments match what is registered. Same goes for calling stubbed implementations.

Exact Value

Matching an exact value is done with Arg.eq(…).

Values can be matched if they:

conform to the AnyObject protocol, which is the case for all classes implicitly, for example Arg.eq(NSString("hello"))
or conform to the MockUsable protocol, for example Arg.eq(42)
or they are types, for example Arg.eq(String.self)
or they are tuples, limited to 5 values, for example Arg.eq(("a string", 42))

Any Value

Matching any value can be done for types that adopt the MockUsable protocol, with Arg.any().

Certain Condition

Matching a value that verifies a certain condition is done with Arg.verify({ _ in return … }).

Closure

Matching a closure is a special case. Use the following syntax: Arg.closure().

Limitation: closures can be matched as long as they have less than 5 arguments.

Argument Capturing

Arguments can also be captured for later use thanks to the ArgumentCaptor class.

For example:

// create captor for type `String`
let captor = ArgumentCaptor<String>()

// create expectation on `mock`, that is verified when `bar` is called
// with 42 for `arg2`. All values for `arg1` are captured.
mock.expect().call(mock.bar(arg1: captor.capture(), arg2: Arg.eq(42)))
...

// retrieve the last captured value
let value = captor.value

// retrieve all captured values
let values = captor.allValues

Capturing a Closure

Capturing a closure is particularly useful for stubbing the behavior of a method with callbacks, see this conversation.

Capturing a closure is a special case. Use the following syntax:

Limitation: closures can be captured as long as they have less than 5 arguments.

// create captor for type closure `(Int) -> Bool`
let captor = ArgumentClosureCaptor<(Int) -> Bool>()
...
// retrieve the last captured closure, and call it
let ret = captor.value!(42)

MockUsable

MockUsable is a protocol that makes types easily usable in mocks. For a given type, it allows to return non-optional values and to match any values.

Adding MockUsable on an existing type is done by creating an extension that adopts the protocol. For example:

extension SomeClass: MockUsable {

    static var any = SomeClass() // any value

    // return any value
    public static var anyValue: MockUsable {
        return SomeClass.any
    }

    // returns true if an object is equal to another `MockUsable` object
    public func equal(to value: MockUsable?) -> Bool {
        guard let value = value as? SomeClass else { return false }
        return self == value
    }

}

Adding MockUsable on an existing type that uses inheritance, should always be done on the deepest subclass. Indeed, adding this extension to both a parent and a subclass would create build conflicts.

Supported Types

For now, the following types are MockUsable:

Bool
Int, Int64
UInt, UInt64
Float
Double
String
Set
Array
Dictionary

Changelog

List of changes can be found here.

Requirements

Xcode 10
iOS 9
osX 10.10

Installation

Cocoapods

InstantMock is available using CocoaPods, see Podfile example:

target 'Example' do

    # Tests target
    target 'ExampleTests' do
        inherit! :search_paths
        pod 'InstantMock'
    end

end

Swift Package Manager

InstantMock is available using the Swift Package Manager, by adding the dependency either with Xcode or by editing the Package.swift file:

.package(url: "https://github.com/pirishd/InstantMock", from: "2.5.3"),

Inspiration

Argument Capture: Mockito
Registration API: SwiftMock

Author

Patrick Irlande - pirishd@icloud.com

License

InstantMock is available under the MIT License.

abarisain/InstantMock

InstantMock

Create Mocks Easily in Swift

How to Create a Mock?

For a Protocol

For a Class

Rules

Optional Return Value

Non-Optional Return Value

Throwing

Properties

How to Set Expectations?

Reject

Number of calls

Properties

Verifications

Reset Expectations

How to Stub Calls?

Return Value

Compute a Return Value

Call Another Function

Throw an Error

Chaining

Reset Stubs

Argument Matching

Exact Value

Any Value

Certain Condition

Closure

Argument Capturing

Capturing a Closure

MockUsable

Supported Types

Changelog

Requirements

Installation

Cocoapods

Swift Package Manager

Inspiration

Author

License