![logo][logo]

Check out [guides][link-guides-contents], or full [documentation][link-docs]

Table of contents

1. Overview
2. Current Version
3. Getting started:
   1. Integrating SwiftyMocky runtime into test target
   2. Installation SwiftyMocky CLI
   3. Generate mocks
4. Usage:
   1. Marking protocols to be mocked
   2. Stubbing return values for mock methods - Given
   3. Check invocations of methods, subscripts and properties - Verify
   4. Take action when a stubbed method is called - Perform
5. Documentation
   1. All supported Features
   2. Examples of usage
   3. Roadmap
   4. Authors
   5. License

Overview

SwiftyMocky is a strongly typed framework for Mockito-like unit testing experience. Library depends on Sourcery, that scans your source code and generates Mocks Swift code for you!

The idea of SwiftyMocky is to automatically mock Swift protocols and protocol compositions. The main features are:

• easy syntax, utilising full power of auto-complete, which makes writing test easier and faster
• we DO support generics
• mock implementations generation
• a way to specify what mock will return (given)
• possibility to specify different return values for different attributes
• record stubbed return values sequence
• verify, whether a method was called on mock or not
• check method invocations with specified attributes
• it works with real device

Important!!! Version 4.1.x

CLI was moved bask to the main (this) repo. CLI in this repository will be supported at least until version 5.0.0.

Version 4.0.x

Current version has several significant changes. It removes deprecated methods (which might be breaking) and deprecates having CLI in the new repository.

SwiftyPrototype was also extracted to separate library. There are no more compilation flags, so if you were relying on SwiftyMocky with -DMockyCustom, you will have to switch to SwiftyPrototype.

We consider current version as stable. We are moving toward using the new [Mockfile][link-guides-mockfile] but the previous configuration format would be still supported. Library works with Swift 4.1, 4.2, 5.0, 5.1.2 and Sourcery 1.0.x.

While it is technically possible to integrate SwiftyMocky on Linux targets, there is no Mock generation feature there yet. You can use SwiftyMokcy runtime via SwiftPM though, as long as your are fine with generating mocks on mac machine.

Migration from 3.2.0 and below

The migration is not required, you can keep using SwiftyMocky as you did before. The Legacy setup is described in guides section.

Still, we would encourage to try new CLI and share a feedback. We believe it will make using and setting up SwiftyMocky way easier. If you have an existing setup, install CLI as per this guide and try:

> swiftymocky migrate

Getting started

1. Integrating SwiftyMocky:

CocoaPods:

SwiftyMocky is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod "SwiftyMocky"

Use CLI tool from your project directory:

# To setup initial Mockfile
% ./Pods/SwiftyMocky/bin/swiftymocky setup
# To generate mocks
% ./Pods/SwiftyMocky/bin/swiftymocky generate

Carthage:

To install, add following to you Cartfile:

github "MakeAWishFoundation/SwiftyMocky"

Then execute carthage update

For Carthage, few additional steps are required ⚠️. For detailed install instructions, see full [documentation][link-docs-installation-carthage] or consult [Carthage documentation][carthage-adding-framework].

You need to install CLI to generate mocks - see installation

Swift Package Manager:

Add SwiftyMocky to you Package.swift dependencies:

dependencies: [
    .package(url: "https://github.com/MakeAWishFoundation/SwiftyMocky", from: "4.2.0"),
]

You need to install CLI to generate mocks - see installation

Note: Examples of SwiftyMocky integration as a tool for Unit tests, as well as a Prototyping framework, are here: https://github.com/MakeAWishFoundation/SM-Integration-Tests

2. Installing SwiftyMocky CLI:

Mint 🌱:

> brew install mint
> mint install MakeAWishFoundation/SwiftyMocky

Marathon 🏃:

> marathon install MakeAWishFoundation/SwiftyMocky

Make:

Clone from https://github.com/MakeAWishFoundation/SwiftyMockyCLI and run make in the root directory.

---

3. Generate mocks

