alvarhansen / mockingbird Goto Github PK

// Mocking
let bird = mock(Bird.self)

// Stubbing
given(bird.getName()) ~> "Ryan"

// Verification
verify(bird.fly()).wasCalled()

Mockingbird is a Swift mocking framework that lets you throw away your hand-written mocks and write clean, readable tests.

• Expansive coverage of Swift language features
  • Mock classes and protocols in a single line of code
  • Support for generics, inheritance, static members, nested classes, type aliasing, etc.
• Seamless integration with Xcode projects
  • Automatic discovery of source and dependency files
  • Handling of external types from third-party libraries
• Convenient testing API
  • Clear stubbing and verification error messages
  • Support for asynchronous code, in order verification, default return value stubbing, etc.

Mockingbird consists of two main components: the generator and the testing framework. The generator creates mocks before each test bundle compilation by implementing protocols and subclassing classes, while the testing framework hooks into the generated code and provides APIs for mocking, stubbing, and verification.

A key design consideration was performance. Mockingbird runs an optimized parser built on SwiftSyntax and SourceKit that is ~30-40x faster than existing frameworks and supports a broad range of complex Swift features like generics and type qualification.

protocol Bird {
  var canFly: Bool { get }
  func fly()
}

class Tree {
  let bird: Bird
  
  init(with bird: Bird) {
    self.bird = bird
  }
  
  func shake() {
    guard bird.canFly else { return }
    bird.fly()
  }
}

func testShakingTreeCausesBirdToFly() {
  // Given a tree with a bird that can fly
  let bird = mock(Bird.self)
  let tree = Tree(with: bird)
  given(bird.getCanFly()) ~> true
  
  // When the tree is shaken
  tree.shake()
  
  // Then the bird flies away
  verify(bird.fly()).wasCalled()
}

Select your preferred dependency manager below for installation instructions and example projects.

target 'MyAppTests' do
  use_frameworks!
  pod 'MockingbirdFramework', '~> 0.13'
end

$ pod install
$ (cd Pods/MockingbirdFramework && make install-prebuilt)

$ mockingbird download starter-pack
$ mockingbird install --target MyAppTests --sources MyApp MyLibrary1 MyLibrary2

github "birdrides/mockingbird" ~> 0.13

$ carthage update
$ (cd Carthage/Checkouts/mockingbird && make install-prebuilt)

$ mockingbird download starter-pack
$ mockingbird install --target MyAppTests --sources MyApp MyLibrary1 MyLibrary2

let package = Package(
  name: "MyPackage",
  dependencies: [
    .package(url: "https://github.com/birdrides/mockingbird.git", .upToNextMinor(from: "0.13.0")),
  ],
  targets: [
    .testTarget(name: "MyPackageTests", dependencies: ["Mockingbird"]),
  ]
)

$ xcodebuild -resolvePackageDependencies
$ DERIVED_DATA=$(xcodebuild -showBuildSettings | pcregrep -o1 'OBJROOT = (/.*)/Build')
$ (cd "${DERIVED_DATA}/SourcePackages/checkouts/mockingbird" && make install-prebuilt)

$ mockingbird download starter-pack
$ mockingbird install --target MyPackageTests --sources MyPackage MyLibrary1 MyLibrary2

1. Mocking
2. Stubbing
3. Verification
4. Argument Matching
5. Miscellaneous

Initialized mocks can be passed in place of the original type. Protocol mocks do not require explicit initialization while class mocks should be created using initialize(…).

protocol Bird {
  init(name: String)
}
class Tree {
  init(with bird: Bird) {}
}

let bird = mock(Bird.self)  // Protocol mock
let tree = mock(Tree.self).initialize(with: bird)  // Class mock

Generated mock types are suffixed with Mock and should not be coerced into their supertype.

let bird: BirdMock = mock(Bird.self)  // The concrete type is `BirdMock`
let inferredBird = mock(Bird.self)    // Type inference also works
let coerced: Bird = mock(Bird.self)   // Avoid upcasting mocks

