Mockingbird Documentation 0.18.0

Extensions on NSObjectProtocol

Methods

forward​Calls​ToSuper()

@discardableResult
  func forwardCallsToSuper() -> Self  

Create a partial mock, forwarding all calls without an explicit stub to the superclass.

Use forwardCallsToSuper on class mocks to call the superclass implementation. Superclass forwarding persists until removed with clearStubs or shadowed by a forwarding target that was added afterwards.

class Bird {
  let name: String
  init(name: String) { self.name = name }
}

// `BirdMock` subclasses `Bird`
let bird: BirdMock = mock(Bird.self).initialize(name: "Ryan")

bird.forwardCallsToSuper()
print(bird.name)  // Prints "Ryan"

Concrete stubs always have a higher priority than forwarding targets, regardless of the order they were added.

let bird = mock(Bird.self).initialize(name: "Sterling")
given(bird.name).willReturn("Ryan")
bird.forwardCallsToSuper()
print(bird.name)  // Prints "Ryan"

Objects must inherit from the mocked type to handle forwarded invocations, even if the declaration is identical. Adding an unrelated type as a forwarding target is a no-op.

// Not a class
protocol AbstractBird {
  var name: String { get }
}

let bird = mock(AbstractBird.self)
bird.forwardCallsToSuper()
print(bird.name)  // Error: Missing stubbed implementation

Returns

A partial mock using the superclass to handle invocations.

forward​Calls(to:​)

@discardableResult
  func forwardCalls<T>(to target: T) -> Self  

Create a partial mock, forwarding all calls without an explicit stub to an object.

Objects are strongly referenced and receive proxed invocations until removed with clearStubs. Targets added afterwards have a higher precedence and only pass calls down the forwarding chain if unable handle the invocation, such as when the target is unrelated to the mocked type.

class Crow: Bird {
  let name: String
  init(name: String) { self.name = name }
}

let bird = mock(Bird.self)
bird.forwardCalls(to: Crow(name: "Ryan"))
print(bird.name)  // Prints "Ryan"

// Additional targets take precedence
bird.forwardCalls(to: Crow(name: "Sterling"))
print(bird.name)  // Prints "Sterling"

Concrete stubs always have a higher priority than forwarding targets, regardless of the order they were added.

given(bird.name).willReturn("Ryan")
bird.forwardCalls(to: Crow(name: "Sterling"))
print(bird.name)  // Prints "Ryan"

Objects must inherit from the mocked type to handle forwarded invocations, even if the declaration is identical. Adding an unrelated type as a forwarding target is a no-op.

// Not a `Bird`
class Person {
  var name = "Ryan"
}

bird.forwardCalls(to: Person())
print(bird.name)  // Error: Missing stubbed implementation

Parameters

object

An object that should handle forwarded invocations.

Returns

A partial mock using object to handle invocations.

use​Default​Values(from:​)

@discardableResult
  func useDefaultValues(from valueProvider: ValueProvider) -> Self  

Adds a value provider returning default values for unstubbed methods to this mock.

Mocks are strict by default, meaning that calls to unstubbed methods will trigger a test failure. Methods returning Void do not need to be stubbed in strict mode.

let bird = mock(Bird.self)
print(bird.name)  // Fails because `bird.name` is not stubbed
bird.fly()        // Okay because `fly()` has a `Void` return type

To return default values for unstubbed methods, use a ValueProvider with the initialized mock. Mockingbird provides preset value providers which are guaranteed to be backwards compatible, such as .standardProvider.

bird.useDefaultValues(from: .standardProvider)
print(bird.name)  // Prints ""

You can create custom value providers by registering values for types. See Providable for how to provide "wildcard" instances for generic types.

var valueProvider = ValueProvider(from: .standardProvider)
valueProvider.register("Ryan", for: String.self)
bird.useDefaultValues(from: valueProvider)
print(bird.name)  // Prints "Ryan"

Values from concrete stubs always have a higher precedence than default values.

given(bird.name) ~> "Ryan"
print(bird.name)  // Prints "Ryan"

bird.useDefaultValues(from: .standardProvider)
print(bird.name)  // Prints "Ryan"

Parameters

value​Provider Value​Provider

A value provider to add.