Annotate your protocols that are going to be mocked, making them adopt AutoMockable protocol, or adding annotation comment above their definition in the source code.

Mocks are generated from your project root directory, based on configuration inside [Mockfile][link-guides-mockfile].

> path/to/swiftymocky setup     # if you don't have a Mockfile yet
> path/to/swiftymocky doctor    # validate your setup
> path/to/swiftymocky generate  # generate mocks

More informations about [CLI][link-guides-cli] and [mock generation][link-guides-cli-generate]

If you don't want to migrate to our CLI and prefer to use "raw" Sourcery, please refer [to this section in documentation][link-guides-cli-legacy].

Usage

1. Marking protocols to be mocked

Create 'dummy' protocol somewhere in your project, like: protocol AutoMockable { }

Adopt it by every protocol you want to actually mock.

protocol ToBeMocked: AutoMockable {
  // ...
}

Alternatively, mark protocols that are meant to be mocked with sourcery annotation as following:

//sourcery: AutoMockable
protocol ToBeMocked {
  // ...
}

Or use it to protocol compositions:

typealias ToBeMocked = OneProtocol & TwoProtocols & AutoMockable

Every protocol in source directories, having this annotation, will be added to Mock.generated.swift

2. Stubbing return values for mock methods - Given

All mocks has given method (accessible both as instance method or global function), with easy to use syntax, allowing to specify what should be return values for given methods (based on specified attributes).

![Generating mock][example-given]

All protocol methods are nicely put into Given, with matching signature. That allows to use auto-complete (just type .) to see all mocked protocol methods, and specify return value for them.

All method attributes are wrapped as Parameter enum, allowing to choose between any and value, giving great flexibility to mock behaviour. Please consider following:

Given(mock, .surname(for name: .value("Johnny"), willReturn: "Bravo"))
Given(mock, .surname(for name: .any, willReturn: "Kowalsky"))

print(mock.surname(for: "Johny"))   // Bravo
print(mock.surname(for: "Mathew"))  // Kowalsky
print(mock.surname(for: "Joanna"))  // Kowalsky

In verions 3.0 we introduced sequences and policies for better control of mock behvaiour.

Given(mock, .surname(for name: .any, willReturn: "Bravo", "Kowalsky", "Nguyen"))

print(mock.surname(for: "Johny"))   // Bravo
print(mock.surname(for: "Johny"))   // Kowalsky
print(mock.surname(for: "Johny"))   // Nguyen
print(mock.surname(for: "Johny"))   // and again Bravo
// ...

For more details please see full [documentation][link-docs].

3. Check invocations of methods, subscripts and properties - Verify

All mocks has verify method (accessible both as instance method or global function), with easy to use syntax, allowing to verify, whether a method was called on mock, and how many times. It also provides convenient way to specify, whether method attributes matters (and which ones).

![Generating mock][example-verify]

All protocol methods are nicely put into Verify, with matching signature. That allows to use auto-complete (just type .) to see all mocked protocol methods, and specify which one we want to verify.

All method attributes are wrapped as Parameter enum, allowing to choose between any, value and matching, giving great flexibility to tests. Please consider following:

// inject mock to sut. Every time sut saves user data, it should trigger storage storeUser method
sut.usersStorage = mockStorage
sut.saveUser(name: "Johny", surname: "Bravo")
sut.saveUser(name: "Johny", surname: "Cage")
sut.saveUser(name: "Jon", surname: "Snow")

// check if Jon Snow was stored at least one time
Verify(mockStorage, .storeUser(name: .value("Jon"), surname: .value("Snow")))
// storeUser method should be triggered 3 times in total, regardless of attributes values
Verify(mockStorage, 3, .storeUser(name: .any, surname: .any))
// storeUser method should be triggered 2 times with name Johny
Verify(mockStorage, 2, .storeUser(name: .value("Johny"), surname: .any))
// storeUser method should be triggered at least 2 times with name longer than 3
Verify(mockStorage, .moreOrEqual(to: 2), .storeUser(name: .matching({ $0.count > 3 }), surname: .any))

For Verify, you