Reset mocks and clear specific configurations during test runs.

reset(bird)                    // Reset everything
clearStubs(on: bird)           // Only remove stubs
clearDefaultValues(on: bird)   // Only remove default values
clearInvocations(on: bird)     // Only remove recorded invocations

Stubbing allows you to define custom behavior for mocks to perform.

given(bird.canChirp()) ~> true
given(bird.canChirp()) ~> { throw BirdError() }
given(bird.canChirp(volume: any())) ~> { volume in
  return volume < 42
}

Match argument values to stub methods with parameters. Stubs added later have a higher precedence, so add stubs with specific matchers last.

given(bird.canChirp(volume: any())) ~> true     // Any volume
given(bird.canChirp(volume: notNil())) ~> true  // Any non-nil volume
given(bird.canChirp(volume: 10)) ~> true        // Volume = 10

Stub properties with their getter and setter methods.

given(bird.getName()) ~> "Ryan"
given(bird.setName(any())) ~> { print($0) }

Getters can be stubbed to automatically save and return values.

given(bird.getName()) ~> lastSetValue(initial: "")
print(bird.name)  // Prints ""
bird.name = "Ryan"
print(bird.name)  // Prints "Ryan"

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.getName()` 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.

let bird = mock(Bird.self)
useDefaultValues(from: .standardProvider, on: bird)
print(bird.name)  // Prints ""

You can create custom value providers by registering values for types.

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

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

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

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

Provide wildcard instances for generic types by conforming the base type to Providable and registering the type.

extension Array: Providable {
  public static func createInstance() -> Self? {
    return Array()
  }
}

// Provide an empty array for all specialized `Array` types
valueProvider.registerType(Array<Any>.self)

Methods that return a different value each time can be stubbed with a sequence of values. The last value will be used for all subsequent invocations.

given(bird.getName()) ~> sequence(of: "Ryan", "Sterling")
print(bird.name)  // Prints "Ryan"
print(bird.name)  // Prints "Sterling"
print(bird.name)  // Prints "Sterling"

Verification lets you assert that a mock received a particular invocation during its lifetime.

verify(bird.fly()).wasCalled()

Verifying doesn’t remove recorded invocations, so it’s safe to call verify multiple times.

verify(bird.fly()).wasCalled()  // If this succeeds...
verify(bird.fly()).wasCalled()  // ...this also succeeds

Match argument values to verify methods with parameters.

verify(bird.canChirp(volume: any())).wasCalled()     // Called with any volume
verify(bird.canChirp(volume: notNil())).wasCalled()  // Called with any non-nil volume
verify(bird.canChirp(volume: 10)).wasCalled()        // Called with volume = 10

Verify property invocations using their getter and setter methods.

verify(bird.getName()).wasCalled()
verify(bird.setName(any())).wasCalled()

It’s possible to verify that an invocation was called a specific number of times with a count matcher.

verify(bird.fly()).wasNeverCalled()            // n = 0
verify(bird.fly()).wasCalled(exactly(10))      // n = 10
verify(bird.fly()).wasCalled(atLeast(10))      // n ≥ 10
verify(bird.fly()).wasCalled(atMost(10))       // n ≤ 10
verify(bird.fly()).wasCalled(between(5...10))  // 5 ≤ n ≤ 10

Count matchers also support chaining and negation using logical operators.

verify(bird.fly()).wasCalled(not(exactly(10)))           // n ≠ 10
verify(bird.fly()).wasCalled(exactly(10).or(atMost(5)))  // n = 10 || n ≤ 5

An argument captor extracts received argument values which can be used in other parts of the test.

let bird = mock(Bird.self)
bird.name = "Ryan"

let nameCaptor = ArgumentCaptor<String>()
verify(bird.setName(nameCaptor.matcher)).wasCalled()

print(nameCaptor.value)  // Prints "Ryan"

Enforce the relative order of invocations with an inOrder verification block.

// Verify that `fly` was called before `chirp`
inOrder {
  verify(bird.fly()).wasCalled()
  verify(bird.chirp()).wasCalled()
}

Pass options to inOrder verification blocks for stricter checks with additional invariants.

inOrder(with: .noInvocationsAfter) {
  verify(bird.fly()).wasCalled()
  verify(bird.chirp()).wasCalled()
}

Mocked methods that are invoked asynchronously can be verified using an eventually block which returns an XCTestExpectation.

DispatchQueue.main.async {
  Tree(with: bird).shake()
}

let expectation =
  eventually {
    verify(bird.fly()).wasCalled()
    verify(bird.chirp()).wasCalled()
  }

wait(for: [expectation], timeout: 1.0)

Specify the expected return type to disambiguate overloaded methods.

protocol Bird {
  func getMessage<T>() -> T    // Overloaded generically
  func getMessage() -> String  // Overloaded explicitly
  func getMessage() -> Data
}

verify(bird.getMessage()).returning(String.self).wasCalled()

Argument matching allows you to stub or verify specific invocations of parameterized methods.

Value types that explicitly conform to Equatable work out of the box. Note that structs able to synthesize Equatable conformance must still explicitly declare conformance.

struct Fruit: Equatable {
  let size: Int
}

verify(bird.eat(Fruit(size: 42))).wasCalled()
verify(bird.setName("Ryan")).wasCalled()

Class instances can be safely compared by reference.

class Tree {
  init(with bird: Bird) {
    bird.home = self
  }
}

let tree = Tree(with: bird)
verify(bird.setHome(tree)).wasCalled()

Argument matchers allow for wildcard and custom matching of arguments that don’t conform to Equatable.

any()                    // Matches any value
any(of: 1, 2, 3)         // Matches any value in {1, 2, 3}
any(where: { $0 > 42 })  // Matches any number greater than 42
notNil()                 // Matches any non-nil value

For methods overloaded by parameter type (such as with generics), using a matcher may cause ambiguity for the compiler. You can help the compiler by specifying an explicit type in the matcher.

any(Int.self)
any(Int.self, of: 1, 2, 3)
any(Int.self, where: { $0 > 42 })
notNil(String?.self)

You can also match elements or keys within collection types.

any(containing: 1, 2, 3)  // Matches any collection with values {1, 2, 3}
any(keys: "a", "b", "c")  // Matches any dictionary with keys {"a", "b", "c"}
any(count: atMost(42))    // Matches any collection with at most 42 elements
notEmpty()                // Matches any non-empty collection

Mathematical operations on floating point numbers can cause loss of precision. Fuzzily match floating point arguments instead of using exact values to increase the robustness of tests.

around(10.0, tolerance: 0.01)

You can exclude unwanted or problematic sources from being mocked by adding a .mockingbird-ignore file. Mockingbird follows the same pattern format as .gitignore and scopes ignore files to their enclosing directory.

Supporting source files are used by the generator to resolve inherited types defined outside of your project. Although Mockingbird provides a preset “starter pack” for basic compatibility with common system frameworks, you will occasionally need to add your own definitions for third-party library types. Please see Supporting Source Files for more information.

Generate mocks for a set of targets in a project.

mockingbird generate

Configure a test target to use mocks.

mockingbird install

Remove Mockingbird from a test target.

mockingbird uninstall

Download and unpack a compatible asset bundle. Bundles will never overwrite existing files on disk.

mockingbird download <asset>

Mockingbird will first check if the environment variable $PROJECT_FILE_PATH was set (usually by an Xcode build context). It will then perform a shallow search of the current working directory for an .xcodeproj file. If multiple .xcodeproj files exist then you must explicitly provide a project file path.

By default Mockingbird will generate mocks into the $(SRCROOT)/MockingbirdMocks directory with the file name $(PRODUCT_MODULE_NAME)Mocks.generated.swift.

Mockingbird will recursively look for supporting source files in the $(SRCROOT)/MockingbirdSupport directory.

• CocoaPods tutorial + example project
• Carthage tutorial + example project
• Swift Package Manager tutorial + example project

• Slack channel
• Troubleshooting guide
• Mockingbird wiki