Yet Another Swift Blog

Code Generating Swift Mocks with Sourcery

2021-03-09T00:00:00+00:00

Sometimes it is difficult or even impossible to verify the system under test (SUT) because it depends on other components that cannot be used in the test environment. It can be that they aren’t available (an internet connection), they will not return the results needed (user location), or because executing them would have undesirable side effects (firing an HTTP request) [1].

When you test something, you refer to it as the system under test (SUT).

In such a case it is convenient to replace real dependent-on components with their counterparts that we can fully control. This technique is called Mocking.

Mock objects mimic real objects for testing.

When it comes to implementing mock objects in Swift, what options do we have?

In good old Objective-C days we were able to generate mocks on the fly using OCMock. However, Swift has limited dynamic capabilities, meaning that we must implement mocks manually.

In this article, let’s learn how we can optimize this process by using a code generation tool Sourcery to create mock objects in Swift. We’ll come up with a production-ready setup that you can use in your projects right away.

Mock Objects Overview

The mock doesn’t behave like a real component. It simply provides the same API as the real one so that the SUT thinks it is the real one.

Mocking solves several important problems during unit testing [1]:

Isolates SUT from dependencies when they are unusable.
Provides a control point when the dependent-on component does not allow us to exercise the SUT under the necessary conditions.
Provides an observation point for the SUT’s indirect output that we need to verify. Indirect output means changes that cannot be observed via SUT public API. E.g., when SUT logs a message.
Speeds up a test suite execution by replacing slow components with their test counterparts.

Mocking comes not without its downsides:

We are testing the SUT in a different configuration from the one used in production.
Tests know too much about how the SUT should be structured or behave. That is, the tests will only pass if the SUT is implemented in a particular way, making such tests overspecified and fragile.

Understanding Sourcery

Sourcery is a tool that generates boilerplate Swift code using templates. It is powered by Apple’s SourceKit and allows us to do meta-programming. Among other things, it can generate test mocks.

Here is why we should be using Sourcery instead of writing mocks by hand:

Reduces development effort on writing and maintaining test mocks.
Reduces the cost of changing our code.
Unifies the way we write mocks.

Integrating Sourcery to Xcode Project

There are four ways of integrating Sourcery: binary form, CocoaPods, Homebrew, or Mint.

I do not recommend using Homebrew or Mint because there is no way you can enforce that every team member, as well as CI/CD slave, are using the same Sourcery version.

I also do not recommend CocoaPods integration. The reason is that you’ll often need to customize Sourcery templates, and you’ll have to store custom templates outside the CocoaPods directory anyway.

Instead, we are going to add Sourcery as a binary. Download the latest Sourcery release on GitHub. At the time I am writing this article it is version 1.3.2. Create the tools directory at your Xcode project root and move the Sourcery folder there.

The folder Sourcery-1.3.2 includes the binary at ./bin/sourcery and several default Stencil templates at ./Templates/. The other files are not relevant to us.

Next, create the configuration file sourcery.yml and move it to the tools/ folder root:

sources:
  - ../AutoMockable
templates:
  - ./Templates/AutoMockable.stencil
output:
  ../AutoMockableTests/Generated

The configuration file tells Sourcery:

To look for source code files in the AutoMockable/ directory.
Use the AutoMockable.stencil template that generates test mocks.
Store the generated files at AutoMockableTests/Generated.

Note that I named the Xcode project AutoMockable, and the test target is called AutoMockableTests.

Next, create a script that will be invoked during Xcode build phase. The script runs Sourcery with a configuration file that we just defined. Create the file sourcery.sh at tools/ root with the next content:

SOURCERY="Sourcery-1.3.2"
"${PROJECT_DIR}/tools/${SOURCERY}/bin/sourcery" --config "${PROJECT_DIR}/tools/sourcery.yml" --verbose

An unfortunate feature of the default AutoMockable.stencil template is that it dumps all mock objects into a single file. That file becomes unmanageable quickly. To enable per file code generation, we have to add the following annotations to the template:

// sourcery:file:{{ type.name }}+AutoMockable
...
// sourcery:end

Sourcery will generate the template code and then write the parts between the annotations sourcery:file and sourcery:end to corresponding files named <TypeName>Mock+AutoMockable.generated.swift. The final template can be on GitHub. I did two customizations to the original template: (1) enabled per file code generation, and (2) added project-specific import statements.

Since we are going to use the custom template, we’ll have to maintain it independently from the ones bundled with Sourcery. For this reason let’s store the custom template at /tools/Templates/AutoMockable.stencil.

At this point Xcode project directories structure is supposed to look like:

.
|-- AutoMockable
    |-- ...
|-- AutoMockable.xcodeproj
    |-- ...
|-- AutoMockableTests
|   |-- AutoMockableTests.swift
|   `-- Info.plist
`-- tools
    |-- Sourcery-1.3.2
    |   |-- CHANGELOG.md
    |   |-- LICENSE
    |   |-- README.md
    |   |-- Resources
    |   |-- Sourcery.docset
    |   |-- Templates
    |   |-- bin
    |   `-- lib
    |-- Templates
    |   `-- AutoMockable.stencil
    |-- sourcery.sh
    `-- sourcery.yml

Note that the directory Sourcery-1.3.2 is unmodified. Therefore, we can easily upgrade the tool without losing the configuration file, the build script, and the custom template.

Lastly, to enabled Sourcery code generation for our project, call sourcery.sh as Xcode build phase. Go to Xcode, select the test target, add a new Run Script Phase before the Compile Sources phase:

sh "${PROJECT_DIR}/tools/sourcery.sh"

Congratulations on completing all the preparations! Now we are ready to generate some mocks.

Code Generating a Mock

There are two ways of enabling code generation for a protocol. By annotating the protocol with sourcery: AutoMockable (1):

//sourcery: AutoMockable
protocol Cancellable {
    func cancel()
}

And by conforming to the AutoMockable protocol (2):

protocol AutoMockable {}

protocol Cancellable: AutoMockable {
    func cancel()
}

Note that if you are using the second option, the marker protocol AutoMockable must be declared somewhere in your project.

In this article, we will stick with the first option. As an example, we are going to generate mocks for the following protocols:

//sourcery: AutoMockable
protocol HTTPClient {
    func execute(
        request: URLRequest,
        completion: @escaping (Result<Data, Error>) -> Void
    )
}

//sourcery: AutoMockable
protocol Cancellable {
    func cancel()
}

//sourcery: AutoMockable
protocol ErrorPresenter {
    func showError(_ error: Error)
}

Declare the above protocols in your project. Don’t forget to add the sourcery annotation like in the example above.
Run tests via the CMD + U shortcut.
Open Finder and navigate to the AutoMockableTests folder.
Drag the folder to Xcode, and link the files to the AutoMockableTests target.

You must see the new directory Generated with the following structure:

|-- AutoMockableTests
|   |-- AutoMockableTests.swift
|   |-- Generated
|   |   |-- Cancellable+AutoMockable.generated.swift
|   |   |-- ErrorPresenter+AutoMockable.generated.swift
|   |   `-- HTTPClient+AutoMockable.generated.swift
|   `-- Info.plist

Ideally, generated files must be linked to the Xcode project automatically. In theory, Sourcery supports this via the link key. However, in practice, this feature does not behave as expected. Internally Sourcery uses XcodeProj to link the generated files to the current project. I recommend writing a custom script that calls XcodeProj to overcome this.

Here is how a generated mock looks like:

// Generated using Sourcery 1.3.2 — https://github.com/krzysztofzablocki/Sourcery
// DO NOT EDIT
// swiftlint:disable all

import UIKit
@testable import AutoMockable

class HTTPClientMock: HTTPClient {

    //MARK: - execute

    var executeRequestCompletionCallsCount = 0
    var executeRequestCompletionCalled: Bool {
        return executeRequestCompletionCallsCount > 0
    }
    var executeRequestCompletionReceivedArguments: (request: URLRequest, completion: (Result<Data, Error>) -> Void)?
    var executeRequestCompletionReceivedInvocations: [(request: URLRequest, completion: (Result<Data, Error>) -> Void)] = []
    var executeRequestCompletionClosure: ((URLRequest, @escaping (Result<Data, Error>) -> Void) -> Void)?

    func execute(request: URLRequest, completion: @escaping (Result<Data, Error>) -> Void) {
        executeRequestCompletionCallsCount += 1
        executeRequestCompletionReceivedArguments = (request: request, completion: completion)
        executeRequestCompletionReceivedInvocations.append((request: request, completion: completion))
        executeRequestCompletionClosure?(request, completion)
    }

}

Using Mocks in Unit Tests

Now let’s use the generated mock object in a real-world scenario. Given an API service that uses HTTPClient to execute HTTP requests:

struct CurrencyDTO: Codable, Equatable {
    let currencyCode: String
    let country: String
    let currencyName: String
    let countryCode: String
}

final class CurrenciesAPIService {
    private let httpClient: HTTPClient

    init(httpClient: HTTPClient) {
        self.httpClient = httpClient
    }

    func allCurrencies(completion: @escaping (Result<[CurrencyDTO], Error>) -> Void) {
        httpClient.execute(request: .allCurrencies()) { result in
            completion(
                result.flatMap { data in Result { try JSONDecoder().decode([CurrencyDTO].self, from: data) }}
            )
        }
    }
}

extension URLRequest {
    static func allCurrencies() -> URLRequest {
        let rawPath = "https://gist.githubusercontent.com/V8tr/b8d3e63f7d987d3298cc83c9362f1c6e/raw/ad3f8f697835ec2dbd9a36779f84ffed9911c8aa/currencies.json"
        guard let url = URL(string: rawPath) else { fatalError() }
        return URLRequest(url: url)
    }
}

Let’s test CurrenciesAPIService by replacing HTTPClient with a mock. This is rational because HTTPClient depends on other components that cannot be used in the test environment. Namely, we cannot control internet connectivity and backend services.

The next test verifies that CurrenciesAPIService correctly handles malformed data in response:

import Foundation
import XCTest
@testable import AutoMockable

class CurrenciesAPIServiceTests: XCTestCase {

    let httpClient = HTTPClientMock()
    lazy var sut = CurrenciesAPIService(httpClient: httpClient)

    func test_allCurrencies_withMalformedData_returnsError() throws {
        httpClient.executeRequestCompletionClosure = { _, completion in
            completion(.success(Data()))
        }

        var result: Result<[CurrencyDTO], Error>?

        sut.allCurrencies { result = $0 }

        XCTAssertThrowsError(try result?.get())
    }
}

We use httpClient.executeRequestCompletionClosure to set custom response from HTTPClient.
The mock does not execute network requests, hence the method allCurrencies() is synchronous.
XCTAssertThrowsError() verifies that Result<T> contains an error.

The next test verifies that CurrenciesAPIService correctly parses a successful response that contains valid data:

class CurrenciesAPIServiceTests: XCTestCase {
    ...

    func test_allCurrencies_withResponseSuccess_returnsValidData() throws {
        let expected = CurrencyDTO(
            currencyCode: "A",
            country: "B",
            currencyName: "C",
            countryCode: "D"
        )
        let data = try JSONEncoder().encode([expected])
        httpClient.executeRequestCompletionClosure = { _, completion in
            completion(.success(data))
        }

        var result: Result<[CurrencyDTO], Error>?

        sut.allCurrencies { result = $0 }

        XCTAssertEqual(try result?.get(), [expected])
    }
}

You’ll find more examples of unit tests in the final project.

Source Code

You can find the complete project on GitHub. It is published under the “Unlicense”, which allows you to do whatever you want with it.

Summary

Use mocks when SUT dependencies cannot be controlled in the test environment.
Mock-based tests are often overspecified and fragile. If possible, prefer using real dependencies instead of mocks.
Use Sourcery to generate mocks in Swift instead of writing them manually. This allows you to avoid boilerplate code, reduces room for mistakes, and enforces a similar code style.
Configure Sourcery to use per file code generation instead of placing all mocks into a single file which is the default.

Custom Popup in SwiftUI

2021-02-23T00:00:00+00:00

Popup is a kind of modal that appears in front of app content to provide critical information or ask for a decision.

SwiftUI provides many APIs to show alerts, popovers, action sheets, modal sheets. However, none of these allow us to present a custom popup or a snackbar. In this article, let’s build a reusable SwiftUI component for presenting custom popups and snackbars.

You can find the complete project on GitHub

It’s convenient to design the popup as a ViewModifier that can be applied to any view:

struct Popup<T: View>: ViewModifier {
    let popup: T
    let isPresented: Bool

    // 1.
    init(isPresented: Bool, @ViewBuilder content: () -> T) {
        self.isPresented = isPresented
        popup = content()
    }

    // 2.
    func body(content: Content) -> some View {
        content
            .overlay(popupContent())
    }

    // 3.
    @ViewBuilder private func popupContent() -> some View {
        GeometryReader { geometry in
            if isPresented {
                popup
                    .frame(width: geometry.size.width, height: geometry.size.height)
            }
        }
    }
}

Here’s what’s going on in the code above:

The popup is initialized with two arguments. The isPresented flag means whether the popup is currently visible onscreen. The content closure produces the popup sheet. It is marked with the @ViewBuilder attribute that enables us to use the SwiftUI declarative DSL.
In the body() method we add the popup as an overlay to the parent view.
GeometryReader eagerly takes all available space provided by its parent view. The popup within GeometryReader is shown or hidden based on the isPresented property. We specify frame() to correctly size and position the popup within the geometry reader.

You can learn more about the @ViewBuilder attribute in Function Builders in Swift and SwiftUI.

Let’s check the result on a SwiftUI preview:

struct Popup1_Previews: PreviewProvider {
    static var previews: some View {
        Color.clear
            .modifier(Popup(isPresented: true,
                            content: { Color.yellow.frame(width: 100, height: 100) }))
            .previewDevice("iPod touch")
    }
}

By default, the popup is centered within GeometryReader bounds. To support custom alignment we need to pass an extra alignment argument to the popup frame() view modifier:

struct Popup<T: View>: ViewModifier {
    ...
    let alignment: Alignment // (*)

    init(isPresented: Bool, alignment: Alignment, @ViewBuilder content: () -> T) { // (*)
        self.isPresented = isPresented
        self.alignment = alignment // (*)
        popup = content()
    }
    ...
    @ViewBuilder private func popupContent() -> some View {
        GeometryReader { geometry in
            if isPresented {
                popup
                    .frame(width: geometry.size.width, height: geometry.size.height, alignment: alignment) // (*)
            }
        }
    }
    ...
}

We receive the alignment argument in the Popup initializer and pass it to the popup frame. The changes are marked with the (*) symbol.

Let’s update the preview to showcase different popup alignments:

struct Popup2_Previews: PreviewProvider {
    static var previews: some View {
        Color.clear
            .modifier(Popup(isPresented: true,
                            alignment: .topTrailing,
                            content: { Color.orange.frame(width: 100, height: 100) }))
            ...
            .modifier(Popup(isPresented: true,
                            alignment: .bottomLeading,
                            content: { Color.blue.frame(width: 100, height: 100) }))
            .previewDevice("iPod touch")
    }
}

To create an animated transition, we add the animation() and transition() view modifiers to the popup:

struct Popup<T: View>: ViewModifier {
    ...
    @ViewBuilder private func popupContent() -> some View {
        GeometryReader { geometry in
            if isPresented {
                popup
                    .animation(.spring()) // 1.
                    .transition(.offset(x: 0, y: geometry.belowScreenEdge)) // 2.
                    .frame(width: geometry.size.width, height: geometry.size.height, alignment: alignment)
            }
        }
    }
}

// 3.
private extension GeometryProxy {
    var belowScreenEdge: CGFloat {
        UIScreen.main.bounds.height - frame(in: .global).minY
    }
}

Here the highlights from the code above:

When we set the animation(_:) modifier on a view, SwiftUI animates any changes to the animatable properties of the view. In our case, we are going to animate view position.
The transition(_:) modifier specifies how a view appears and disappears. It has no effect on its own and must be associated with an animation. In our case, we set the offset transition that moves the popup from the bottom screen edge.
Calculate the popup position below the screen edge.

To see the animation in action, we add a button to the preview that toggles the popup presentation:

struct Popup3_Previews: PreviewProvider {

    static var previews: some View {
        Preview()
            .previewDevice("iPod touch")
    }

    // Helper view that shows a popup
    struct Preview: View {
        @State var isPresented = false

        var body: some View {
            ZStack {
                Color.clear
                VStack {
                    Button("Toggle", action: { isPresented.toggle() })
                    Spacer()
                }
            }
            .modifier(Popup(isPresented: isPresented,
                            alignment: .center,
                            content: { Color.yellow.frame(width: 100, height: 100) }))
        }
    }
}

Now the popup appears and disappears with animation:

Adding Direction

It’s common to have a popup that slides from the top of the screen. However, the current Popup animation is fixed in a way that the popup always appears from the bottom edge. Let’s add versatility to our component and support two different animation directions:

extension Popup {
    enum Direction {
        case top, bottom

        func offset(popupFrame: CGRect) -> CGFloat {
            switch self {
            case .top:
                let aboveScreenEdge = -popupFrame.maxY
                return aboveScreenEdge
            case .bottom:
                let belowScreenEdge = UIScreen.main.bounds.height - popupFrame.minY
                return belowScreenEdge
            }
        }
    }
}

Here we calculate popup offset based on the animation direction:

struct Popup<T: View>: ViewModifier {
    ...
    let direction: Direction // (*)

    init(isPresented: Bool, alignment: Alignment, direction: Direction, @ViewBuilder content: () -> T) { // (*)
        self.isPresented = isPresented
        self.alignment = alignment
        self.direction = direction // (*)
        popup = content()
    }
    ...
    @ViewBuilder private func popupContent() -> some View {
        GeometryReader { geometry in
            if isPresented {
                popup
                    .animation(.spring())
                    .transition(.offset(x: 0, y: direction.offset(popupFrame: geometry.frame(in: .global)))) // (*)
                    .frame(width: geometry.size.width, height: geometry.size.height, alignment: alignment)
            }
        }
    }
}

This code adds a new direction property and calculates the transition offset based on the direction and the popup frame. The changes are marked with the (*) symbol.

Then add a conveniece extension to SwiftUI View that applies the Popup view modifier:

extension View {
    func popup<T: View>(
        isPresented: Bool,
        alignment: Alignment = .center,
        direction: Popup<T>.Direction = .bottom,
        @ViewBuilder content: () -> T
    ) -> some View {
        return modifier(Popup(isPresented: isPresented, alignment: alignment, direction: direction, content: content))
    }
}

The final demo shows several practical Popup use cases, namely a loading indicator and a message snackbar:

struct ContentView: View {
    @State private var isLoaderPresented = false
    @State private var isTopSnackbarPresented = false

    var body: some View {
        TabView {
            leftTab
            rightTab
        }
        .popup(isPresented: isTopSnackbarPresented, alignment: .top, direction: .top, content: Snackbar.init)
        .popup(isPresented: isLoaderPresented, alignment: .center, content: Loader.init)
    }

    private var leftTab: some View { ... }

    private var rightTab: some View { ... }
}

struct ContentView_Previews: PreviewProvider {
    static var previews: some View {
        ContentView()
    }
}

The next demo shows a loading indicator appearing from the bottom:

And here is a snackbar message appearing from the top:

Source Code

You can find the complete project on GitHub. It is published under the “Unlicense”, which allows you to do whatever you want with it.

Callable Objects and callAsFunction() in Swift

2021-01-25T00:00:00+00:00

In Swift, any object that has the callAsFunction method can be called like a function. Such objects are named callable.

The function-call syntax forwards arguments to the corresponding callAsFunction method [SE-0253]:

struct WannabeFunction {
    func callAsFunction() {
        print("Hi there")
    }
}

let f = WannabeFunction()
f() // Hi there

There are three ways of invoking callAsFunction() on f:

let f = WannabeFunction()

f() // Callable sugar
f.callAsFunction() // Member function sugar
WannabeFunction.callAsFunction(f)() // No sugar

The callAsFunction() method obeys all Swift function rules. It can be declared in an extension:

struct WannabeFunction {}

extension WannabeFunction {
    func callAsFunction() { ... }
}

And overloaded:

struct WannabeFunction {
    func callAsFunction() { print(#function) }

    // Argument label overloading
    func callAsFunction(x: Int) { print(#function, x) }
    func callAsFunction(y: Int) { print(#function, y) }

    // Argument type overloading
    func callAsFunction(x: String) { print(#function, x) }

    // Generic type constraint overloading
    func callAsFunction<T>(value: T) where T: Numeric { print(#function, value) }
    func callAsFunction<T>(value: T) where T: StringProtocol { print(#function, value) }
}

let f = WannabeFunction()
f() // callAsFunction()
f(x: 1) // callAsFunction(x:) 1
f(y: 2) // callAsFunction(y:) 2
f(value: 3) // callAsFunction(value:) 3
f(value: "str") // callAsFunction(value:) str
f([1, 2, 3]) // ❌ Error: Type of expression is ambiguous without more context

And passed around:

let foo = f.callAsFunction(y:)
foo(10) // callAsFunction(y:) 10

Does callAsFunction() bring to Swift anything more than yet another syntactic sugar? Let’s find out by checking the use cases below.

Types representing functions

Types that represent functions, such as mathematical operations or machine learning computations, typically contain a single primary method, which can be conveniently sugared using callable syntax.

A prominent example is TensorFlow. The Layer protocol, which represents a neural network layer, contains the callAsFunction(_:) method requirement.

Another example is reducer from the Redux architecture. A motivating example can be found in the Composable Architecture.

Parsers, calculators, shell commands fall into this category.

Passing generic functions

Referencing and passing generic functions would not have been possible without callable syntax. A compiler error pops up if we try to reference a generic function:

func bar<T>(_ x: T) { print(x) }
let f = bar<Int>() // ❌ Error: Cannot explicitly specialize a generic function

However, we can achieve this using callAsFunction():

struct Bar<T> {
    var f: (T) -> Void
    func callAsFunction(_ x: T) { f(x) }
}

let f = Bar<Int> { print($0) }
f(1)

Although f is factually a callable object, it can be considered a generic function at a point of use.

Function identity

Two functions are considered equal if for each input they produce the same output. Given that some categories are infinite, the only possible way to achieve this is by wrapping functions into a nominal type.

The next use case shows how we can add Identifiable, Hashable, and Equatable conformance to a function by wrapping it into a nominal type. The method callAsFuntion() allows us to invoke the wrapper using a function-like syntax:

struct Function<Input, Output>: Identifiable {
    let id: UUID
    let f: (Input) -> Output

    init(id: UUID = UUID(), f: @escaping (Input) -> Output) {
        self.id = id
        self.f = f
    }

    func callAsFunction(_ input: Input) -> Output {
        f(input)
    }
}

extension Function: Equatable {
    static func == (lhs: Function<Input, Output>, rhs: Function<Input, Output>) -> Bool {
        lhs.id == rhs.id
    }
}

extension Function: Hashable {
    func hash(into hasher: inout Hasher) {
        hasher.combine(id)
    }
}

Consider Swift key paths as an alternative to the above technique as they already conform to Hashable and Equatable.

Bound functions

Partial application and bound closures can be modeled using callable syntax.

Partial application is a functional programming technique that means binding some arguments to a function without fully evaluating it.

Here is a curried add() function which is then partially applied:

func add(_ x: Int) -> (_ y: Int) -> Int {
    { y in return x + y }
}

let addTwo = add(2)
print(addTwo(3)) // 5

I am touching on the subject in Functions in Swift.

The same technique can be modeled using callable syntax:

// 1.
struct Sum {
    var x: Int
    func callAsFunction(_ y: Int) -> Int { x + y }
}

// 2.
let addTwo = Sum(x: 2)
print(addTwo(3)) // 5

Here are the key highlights:

Declare type Sum, which reprents the arithmetic addition operation.
The argument 2 is stored in the struct instance, which essentially bounds 2 to the method callAsFunction().

Delegation

The auto-weak delegate pattern, which I’ve learned from @olegdreyman, uses callAsFunction() to improve readability at a call site:

class Delegate<Input, Output> {
    init() {}

    private var block: ((Input) -> Output?)?
    func delegate<T: AnyObject>(on target: T, block: ((T, Input) -> Output)?) {
        self.block = { [weak target] input in
            guard let target = target else { return nil }
            return block?(target, input)
        }
    }

    func call(_ input: Input) -> Output? {
        return block?(input)
    }

    func callAsFunction(_ input: Input) -> Output? {
        return call(input)
    }
}

Say, there is a DataLoader which fetches data and notifies when it’s done:

class DataLoader {
    let onLoad = Delegate<(), Void>()
    func loadData() {
        onLoad(())
    }
}

Then, in the onLoad callback, we receive weakified self, and there is no need to write [weak self] every time:

class ViewController: UIViewController {
    let loader = DataLoader()

    override func viewDidLoad() {
        super.viewDidLoad()
        loader.loadData()
        loader.onLoad.delegate(on: self) { (self, _) in
            self.setupLoadedUI()
        }
    }

    func setupLoadedUI() {}
}

See the original Oleg’s post here for more details on the pattern.

Wrapping Up

Apart from the subjective improvements that callable syntactic sugar brings into the Swift language, callAsFunction() has two real benefits which are not achievable by any other means. These are:

passing generic function, and
functions identity.

I also believe that the types-representing-functions, bound functions, and auto-weak delegation pattern will find their application in many modern codebases.

Effective Auto Layout Programmatically in Swift

2021-01-11T00:00:00+00:00

Interface Builder (IB) has been in Xcode going back as far as anyone could recall [1]. It initiated the disputes about developing user interface in code vs IB which continue till nowadays. However, with the release of SwiftUI, Apple has made programmatic layout the mainstream approach.

Why hadn’t this happen before? The folklore tells us that constructing UI in code is slower compared to Interface Builder. In this article, I am going to show not only that the opposite is true, but also that programmatic layout is more scalable, maintainable, and future-proof when using the five techniques of Effective Programmatic Auto Layout.

This is not an introductory article. To familiarize yourself with the topic, I recommend Apple’s Auto Layout Guide.

Auto Layout Programmatically vs Storyboard

Let’s look at some facts about using Interface Builder:

Interface Builder has a low entry barrier.
Changes are visual.
To get a full picture of a UI component, you need to inspect both an Interface Builder file and a source code file. Having two sources of truth for a UI component decreases readability and leaves more room for mistakes.
Too many ways of configuring a component via IB: Runtime Attributes, multiple tabs with different settings, size-class-specific overrides, etc. This makes it difficult to spot which settings are overridden.
Resolving merge conflicts in storyboards and xibs is error-prone since we have to deal with poorly readable XML. What is more, Interface Builder files can break silently while fixing merge conflicts. Say, you won’t notice a missing IBAction connection until you trigger that action.
In complex scenarios, when you need more control over the layout (e.g., screen rotation, variations per screen size or platform, animations, dynamic fonts), you’ll need to resort to programmatic constraints or even manual frame calculation.

Then let’s put some facts about programmatic layout:

Code is a single source of truth of a UI component.
View setup is explicit. It is clear which properties are configured and how.
Merge conflicts are easier to resolve since we are dealing with code rather than XML.
Extensible for complex scenarios: screen rotation, animations, dynamic fonts, etc.
The consistent coding style of constructing UI programmatically is maintained across a mixed UIKit and SwiftUI project. With the gradual adoption of SwiftUI, this becomes more and more relevant.
Less noise in the codebase: no segues, string identifiers, tricky initialization from storyboard and xib, numerous helper extensions attempting to hide some part of that noise.

By looking at these facts we can conclude that the folklore was wrong. Layout in code is faster and more future-proof compared to storyboards and xibs. It is seemingly fast and easy to throw some views together on a canvas. However, in the long run, all of the disadvantages of Interface Builder add up, making it a sub-optimal choice.

To make the programmatic layout even more effective in terms of speed of writing and maintainability, we are going to utilize the five techniques of Effective Programmatic Auto Layout:

Auto Layout DSL.
Focused, independent components.
Callbacks as a communication pattern.
Stack views over auto layout constraints.
SwiftUI previews.

Auto Layout DSL

After building UI programmatically for a while, you’ll notice that some compositions are repeated over time. To avoid boilerplate code, I recommend designing a µDSL that provides a thin abstraction layer on top of the excellent layout anchors API.

I consider popular libraries like SnapKit and Cartography a sub-optimal choice. A valuable piece of advice I learned from Ben Sandofsky is to use libraries only for problems outside your domain.

For example, here is the µDSL I’ve been using in my projects. Consider it informative rather than prescriptive. I’ll briefly highlight the key points so that we can see the benefits of using it.

LayoutAnchor represents a single constraint, which can be either constant (e.g., fixed-width or height), or relative to another constraint (e.g., leading or trailing):

import UIKit

enum LayoutAnchor {
    case constant(attribute: NSLayoutConstraint.Attribute,
                  relation: NSLayoutConstraint.Relation,
                  constant: CGFloat)

    case relative(attribute: NSLayoutConstraint.Attribute,
                  relation: NSLayoutConstraint.Relation,
                  relatedTo: NSLayoutConstraint.Attribute,
                  multiplier: CGFloat,
                  constant: CGFloat)
}

The factory methods simplify anchors definition:

extension LayoutAnchor {
    ...
    static let leading = relative(attribute: .leading, relatedBy: .equal, relatedTo: .leading)
    static let trailing = relative(attribute: .trailing, relatedBy: .equal, relatedTo: .trailing)

    static let width = constant(attribute: .width, relatedBy: .equal)
    static let height = constant(attribute: .height, relatedBy: .equal)
    ...
}

UIView has a convenience method which applies a set of LayoutAnchors:

extension UIView {
    func addSubview(_ subview: UIView, anchors: [LayoutAnchor]) {
        translatesAutoresizingMaskIntoConstraints = false
        subview.translatesAutoresizingMaskIntoConstraints = false
        addSubview(subview)
        subview.activate(anchors: anchors, relativeTo: self)
    }
    
    func activate(anchors: [LayoutAnchor], relativeTo: UIView? = nil) {
        let constraints = anchors.map { NSLayoutConstraint(from: self, relativeTo: relativeTo, anchor: $0) }
        NSLayoutConstraint.activate(constraints)
    }
}

extension NSLayoutConstraint {
    convenience init(from: UIView, to item: UIView?, anchor: LayoutAnchor) {
        ...
    }
}

Here is how we can put together a couple of views using our µDSL:

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()

        let yellow = UIView()
        yellow.backgroundColor = .yellow
        view.addSubview(yellow, anchors: [.leading(0), .trailing(0), .bottom(0), .top(0)])

        let redBox = UIView()
        redBox.backgroundColor = .red
        view.addSubview(redBox, anchors: [.centerX(0), .centerY(0), .width(100), .height(100)])
    }
}

Compare against the standard anchors API:

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()

        let yellow = UIView()
        yellow.backgroundColor = .yellow
        yellow.translatesAutoresizingMaskIntoConstraints = false
        view.addSubview(yellow)
        NSLayoutConstraint.activate([
            yellow.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            yellow.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            yellow.topAnchor.constraint(equalTo: view.topAnchor),
            yellow.bottomAnchor.constraint(equalTo: view.bottomAnchor),
        ])

        let redBox = UIView()
        redBox.backgroundColor = .red
        redBox.translatesAutoresizingMaskIntoConstraints = false
        view.addSubview(redBox)
        NSLayoutConstraint.activate([
            redBox.widthAnchor.constraint(equalToConstant: 100),
            redBox.heightAnchor.constraint(equalToConstant: 100),
            redBox.centerXAnchor.constraint(equalTo: view.centerXAnchor),
            redBox.centerYAnchor.constraint(equalTo: view.centerYAnchor),
        ])
    }
}

If we count the viewDidLoad() methods, it’s 11 vs 24 lines of code.

Focused, Independent Components

Interface Builder makes it difficult to reuse components. To render a view in the canvas, you’ll need to mark it with the @IBDesignable attribute and support an alternative lifecycle path via prepareForInterfaceBuilder(). And even if you manage to do this, the storyboard will load slowly and the view will appear on the canvas only from time to time (this is how it’s been since Xcode 6, and I don’t believe this will ever be fixed).

Conversely, no extra efforts are needed to compose programmatically-written components. Here are the rules of thumb when designing components with reusability in mind:

Strive for focused, independent views.
Pass the minimal subset of data the view needs for rendering. Prefer primitive values over view models, business model objects, you name it.
Do not couple views with protocols or base classes since premature abstraction will likely damage your design. The reason for this is that UI components change at a different speed and for different reasons.

Callbacks as a Communication Pattern

Use callbacks as a primary communication pattern between views. By doing this, we keep construction and configuration code together, and also reduce target-action and delegation boilerplate.

Since iOS 14, we can do this via system APIs. For example, here is how you can attach a callback to UITextField text changes:

let textField = UITextField()
textField.addAction(
    UIAction { action in
        let textField = action.sender as! UITextField
        print("Text changed \(textField.text)")
    },
    for: .editingChanged
)

Or instantiate a UIButton with a callback:

let button = UIButton(primaryAction: UIAction { action in
    print("Tapped!")
})

Since most of us don’t have the privilege of supporting iOS 14+, it’s trivial to implement custom callback-based controls. Here is an example for UIButton:

class CallbackButton: UIButton {
    var onAction: ((CallbackButton) -> Void)?

    init(onAction: ((CallbackButton) -> Void)? = nil) {
        self.onAction = onAction
        super.init(frame: .zero)
        setup()
    }

    required init?(coder: NSCoder) {
        super.init(coder: coder)
        setup()
    }

    private func setup() {
        addTarget(self, action: #selector(onTap), for: .primaryActionTriggered)
    }

    @objc private func onTap() {
        onAction?(self)
    }
}

The usage is similar to the system API:

let button = CallbackButton { btn in
    print("Tapped!")
}

It feels almost like SwiftUI, right?

Here I described SwiftUI View communication patterns.

Stack Views Over Auto Layout Constraints

Stack views provide a layer of abstraction on top of the auto layout, allowing us to compose complex layouts from primitive container views. Everything UIStackView does is create constraints for us.

If you check Apple’s View Layout overview, the first sentence says:

Use stack views to lay out the views of your interface automatically. Use Auto Layout when you require precise placement of your views.

Even Apple’s Auto Layout Guide introduces stacks before the constraints themselves.

In other words, if we can get away with stack views only, then go for it.

From my experience, stacks are a solution to well over 50% of the problems that Auto Layout was intended to solve. The stack-based layout is faster to build, more concise, readable, and flexible, compared to constraints. What’s more, stacks have several other benefits:

Trivial to support different content size categories. Just flip the axis of the content if it does not fit.
Trivial to add scrolling. This is very handy for forms, short lists, and collections, without introducing the overhead of UITableView or UICollectionView.
Multiple ways of aligning and distributing arranged subviews, which are not trivial to achieve via constraints.
Easy to hide and show arranged subviews from view hierarchy without breaking constraints.

SwiftUI Previews

When building layout in code, it’s often difficult to get to the state where you can verify that the changes that you are making have the results you expect. The goal of SwiftUI Previews is to minimize the amount of time you spend building, and running, and configuring your views to verify the changes that you are making [2].

Although the preview provider supports only SwiftUI.View, we can seamlessly make UIView and UIViewController available for the preview by conforming to UIView(Controller)Representable [3]:

UIKit with SwiftUI goes into more details on the subject.

import SwiftUI

@available(iOS 13, *)
struct UIViewControllerPreview<ViewController: UIViewController>: UIViewControllerRepresentable {
    let viewController: ViewController

    init(_ builder: @escaping () -> ViewController) {
        viewController = builder()
    }

    func makeUIViewController(context: Context) -> ViewController { viewController }

    func updateUIViewController(_ uiViewController: ViewController, context: Context) {}
}

With the above in place, we are now able to make any instance of UIViewController conform to UIViewControllerRepresentable, making it possible to preview our view controller from the previous example:

struct ViewControllerPreviews: PreviewProvider {
    static var previews: some View {
        UIViewControllerPreview {
            let storyboard = UIStoryboard(name: "Main", bundle: nil)
            return storyboard.instantiateViewController(identifier: "ViewController") as! ViewController
        }
        .previewDevice("iPhone SE (2nd generation)")
    }
}

Summary

Let’s summarize the five techniques of Effective Programmatic Auto Layout:

Utilize Auto Layout DSL to cut boilerplate. The example from this article is here.
Design components with reuse in mind: (a) require a minimal subset of data, (b) focus on doing one thing, (c) not couple to other components via inheritance.
Communicate between components via callbacks.
Use stack views to simplify layout and make it fore flexible.
Use SwiftUI previews for a faster feedback loop.

SwiftUI View Lifecycle

2020-11-18T00:00:00+00:00

Each view undergoes a series of events from its birth to its death, which is referred to as a lifecycle. Understanding it is essential when building apps in SwiftUI. In this article, we will explore the three phases of the SwiftUI view lifecycle.

Before we talk about lifecycle, we need to agree on what a view is.

Understanding SwiftUI Views

To describe what’s displayed onscreen, we create a graph of views.

View is a definition of a piece of UI. [1].

SwiftUI uses this definition to create an appropriate rendering.

View is a function of a state [2].

To update UI, we don’t mutate the view graph directly. Instead, we modify the state, and a new view graph is calculated from the state. Then SwiftUI performs rendering to reflect the changes.

The identity and lifetime of SwiftUI views are separate from the lifetime of structs that define them [1].

SwiftUI.ViewGraph manages a rendering and non-rendering hierarchy of views. From what I’ve learned from reflecting the SwiftUI binary, their corresponding names are DisplayList and ViewList:

The non-rendering hierarchy is a definition of what needs to be displayed onscreen. SwiftUI creates it using bodys of the view structs that we provide. On every UI update, SwiftUI traverses the previous and new snapshots of the non-rendering hierarchy to calculate changes. It relies on the private AttributeGraph framework to represent view attributes and perform diffing.
SwiftUI uses the rendering hierarchy to produce an actual drawing. Views from this hierarchy have their own identities, and their lifetime corresponds to how long they are displayed onscreen.

The type of view body encodes the whole view subgraph.

If you inspect the type of your app’s root view body, you’ll notice that it contains the entire view hierarchy:

struct ContentView: View {
    var body: some View {
        Text("Hello, world!")
            .background(Color.yellow)
            .font(.title)
            .dump()
    }
}

extension View {
    func dump() -> Self {
        print(Mirror(reflecting: self))
        return self
    }
}

This will print:

Mirror for ModifiedContent<ModifiedContent<Text, _BackgroundModifier<Color>>, _EnvironmentKeyWritingModifier<Optional<Font>>>

This includes not only visible views, but also all variations of views that can appear onscreen:

struct ContentView_: View {
    var body: some View {
        Group {
            if true {
                Color.yellow
            } else {
                Text("Impossible")
            }
        }
        .dump()
    }
}

This will print:

Mirror for Group<_ConditionalContent<Color, Text>>

Although Text can never become visible, it’s still present in _ConditionalContent<Color, Text>.

According to Thinking in SwiftUI, the benefit of encoding the entire view hierarchy instead of the just currently visible one is that it allows for more efficient diffing.

Views should be lightweight and cheap [1].

The consequence of encoding the entire view hierarchy into the body’s type is that large parts of the view graph are constructed upfront. Furthermore, according to Data Essentials in SwiftUI, views are copied very frequently. Therefore, we must keep two rules in mind when designing SwiftUI views:

Make initialization cheap.
Make body a pure function, free of side effects. Simply create your view and return, no dispatching extra work.

SwiftUI View Lifecycle

Lifecycle is the series of events that happen from the creation of a SwiftUI view to its destruction.

Each view in SwiftUI has a lifecycle that we can observe and manipulate during its three main phases. The three phases are Appearing, Updating, and Disappearing. They are summarized in the below diagram:

Apart from the three lifecycle phases, there are two rendering phases: Layout and Commit.

In the Layout phase, SwiftUI initializes the non-rendering view hierarchy, computes frames, connects views to state, calculates diffs to be committed onscreen.

The layout phase must be pure. Any side effects will result in undefined behavior:

struct ContentView: View {
    @State var count = 0
    
    var body: some View {
        count += 1 // ❌ side effect
        ...
    }
}

The above code generates a runtime warning:

Modifying state during view update, this will cause undefined behavior.

In the Commit phase, SwiftUI updates the rendering view hierarchy, commits all changes onscreen, and destroys all views which are not needed anymore.

Appearing

Appearing means inserting a view into a view graph. In this phase, a view is initialized, subscribed to the state, and rendered for the first time.

At the time of initialization, a view is not connected to the state. This makes view construction cheap since the whole view hierarchy is built upfront.
After the initialization, and before the body is computed, a view gets connected to the state.
View body is called for the first time.
Update view graph and render changes.
The onAppear() method is called top-down: from parent to child view.

Updating

Updating is performed in response to an external event or state mutation.

External event means the Combine publisher which is a single abstraction to represent external changes to SwiftUI [2].

A user action causes state change or SwiftUI detects data emitted by a publisher observed via View.onReceive().
A view, which owns a mutated state or which received an external event, and all of its children, is compared against its previous snapshot. At this point, we can provide our custom definition of view equality by conforming our view to the Equatable protocol and wrapping it into EquatableView.
SwiftUI invalidates the views that have changed.
Update view graph and render invalidated views. All the updates flow down through the view hierarchy.

Note that only views that are connected to the state can provide custom equality implementation. Views not connected to the state are always re-rendered.

An important takeaway is that pushing the state down the view hierarchy reduces the number of views to be invalidated and re-rendered when the state changes.

Disappearing

Disappearing means removing a view from the hierarchy.

The onDisappear() method is called after a view has been removed from the hierarchy. Similarly to onAppear(), onDisappear() is called top-down: from parent to child view.

Unit Testing Asynchronous Code in Swift

2020-10-25T00:00:00+00:00

If you are practicing unit testing, sooner or later you’ll run across testing async code. Writing such tests can be a challenge for the next reasons:

False positives and negatives. Async code ends after the unit test does, causing misleading test results.
Flakiness. Async code executes with different speed on different machines, bringing a subtle time dependency into a test suite. A common symptom of flakiness is that on your development machine all tests are passing, however, when run on a CI/CD slave, a couple of random tests are failing.
Untrustworthy. Because of the flakiness, we stop trusting our test suite. If several random tests from the test suite fail, we do not tell ourselves that these tests have detected a bug. Instead, we re-run them individually. And if they pass, we pretend that everything is all right with the test suite.
Error-prone. We all know how hard it is to get async code right. Same goes for testing it. If you run across a multithreading issue in your tests, you know that you are on for a wild ride.

The solution is to use next four patterns which allow us to test async code in a safe and reliable way:

Mocking
Testing before & after
Expectations
Busy assertion

Throughout this article, we’ll study these four patterns: what they are, when to use, and what you can get from them.

System Under Test

When you test something, you refer to it as the system under test (SUT).

MusicService will be our system under test. It is a networking service which searches music via iTunes API:

struct MusicService {
    
    func search(_ term: String, completion: @escaping (Result<[Track], Error>) -> Void) {
        URLSession.shared.dataTask(with: .search(term: term)) { data, response, error in
            DispatchQueue.main.async {
                completion(self.parse(data: data, error: error))
            }
        }.resume()
    }
    
    func parse(data: Data?, error: Error?) -> Result<[Track], Error> {
        if let data = data {
            return Result { try JSONDecoder().decode(SearchMediaResponse.self, from: data).results }
        } else {
            return .failure(error ?? URLError(.badServerResponse))
        }
    }
}

It creates a request via:

extension URLRequest {
    static func search(term: String) -> URLRequest {
        var components = URLComponents(string: "https://itunes.apple.com/search")
        components?.queryItems = [
            .init(name: "media", value: "music"),
            .init(name: "entity", value: "song"),
            .init(name: "term", value: "\(term)")
        ]
        
        return URLRequest(url: components!.url!)
    }
}

MusicService uses URLSession to fire HTTP requests, and returns an array of Tracks via the completion callback:

struct SearchMediaResponse: Codable {
    let results: [Track]
}

struct Track: Codable, Equatable {
    let trackName: String?
    let artistName: String?
}

When building iOS apps, it is typical to design networking layer using services similar to MusicService. Therefore, testing it is a common and relevant task.

After discussing the system under test, let’s move to the first pattern.

Mocking in Swift

The idea of the Mocking pattern is to use special objects called mocks.

Mock object mimics real objects for testing.

To use mock objects, we must:

Extract asynchronous work into a new type.
Delegate asynchronous work to the new type.
Replace real dependency with a mock during testing.

Passing dependencies to an object is called dependency injection. I’ve written an in-depth article about Dependency Injection in Swift, which is important to understand when practicing mocking.

Let’s highlight the parts of MusicService which perform asynchronous work:

struct MusicService {
    func search(_ term: String, completion: @escaping (Result<[Track], Error>) -> Void) {
        URLSession.shared.dataTask(with: .search(term: term)) { data, response, error in
            DispatchQueue.main.async {
                ...
            }
        }.resume()
    }
    ...
}

The responsibility of the above code is to execute HTTP requests. We extract it into a new type called HTTPClient, and use it from MusicService:

protocol HTTPClient {
    func execute(request: URLRequest, completion: @escaping (Result<Data, Error>) -> Void)
}

struct MusicService {
    let httpClient: HTTPClient
    
    func search(_ term: String, completion: @escaping (Result<[Track], Error>) -> Void) {
        httpClient.execute(request: .search(term: term)) { result in
            completion(self.parse(result))
        }
    }
    
    private func parse(_ result: Result<Data, Error>) -> Result<[Track], Error> { ... }
}

HTTPClient will have two implementations. The production one contains all the code from MusicService which was responsible for firing HTTP requests:

class RealHTTPClient: HTTPClient {
    func execute(request: URLRequest, completion: @escaping (Result<Data, Error>) -> Void) {
        URLSession.shared.dataTask(with: request) { data, response, error in
            DispatchQueue.main.async {
                if let data = data {
                    completion(.success(data))
                } else {
                    completion(.failure(error!))
                }
            }
        }.resume()
    }
}

The test implementation remembers the last parameter passed to execute(), and allows us to pass an arbitrary result to the completion callback, mimicking network response.

class MockHTTPClient: HTTPClient {
    var inputRequest: URLRequest?
    var executeCalled = false
    var result: Result<Data, Error>?
    
    func execute(request: URLRequest, completion: @escaping (Result<Data, Error>) -> Void) {
        executeCalled = true
        inputRequest = request
        result.map(completion)
    }
}

Now we are ready to test MusicService using a mock object. In the next test we verify that MusicService fires a correct HTTP request:

func testSearch() {
    // 1.
    let httpClient = MockHTTPClient()
    let sut = MusicService(httpClient: httpClient)
    
    // 2.
    sut.search("A") { _ in }
    
    // 3.
    XCTAssertTrue(httpClient.executeCalled)
    // 4.
    XCTAssertEqual(httpClient.inputRequest, .search(term: "A"))
}

Here is what we are doing:

Initialize the system under test with a mock implementation of HTTPClient.
Run the method search(), passing it an arbitrary query.
Verify that the method execute() has been invoked on the mock.
Verify that the correct HTTP request has been passed to the mock.

Next, we verify how MusicService handles API response. In order to do this, we mimic a successful response using MockHTTPClient:

func testSearchWithSuccessResponse() throws {
    // 1.
    let expectedTracks = [Track(trackName: "A", artistName: "B")]
    let response = try JSONEncoder().encode(SearchMediaResponse(results: expectedTracks))

    // 2.
    let httpClient = MockHTTPClient()
    httpClient.result = .success(response)

    let sut = MusicService(httpClient: httpClient)

    var result: Result<[Track], Error>?

    // 3.
    sut.search("A") { result = $0 }

    // 4.
    XCTAssertEqual(result?.value, expectedTracks)
}

Prepare test data.
Initialize a mock object, and pass it predefined response data. The mock will return that data in the execute() callback.
The method search() is synchronous since we mocked HTTPClient. Therefore, the completion callback is invoked instantly.
Verify that the correct result has been received.

We can also verify how MusicService handles failed response:

func testSearchWithFailureResponse() throws {
    // 1.
    let httpClient = MockHTTPClient()
    httpClient.result = .failure(DummyError())

    let sut = MusicService(httpClient: httpClient)

    var result: Result<[Track], Error>?

    // 2.
    sut.search("A") { result = $0 }

    // 4.
    XCTAssertTrue(result?.error is DummyError)
}

struct DummyError: Error {}

Provide an error response to the mock.
Same as before, the method search() is synchronous, and the completion callback is invoked immediately.
Verify that search() passed the correct error to the callback.

Testing Before & After

The idea of the Before & After pattern is to break verification of an asynchronous code into two tests. The first test verifies that the system under test is in correct state before async code has started. The second test validates the state of the SUT as if async code has already finished.

Let’s return to our initial MusicService implementation. That is, the one without HTTPClient:

struct MusicService {
 
    func search(_ term: String, completion: @escaping (Result<[Track], Error>) -> Void) {
        URLSession.shared.dataTask(with: .search(term: term)) { ... }.resume()
    }
 
    private func parse(data: Data?, error: Error?) -> Result<[Track], Error> { ... }
}

In the test before, validate that MusicService fires correct HTTP request:

func testSearchBefore() {
    let sut = MusicService()
    
    // 1.
    sut.search("A") { _ in }
    
    // 2.
    let lastRequest = URLSession.shared.tasks.last?.currentRequest
    XCTAssertEqual(lastRequest?.url, URLRequest.search(term: "A").url)
}

Unlike the example with Mocking, the search() method fires a real HTTP request, and invokes the completion callback as soon as it receives a response. That it, asynchronously. For this reason we are we do not handle it.
To validate that MusicService has fired a correct HTTP request, we take the last URLRequest from URLSession, and compare its url with the expected one.

An attentive reader might have noticed that URLSession does not expose a list of its tasks synchronously. Indeed, we’ve been using a helper method for this:

extension URLSession {
    var tasks: [URLSessionTask] {
        var tasks: [URLSessionTask] = []
        let group = DispatchGroup()
        group.enter()
        getAllTasks {
            tasks = $0
            group.leave()
        }
        group.wait()
        return tasks
    }
}

In the test after, pretend that MusicService has received a response, and test the method parse(). The tricky thing is that this method is private. What we are going to do is trade encapsulation for testability, and make parse() internal:

struct MusicService {
    ...
    func parse(data: Data?, error: Error?) -> Result<[Track], Error> { ... }
}

Now nothing prevents us from testing the method parse() directly:

func testSearchAfterWithSuccess() throws {
    let expectedTracks = [Track(trackName: "A", artistName: "B")]
    let response = try JSONEncoder().encode(SearchMediaResponse(results: expectedTracks))
    
    let sut = MusicService()
    
    let result = sut.parse(data: response, error: nil)
    
    XCTAssertEqual(result.value, expectedTracks)
}

We can also validate the negative case:

func testSearchAfterWithFailure() {
    let sut = MusicServiceWithoutDependency()
    
    let result = sut.parse(data: nil, error: DummyError())
    
    XCTAssertTrue(result.error is DummyError)
}

struct DummyError: Error {}

Expectations

Up to this point, we were able to verify asynchronous code with synchronous tests, avoiding the complexity of writing multithreading code in tests altogether.

What if we cannot use Mocking since it is too risky or too long to refactor an SUT? What if we also cannot use Before & After since there are no noticeable changes in the SUT that we can verify in the test before? In this case, asynchronous code in tests is unavoidable. The next two patterns lend themselves to writing multithreading tests effectively.

The Expectations pattern is based on the usage of XCTestExpectation.

Expectation is an expected outcome in an asynchronous test.

The pattern can be summarized into four steps:

Create an instance of XCTestExpectation.
Fulfill the expectation when async operation has finished.
Wait for the expectation to be fulfilled.
Assert the expected result.

We are going to test the version of MusicService with HTTPClient. Let’s recall the implementation:

protocol HTTPClient {
    func execute(request: URLRequest, completion: @escaping (Result<Data, Error>) -> Void)
}
 
struct MusicService {
    let httpClient: HTTPClient
    
    func search(_ term: String, completion: @escaping (Result<[Track], Error>) -> Void) {
        httpClient.execute(request: .search(term: term)) { result in
            completion(self.parse(result))
        }
    }
    
    private func parse(_ result: Result<Data, Error>) -> Result<[Track], Error> { ... }
}

The primary difference is that HTTPClient won’t be mocked. As you already might have guessed, we are going to write an integration test:

func testSearch() {
    // 1.
    let didReceiveResponse = expectation(description: #function)
    
    // 2.
    let sut = MusicService(httpClient: RealHTTPClient())
    
    // 3.
    var result: Result<[Track], Error>?
    
    // 4.
    sut.search("ANYTHING") {
        result = $0
        didReceiveResponse.fulfill()
    }
    
    // 5.
    wait(for: [didReceiveResponse], timeout: 5)
    
    // 6.
    XCTAssertNotNil(result?.value)
}

Create an instance of XCTestExpectation.
Initialize SUT with RealHTTPClient. That is, the one used in production.
Declare a variable which will hold a result of the search() method once it completes.
In the search() callback, fulfill the expectation, and store the received result into the variable.
Wait for up to 5 seconds for search() to fulfill.
Assert that a successful request has been received.

More Use Cases for Expectations

XCTestExpectation is a versatile tool and can be applied in a number of scenarios.

Inverted Expectations allows us to verify that something did not happen:

func testInvertedExpectation() {
    // 1.
    let exp = expectation(description: #function)
    exp.isInverted = true
    
    // 2.
    sut.maybeComplete {
        exp.fulfill()
    }
    
    // 3.
    wait(for: [exp], timeout: 0.1)
}

Create an inverted expectation. The test will fail if the inverted expectation is fulfilled.
Call a method that may conditionally invoke a callback.
Verify that the callback is not invoked.

Notification Expectation is fulfilled when an expected Notification is received:

func testExpectationForNotification() {
    let exp = XCTNSNotificationExpectation(name: .init("MyNotification"), object: nil)
    
    ...
    sut.postNotification()
    
    wait(for: [exp], timeout: 1)
}

Assert for over fulfillment triggers an assertion if the number of calls to fulfill() exceeds expectedFulfillmentCount:

func testExpectationFulfillmentCount() {
    let exp = expectation(description: #function)
    exp.expectedFulfillmentCount = 3
    exp.assertForOverFulfill = true
    
    ...
    sut.doSomethingThreeTimes()
    
    wait(for: [exp], timeout: 1)
}

There are even more use cases which we won’t cover in details:

Busy Assertion

The Busy Assertion pattern makes expectations on values which are updated asynchronously. The idea is to create an infinite loop which re-evaluates a condition until it holds or the timeout is reached.

The method expectToEventually() creates a busy assertion loop:

extension XCTest {
    
    func expectToEventually(
        _ isFulfilled: @autoclosure () -> Bool,
        timeout: TimeInterval,
        message: String = "",
        file: StaticString = #filePath,
        line: UInt = #line
    ) {
        func wait() { RunLoop.current.run(until: Date(timeIntervalSinceNow: 0.01)) }
        
        let timeout = Date(timeIntervalSinceNow: timeout)
        func isTimeout() -> Bool { Date() >= timeout }

        repeat {
            if isFulfilled() { return }
            wait()
        } while !isTimeout()
        
        XCTFail(message, file: file, line: line)
    }
}

The important highlight is that wait() is non-blocking. It releases RunLoop for 0.01 seconds to serve other attached input sources. After 0.01 seconds of waiting, another iteration of the busy assertion loop spins. If the isFulfilled condition does not hold for the duration of timeout, the loop ends, and XCTFail is called to signal test failure.

Here is how we can re-write the expectations-based test using busy assertion:

func testSearchBusyAssert() {
    let sut = MusicService(httpClient: RealHTTPClient())
    
    var result: Result<[Track], Error>?
    
    sut.search("ANYTHING") { result = $0 }
    
    expectToEventually(result?.value != nil, timeout: 5)
}

Notice that the number of lines reduced from 16 to 9. The reason for this is that Busy Assertion needs only one step instead of four steps required by expectations.

Summary

Let’s summarize what we just discussed, and lay out when to use each pattern.

Mocking: use whenever possible. It has several strong benefits:

Improves design of existing code since we follow good practices of object-oriented design when extracting multithreading dependencies.
Eliminates asynchronous code in tests.
Verifies edge cases. In our example, we were able to verify how MusicService handles response error.

Before & after: use with legacy code since the pattern requires minimal or no refactoring. In such situations, Mocking can be unsafe since it may lead to bugs in production due to significant refactoring.

Busy assertion: use in the most scenarios when need to test async code directly. This pattern is simpler than expectations and usually can replace them.

Expectations: use in special cases when need to test async code directly. In some non-trivial scenarios, busy assertion cannot replace expectations. Additionally, expectations come with a number of flavours.

Source Code

Source code with all examples from this article can be found here. It is published under the “Unlicense”, which allows you to do whatever you want with it.

Working with an Internet Connection on iOS with Swift: Best Practices

2020-08-10T00:00:00+00:00

Networking is an integral part of most iOS applications. A common network-related task is Internet connectivity detection. Typically, it appears in three scenarios:

Checking connectivity before firing an HTTP request.
Disabling or enabling app features based on network connectivity status.
Attaching constraints to network operations, e.g., disabling large file download via cellular.

The most popular answers on how to detect network connectivity status on iOS suggest using SCNetworkReachability. In this article, let’s discuss why this solution is less than optimal, and lay out best practices of working with the Internet connection recommended by Apple.

Checking Connectivity Before Firing a Request

In its documentation, Apple says that we should not check Internet connection before firing an HTTP request. From Networking Overview:

The SCNetworkReachability API is not intended for use as a preflight mechanism for determining network connectivity. […]

We can hear similar pieces of advice in multiple WWDC sessions. From Advances in Networking, Part 1, at 50:00:

Pre-flight check is a very bad indicator of where your flow will end up on.

From Advances in Networking, Part 2, at 56:00

Pre-flight checks have inherited race conditions.

From Networking Best Practices, at 33:00:

Don’t check the Reachability object to determine whether something is available. It can be deceptive in some cases.

The reasons for these statements are next:

Knowing in advance how Wi-Fi will perform until you try is impossible [Advances in Networking, Part 2, 57:00].
Internet connection pre-flight checks have inherent race conditions, give false positives and false negatives, time-of-check to time-of-use problem [Apple dev forum thread].
Reachability will report unreachable if the networking hardware is powered down. Attempting to make a connection will power up the networking hardware. If you are relying on Reachability (or NWPathMonitor – addition mine) saying something might be reachable, you are relying on something else (a background process) powering up the networking hardware [AFNetworking GitHub thread].

The solution is to use Adaptable Connectivity APIs. By opting in to this feature, we tell URLSession that it should wait for a connection to the server instead of failing a URLSessionTask because of a lack of connectivity.

All it takes to enable Adaptable Connectivity is to set waitsForConnectivity flag on URLSessionConfiguration:

let config = URLSessionConfiguration.default
config.waitsForConnectivity = true
config.timeoutIntervalForResource = 300

let session = URLSession(configuration: config)

let url = URL(string: "https://www.example.com/")!

session.dataTask(with: url) { data, response, error in
    // ...
}

Now we are all set. If a device is online, HTTP requests will fire immediately. Otherwise, URLSession will wait until the device is connected to the Internet, and then fire a request.

By default, URLSession waits for the Internet connection for up to 7 days. If this is not the behavior you want, you could set timeoutIntervalForResource to a relevant value.

Enabling or Disabling App Features Based on Internet Connection

Same as with pre-flight checks, enabling or disabling app features based on an Internet connection is discouraged. The reason for this is that we cannot reliably check connectivity status via Reachability or NWPathMonitor:

The Wi-Fi signal could disappear after your app checks reachability, but before it connects [Networking Overview].
Different hosts may be reachable over different interfaces. You cannot trust a reachability check for one host to be valid for a different host [Networking Overview].
Different IP addresses for the same host may be reachable over different interfaces [Networking Overview].
[…] You can no longer assume that Internet connectivity, once established, will remain established, or that bandwidth will never increase or decrease […] [Apple’s Networking Overview].
Wi-Fi Assist can switch you automatically to cellular if you have a poor Wi-Fi connection so that you can continue using the Internet.
Your device might think it’s on Wi-Fi, but when it tries to use it, it turns out not working [Advances in Networking, Part 2, 57:15].

As highlighted in Advances in Networking, instead of disabling app features and letting users hope for the best, we should indicate on the UI that the current connectivity status is insufficient, without blocking any actions. For example, Safari provides a refresh button on a web page which failed to load due to the lack of connectivity since automatic refresh is unreliable:

Let’s lay out the idiomatic approach to working with an insufficient Internet connection.

Given that you opted into Adaptable Connectivity, you can now handle connectivity updates via URLSessionDelegate. The following methods are called once per URLSessionTask, and are a good place to indicate the status on the UI, e.g., by presenting an offline mode or a cellular-only mode:

class NetworkingHandler: NSObject, URLSessionDelegate {
    func urlSession(_ session: URLSession, taskIsWaitingForConnectivity task: URLSessionTask) {
        // Indicate network status, e.g., offline mode
    }
    
    func urlSession(_ session: URLSession, task: URLSessionTask, willBeginDelayedRequest: URLRequest, completionHandler: (URLSession.DelayedRequestDisposition, URLRequest?) -> Void) {
        // Indicate network status, e.g., back to online
    }
}

let session = URLSession(configuration: config, delegate: NetworkingHandler(), delegateQueue: .main)

In case you haven’t opted into Adaptable Connectivity, you should use NWPathMonitor to receive network status updates. First, create a monitor instance. Make sure that you store a strong reference to it, e.g., by having it as a property in AppDelegate:

import Network

let monitor = NWPathMonitor()
monitor.start(queue: .global()) // Deliver updates on the background queue

Then use pathUpdateHandler to handle status changes:

monitor.pathUpdateHandler = { path in
    if path.status == .satisfied {
        // Indicate network status, e.g., back to online
    } else {
        // Indicate network status, e.g., offline mode
    }
}

The benefits of using NWPathMonitor over SCNetworkReachability is that it offers higher-level APIs, and provides more information about the network connection. We no longer need to create a network socket, and listen for its changes – all using low-level C APIs and pointers.

Once we receive a network status update – either via URLSessionDelegate or NWPathMonitor – we can diagnose the current connection via NWPathMonitor:

if monitor.currentPath.status == .satisfied {
    // Connected
} else {
    // No connection
}

if monitor.currentPath.isExpensive { 
    // Using an expensive interface, such as Cellular or a Personal Hotspot
}

if monitor.currentPath.isConstrained {
    // Using Low Data Mode
}

There is still a chance that a connection will drop after it has been established. In such a case, you will receive an NSURLErrorNetworkConnectionLost error in URLSessionTask’s completion handler. This is a good place to diagnose connectivity status using NWPathMonitor to handle the error appropriately.

Attaching Constraints to Network Operations

Another common scenario is to constrain network operations based on Internet connection status. E.g., disable video autoplay, or automatic downloads, or high quality streaming via cellular.

Networking Overview suggests that we should not use Reachability to decide whether a network operation needs to be constrained or not:

Checking the reachability flag does not guarantee that your traffic will never be sent over a cellular connection.

According to Advances in Networking, Part 1, the preferred way of minimizing data usage is by adopting Low Data Mode. Its purpose is to restrict background network use and save cellular and Wi-Fi usage. Since Low Data Mode is a system-wide preference, it gives control into users’ hands.

We can enable Low Data Mode on a URLSession level:

var config = URLSessionConfiguration.default
config.allowsConstrainedNetworkAccess = false

let session = URLSession(configuration: config)

let url = URL(string: "https://www.example.com/")!

session.dataTask(with: url) { data, response, error in
    // ...
}

Or on a per-request basis:

let url = URL(string: "https://www.example.com/")!
var request = URLRequest(url: url)
request.allowsConstrainedNetworkAccess = false

URLSession.shared.dataTask(with: request) { data, response, error in
    // ...
}

In this case, when there are no available networks without constraints, HTTP requests will fail with URLError whose networkUnavailableReason is set to .constrained.

Here are some examples of how built-in iOS apps adapt Low Data Mode [1]:

App Store: Video autoplay, automatic updates, and automatic downloads are turned off.
Music: Automatic downloads and high-quality streaming are turned off.
Podcasts: The frequency of feed updates is limited, and episodes are downloaded only on Wi-Fi.
News: Article prefetching is turned off.
iCloud: Updates are paused, and automatic backups and iCloud Photos updates are turned off.
FaceTime: Video bitrate is optimized for lower bandwidth.

If Low Data Mode is not what you need, you can use the following properties to make decisions about what to do on a given network:

allowsExpensiveNetworkAccess
allowsCellularAccess

The preferred one is allowsExpensiveNetworkAccess since it is more future-proof than allowsCellularAccess.

Summary

Let’s summarize the list of best practices that we’ve discussed:

Avoid pre-flight checks. Instead, opt into Adaptable Connectivity APIs.
Do not enable or disable app features based on an Internet connection. Instead, indicate connectivity status on UI, and diagnose network errors.
Do not second-guess your users by prevent connections from being sent over a cellular network. Instead, adopt Low Data Mode.

Infinite List Scroll with SwiftUI and Combine

2020-06-15T00:00:00+00:00

Infinite scrolling is a UX pattern which loads content continuously when users scroll down the screen. An example of an infinite list that you probably already know is Twitter or Instagram feed. In this article, let’s implement an endless list of GitHub repositories using the SwiftUI and Combine frameworks, and the MVVM iOS app architecture pattern.

Firing Paginated HTTP Request

We begin by adding a network request that fetches repositories using GitHub REST API:

In Modern Networking in Swift you can learn how to implement a networking layer from scratch.

enum GithubAPI {
    static let pageSize = 10
    
    static func searchRepos(query: String, page: Int) -> AnyPublisher<[Repository], Error> {
        let url = URL(string: "https://api.github.com/search/repositories?q=\(query)&sort=stars&per_page=\(Self.pageSize)&page=\(page)")!
        return URLSession.shared
            .dataTaskPublisher(for: url) // 1.
            .tryMap { try JSONDecoder().decode(GithubSearchResult<Repository>.self, from: $0.data).items } // 2.
            .receive(on: DispatchQueue.main) // 3.
            .eraseToAnyPublisher()
    }
}

Here are the takeaways:

Create a publisher that wraps a URL session data task.
Decode the response as GithubSearchResult. This is an intermediate type created for the purpose of parsing JSON.
Receive response on the main thread.

The models are implemented as follows:

struct GithubSearchResult<T: Codable>: Codable {
    let items: [T]
}

struct Repository: Codable, Identifiable, Equatable {
    let id: Int
    let name: String
    let description: String?
    let stargazers_count: Int
}

Implementing Static List

After fetching GitHub repositories from the network, we display them in a static list:

struct RepositoriesList: View {
    // 1.
    let repos: [Repository]
    let isLoading: Bool
    let onScrolledAtBottom: () -> Void
    
    // 2.
    var body: some View {
        List {
            reposList
            if isLoading {
                loadingIndicator
            }
        }
    }
    
    private var reposList: some View { ... }
    
    private var loadingIndicator: some View { ... }
}

The list accepts an array of repositories to show, a callback that notifies when the list is scrolled to the bottom, and an isLoading flag, that indicates whether a loading animation needs to be shown.
The body contains a list and a loading indicator below it.

Let’s take a closer look at reposList:

struct RepositoriesList: View {
    ...
    private var reposList: some View {
        ForEach(repos) { repo in
            // 1.
            RepositoryRow(repo: repo).onAppear {
                // 2.
                if self.repos.last == repo {
                    self.onScrolledAtBottom()
                }
            }
        }
    }
    ...
}

RepositoryRow represents a list entry.
We call onScrolledAtBottom() when the last repository appears on the screen.

Here is how RepositoryRow is implemented:

struct RepositoryRow: View {
    let repo: Repository
    
    var body: some View {
        VStack {
            Text(repo.name).font(.title)
            Text("⭐️ \(repo.stargazers_count)")
            repo.description.map(Text.init)?.font(.body)
        }
        .frame(idealWidth: .infinity, maxWidth: .infinity, alignment: .center)
    }
}

Implementing the View Model

We’ll use the MVVM pattern to organize the components of our infinite list. The view model will load data from the network, and compose a State object. The view, in, its turn, will bind to the state updates.

Here is an in-depth overview of the modern state of the MVVM pattern.

// 1.
class RepositoriesViewModel: ObservableObject {
    @Published private(set) var state = State()
    private var subscriptions = Set<AnyCancellable>()
    
    // 2.
    func fetchNextPageIfPossible() {
        guard state.canLoadNextPage else { return }
        
        GithubAPI.searchRepos(query: "swift", page: state.page)
            .sink(receiveCompletion: onReceive,
                  receiveValue: onReceive)
            .store(in: &subscriptions)
    }
    
    ...

    // 3.
    struct State {
        var repos: [Repository] = []
        var page: Int = 1
        var canLoadNextPage = true
    }
}

To support data binding, the view model must conform to the ObservableObject protocol, and provide at least one @Published property. Whenever such a variable is updated, SwiftUI re-renders the bound view automatically.
The fetchNextPageIfPossible() method searches GitHub repositories using the ‘swift’ query. It checks that the next page is available before requesting it.
The state contains all the information to render a view.

The two missing pieces are the overloaded onReceive() methods which handle the API response:

class RepositoriesViewModel: ObservableObject {
    ...
    private func onReceive(_ completion: Subscribers.Completion<Error>) {
        switch completion {
        case .finished:
            break
        case .failure:
            state.canLoadNextPage = false
        }
    }
    
    private func onReceive(_ batch: [Repository]) {
        state.repos += batch
        state.page += 1
        state.canLoadNextPage = batch.count == GithubAPI.pageSize
    }
    ...
}

Implementing Infinite Scroll

Finally, let’s connect the view model to the static list. We’ll use the container view pattern, and this is where the pagination logic will sit. The purpose of the container view is to provide the data and pagination behavior to RepositoriesList:

struct RepositoriesListContainer: View {
    @ObservedObject var viewModel: RepositoriesViewModel
    
    var body: some View {
        RepositoriesList(
            repos: viewModel.state.repos,
            isLoading: viewModel.state.canLoadNextPage,
            onScrolledAtBottom: viewModel.fetchNextPageIfPossible
        )
        .onAppear(perform: viewModel.fetchNextPageIfPossible)
    }
}

The final result looks next:

Source Code

You can find the final project here. It is published under the “Unlicense”, which allows you to do whatever you want with it.

Swift Pointers Overview: Unsafe, Buffer, Raw and Managed Pointers

2020-06-10T00:00:00+00:00

Pointers are one of the most complex features in the Swift language. First, the concept of pointers is hard by itself. Second, using them incorrectly could lead to memory leaks and undefined behavior. Third, Swift exposes pointers through a set of thirteen types, which may seem overwhelming. The goal of this article is to put Swift pointers in a systematic way: what they are, when to use, and what you can get from them.

What is Memory

Memory is a long list of bytes. Every byte has a number, called memory address, and can hold a content. Using memory addresses, we can store things in memory and then read them back.

The amount of memory a value occupies depends on its data type and the Swift compiler implementation. For example, here is how a memory address space can look like if we store a Bool value:

It is up to the programmer to interpret the content of the memory since it is not associated with any concrete type. In our example, to get back the value from the memory, we need to read out the byte 0, then resolve the type to Bool.

Here you can learn about advanced iOS memory management and objects life cycle.

Pointers Overview

A pointer is a variable that stores the memory address of an object.

Swift pointers can be broken down into the following types:

A buffer type provides a collection interface to a group of elements stored contiguously in memory so that you can treat them like an array. Conversely, non-buffer type points to a single element.
A mutable type allows us to mutate the memory referenced by that pointer. Conversely, an immutable type provides read-only access to the referenced memory.
A raw type contains uninitialized and untyped data. Raw pointers must be bound to a certain type and value before we can use them. They can also be reinterpreted to several different types. Conversely, typed pointers have a generic parameter, which is the type of the value being pointed to.
An unsafe type does not have some of Swift’s safety features, such as bounds check, automatic memory management. It is possible to violate memory, access unallocated memory, or interpret memory as a wrong type by means of unsafe pointers.
A managed type has automatic memory management. Conversely, an unmanaged type makes you partially responsible for the object’s lifecycle.

Swift Unsafe Pointers

For most of the time, when we need to use a pointer, we are interested in the unsafe kind. In Swift, unsafe pointers are exposed via nine types:

Immutable	Mutable
`UnsafePointer<T>`	`UnsafeMutablePointer<T>`
`UnsafeBufferPointer<T>`	`UnsafeMutableBufferPointer<T>`
`UnsafeRawPointer`	`UnsafeMutableRawBufferPointer`
`UnsafeRawBufferPointer`	`UnsafeRawBufferPointer`

There is also AutoreleasingUnsafeMutablePointer<T> that is used only for Objective-C interoperability. It corresponds to an Objective-C pointer T __autoreleasing *, where T is an Objective-C pointer type [1].

Unsafe pointers have an associated type Pointee which represents the type of data being pointed at. Typed unsafe pointers are generic over their Pointee type. Raw unsafe pointers have their Pointee fixed to UInt8, representing a byte of memory.

Under the hood, every unsafe pointer implements the _Pointer protocol. Its goal is to provide an abstraction on top of Builtin.RawPointer, which is essentially raw memory (void* in C).

Typically, we use unsafe pointers in the following scenarios:

Interacting with C APIs, e.g., Core Foundation.
Performance optimizations.

Using Raw Pointers

With UnsafeRawPointer, we can access untyped memory content. It can be useful when we don’t know what kind of data we point to. Say, when initializing an NSData object from a given buffer [2]:

public init(bytes: UnsafeRawPointer?, length: Int) {
  super.init()
  _init(bytes: UnsafeMutableRawPointer(mutating: bytes), length: length, copy: true)
}

Additionally, raw pointers allow type punning and provide special APIs to do it correctly and safely [3].

Using Typed and Buffer Pointers

When we know Pointee ahead of time, we can use typed pointers:

let oneTwo = UnsafeMutablePointer<Int>.allocate(capacity: 2)

oneTwo.initialize(repeating: 1, count: 2)
print("First memory address:", oneTwo) // First memory address: 0x000000010045deb0
print("First value:", oneTwo.pointee) // First value: 1

oneTwo[1] = 2 // Subscript
print("Second memory address:", oneTwo + 1) // Second memory address: 0x000000010045deb8
print("Second value:", oneTwo[1]) // Second value: 2

Note that the integers are placed contiguously in memory. Therefore, we can interpret them as an array of two elements using UnsafeBufferPointer:

let buffer = UnsafeBufferPointer(start: oneTwo, count: 2)

for (index, element) in buffer.enumerated() {
    print("\(index): \(element)")
}

Lastly, free the pointer from memory:

oneTwo.deinitialize(count: 2)
oneTwo.deallocate()

Opaque and Managed Swift Pointers

Apart from the family of unsafe types, Swift has four more pointers:

OpaquePointer – a pointer for which we do not know the type of data it points to. It can be that the type of pointee is determined by the value of some other variable or cannot be represented in Swift [4].
Unmanaged – a manual-memory-managed pointer.
ManagedBufferPointer – a pointer to ManagedBuffer. The latter is used to building custom buffer-backed collections. It consists of a header value, where we can store a number of elements in the buffer, and a contiguous raw memory for the elements. ManagedBuffer is used internally inside the Swift standard library. It backs __BridgingHashBuffer, which is a minimal hash table storage [5], and __SwiftDeferredNSArray, which is an NSArray whose contiguous storage is created and filled, upon first access, by bridging the elements of a Swift Array [6].
CVaListPointer – a Swift equivalent of an (Objective-) C va_list pointer. An example of CVaListPointer that you probably already know is NSString’s convenience initialize.

The Unmanaged pointer is used in two primary cases. First and foremost, on the boundary of C and Swift APIs to bypass automatic reference counting, that is otherwise enforced to every Swift object. In such a case, an unmanaged pointer is used to wrap a Swift object reference into an opaque pointer, or convert an opaque pointer back:

class Foo {
    let x: Int
    init(_ x: Int) { self.x = x }    
    deinit { print("Deinit \(x)") }
}

do {
    let unmanaged = Unmanaged.passRetained(Foo(0))
    unmanaged.release() // Deinit 0
}

do {
    _ = Unmanaged.passUnretained(Foo(1)) // Deinit 1
}

do {
    let opaque = Unmanaged.passRetained(Foo(2)).toOpaque()
    Unmanaged<Foo>.fromOpaque(opaque).release() // Deinit 2
}

Second, to avoid reference counting overhead using fine-grained memory management. One example of the latter is Operation and OperationQueue from Swift Core Foundation:

open class Operation : NSObject {
    ...
    internal var __previousOperation: Unmanaged<Operation>?
    internal var __nextOperation: Unmanaged<Operation>?
    internal var __nextPriorityOperation: Unmanaged<Operation>?
    internal var __queue: Unmanaged<OperationQueue>?
    ...
}

Opaque pointers are used when working with incomplete C data structures which cannot be represented in Swift [7]. That is, data structures which are not fully defined in .h files, and are implemented privately. For example, this is the case for the Accelerate framework [8]:

public static func destroySetup(_ setup: OpaquePointer) {
  vDSP_destroy_fftsetupD(setup)
}

Summary

Swift exposes pointers via the family of thirteen types. Typically, we are interested in the unsafe pointers group, which allows us to access memory as instances of a specific type. Here is the list of them:

UnsafePointer<T>
UnsafeMutablePointer<T>
UnsafeBufferPointer<T>
UnsafeMutableBufferPointer<T>
UnsafeRawPointer
UnsafeMutableRawBufferPointer
UnsafeRawBufferPointer
UnsafeRawBufferPointer

There is also a group pointers, designed for C interoperability:

Unmanaged
OpaquePointer
AutoreleasingUnsafeMutablePointer
CVaListPointer

Lastly, there is ManagedBufferPointer, which is useful for creating custom buffer-based collections.

SwiftUI Previews at Scale

2020-05-18T00:00:00+00:00

Although SwiftUI previews fulfill their goal of generating dynamic, interactive previews, they come not without a price. SwiftUI previews sit on the boundary of test and production code, therefore, when applied systematically, they inevitably result in test code leaking into production. In this article let’s learn three techniques to help you manage SwiftUI previews at scale:

Extracting reusable previews into components.
Combining groups of previews into presets.
Using Fixture Object pattern to simplify object graph instantiation.

This is not an introduction to the subject. We won’t discuss how to generate SwiftUI previews or what you can get from them. To get started with SwiftUI previews, I recommend this tutorial by Apple.

Problem Statement

SwiftUI previews are easy to get started with. However, as your app grows in features in complexity, you are likely to encounter the problem of using SwiftUI previews at scale.

Extensive use of SwiftUI previews increases the cost of changing your code.

If you check Apple SwiftUI tutorials, you’ll discover that a single SwiftUI view has 2 previews on the average. From my own experience, I have 4-5 previews per view. Therefore, we can conclude that a typical production iOS app contains hundreds, if not thousands, previews.

Unless treated correctly, previews can potentially worsen maintainability of your codebase and slow down development speed:

Previews are treated as throwaway code. The number of previews keeps accumulating, reducing the overall quality of the codebase.
Previews contain repeated configuration code. Typically, we set up most of the previews under the same set of conditions, e.g., multiple locales, dark and light color themes, several supported devices. When we add a new preview, we just copy and paste the configuration code.
A complex object graph needs to be constructed for the purpose of a preview since a view depends on that graph. This way, previews setup code becomes bloated and fragile.

The solution is to follow the three techniques that will help us streamline SwiftUI previews.

Technique #1: Extracting Reusable Previews

The current strategy addresses the problem of boilerplate configuration code.

Before we jump to the solution, let’s see how previews turns out to be a mess even for a trivial SwiftUI control. Given a button:

struct SendButton: View {
    let onAction: () -> Void = {}
    
    var body: some View {
        Button(
            action: onAction,
            label: {
                HStack {
                    Image(systemName: "square.and.arrow.up")
                    Text("common.button.send")
                }
        })
    }
}

In a preview, we want to check the following SendButton states:

Supported locales
Dark theme
Right-to-left text direction
Multiple content size categories

Here is how we can preview multiple locales:

struct SendButton_Preview: PreviewProvider {    
    static var previews: some View {
        Group {
            // Supported locales
            ForEach(Locale.all, id: \.self) { locale in
                SendButton()
                    .padding()
                    .previewLayout(PreviewLayout.sizeThatFits)
                    .environment(\.locale, locale)
                    .previewDisplayName("Locale: \(locale.identifier)")
            }
        }
    }
}

// From https://www.avanderlee.com/swiftui/previews-different-states/
extension Locale {
    static let all = Bundle.main.localizations
        .map(Locale.init)
        .filter { $0.identifier != "base" }
}

The preview looks next:

Then we setup preview for the dark theme:

...
// Dark theme
SendButton()
    .padding()
    .previewLayout(PreviewLayout.sizeThatFits)
    .background(Color(.systemBackground))
    .environment(\.colorScheme, .dark)
    .previewDisplayName("Dark Theme")
...

The dark preview looks next:

Lastly, add the right-to-left and dynamic size previews:

static let sizeCategories: [ContentSizeCategory] = [.extraSmall, .medium, .extraExtraExtraLarge]
...
// Right to left
SendButton()
    .padding()
    .previewLayout(PreviewLayout.sizeThatFits)
    .environment(\.layoutDirection, .rightToLeft)
    .previewDisplayName("Right to Left")

// Content size categories
ForEach(sizeCategories, id: \.self) { sizeCategory in
    SendButton()
        .padding()
        .previewLayout(PreviewLayout.sizeThatFits)
        .environment(\.sizeCategory, sizeCategory)
        .previewDisplayName("Content Size Category: \(sizeCategory)")
}
...

That’s 40 lines of preview code for a 10-lines control. Instead of pasting this code for all future previews, let’s extract it into reusable components:

struct LocalePreview<Preview: View>: View {
    private let preview: Preview

    var body: some View {
        ForEach(Locale.all, id: \.self) { locale in
            self.preview
                .previewLayout(PreviewLayout.sizeThatFits)
                .environment(\.locale, locale)
                .previewDisplayName("Locale: \(locale.identifier)")
        }
    }

    init(@ViewBuilder builder: @escaping () -> Preview) {
        preview = builder()
    }
}

struct DarkThemePreview<Preview: View>: View {
    ...
}

struct RightToLeftPreview<Preview: View>: View {
    ...
}

struct ContentSizeCategoryPreview<Preview: View>: View {
    ...
}

It allows us to rewrite the initial preview into this:

struct SendButton_Preview_ReusablePreviews: PreviewProvider {
    static var previews: some View {
        Group {
            LocalePreview { SendButton().padding() }
            
            DarkThemePreview { SendButton().padding() }
            
            RightToLeftPreview { SendButton().padding() }
            
            ContentSizeCategoryPreview(.extraSmall) { SendButton().padding() }
            
            ContentSizeCategoryPreview(.medium) { SendButton().padding() }
            
            ContentSizeCategoryPreview(.extraExtraExtraLarge) { SendButton().padding() }
        }
    }
}

Technique #2: Preview Presets

Apart from reusing individual previews, we can also reuse groups of previews. I call this group a preview preset.

To create a preset, it’s convenient to begin with extension methods that simplify preview creation:

extension View {
    func previewSupportedLocales() -> some View {
        LocalePreview { self }
    }
    
    func previewDarkTheme() -> some View {
        DarkThemePreview { self }
    }
    
    func previewRightToLeft() -> some View {
        RightToLeftPreview { self }
    }
    
    func previewContentSize(_ sizeCategory: ContentSizeCategory) -> some View {
        ContentSizeCategoryPreview(sizeCategory) { self }
    }
}

Next, define a preset that we are going to use for all buttons:

extension View {
    func previewButtonPreset() -> some View {
        let content = self.padding()
        
        return Group {
            content.previewSupportedLocales()
            content.previewRightToLeft()
            content.previewDarkTheme()
            content.previewContentSize(.extraSmall)
            content.previewContentSize(.medium)
            content.previewContentSize(.extraExtraExtraLarge)
        }
    }
}

Now the SendButton preview turns out to be a one-liner:

struct SendButton_Preview: PreviewProvider {
    static var previews: some View {
        SendButton()
            .previewButtonPreset()
    }
}

Technique #3: Fixture Object Pattern

This recipe simplifies the construction of complex object graphs for the purpose of previews.

It’s very common for SwiftUI views to render deeply nested objects and objects with many properties. This results in the following problems:

You are interested in previewing only one property, but still need to instantiate the whole object graph. This way, the preview receives data that it does not need.
The amount of repeated initialization code increases.
Introduces extra room for mistake.

These problems become evident even if we take Apple SwiftUI tutorial, and try to preview a list of two Landmarks using custom data:

struct LandmarksList_Previews: PreviewProvider {
    static var previews: some View {
        let landmark1 = Landmark(
            id: 1,
            name: "Turtle Rock",
            imageName: "turtlerock",
            coordinates: Coordinates(latitude: 34.011286, longitude: -116.166868),
            state: "California",
            park: "Joshua Tree National Park",
            category: .rivers,
            isFavorite: true
        )
        
        let landmark2 = Landmark(
            id: 2,
            name: "Silver Salmon Creek",
            imageName: "silversalmoncreek",
            coordinates: Coordinates(latitude: 59.980167, longitude: -152.665167),
            state: "Alaska",
            park: "Lake Clark National Park and Preserve",
            category: .lakes,
            isFavorite: false
        )
        
        let userData = UserData()
        userData.landmarks = [landmark1, landmark2]
        
        return LandmarkList()
            .previewDevice("iPhone SE")
            .environmentObject(userData)
    }
}

If this was a one-off preview and you are completely sure that there will be no more previews like this one, then hard-coded initialization is fine. However, as you write more similar previews, such an approach results in repetitive and fragile code, and hence worsens maintainability of the codebase. The solution is the Fixture Object pattern.

The purpose of the Fixture Object pattern is to simplify object instantiation.

The proposed implementation of the pattern utilizes factory methods with default values. Here is how we can implement the Landmark fixture:

extension Landmark {
    static func fixture(
        id: Int = 1,
        name: String = "",
        imageName: String = "",
        coordinates: Coordinates = .fixture(),
        state: String = "",
        park: String = "",
        category: Category = .featured,
        isFavorite: Bool = false
    ) -> Landmark {
        Landmark(
            id: id,
            name: name,
            imageName: imageName,
            coordinates: coordinates,
            state: state,
            park: park,
            category: category,
            isFavorite: isFavorite
        )
    }
}

extension Coordinates {
    static func fixture(latitude: Double = 0, longitude: Double = 0) -> Coordinates {
        Coordinates(latitude: latitude, longitude: longitude)
    }
}

In case of high-level SwiftUI views like LandmarksList, we are interested only in the shallow verification, since we have already validated lower-level components in their own previews. Therefore, for the most of the object properties, we can get away with default values from our fixture implementation.

Here is how we can rewrite LandmarksList_Previews using fixtures:

struct LandmarksList_Previews: PreviewProvider {
    static var previews: some View {
        let userData = UserData()
        userData.landmarks = [
            .fixture(id: 1, name: "Turtle Rock", imageName: "turtlerock", isFavorite: true),
            .fixture(id: 2, name: "Silver Salmon Creek", imageName: "silversalmoncreek", isFavorite: false)
        ]
        
        return LandmarkList()
            .previewDevice("iPhone SE")
            .environmentObject(userData)
    }
}

I’d venture to guess that if it were a production app, you would check more cases in the preview:

struct LandmarksList_Previews: PreviewProvider {
    static var previews: some View {
        let twoRows = UserData()
        twoRows.landmarks = [.fixture(name: "Turtle Rock", imageName: "turtlerock", isFavorite: true)]
        
        let longList = UserData()
        longList.landmarks = Array(repeating: .fixture(name: "A"), count: 100)
        
        let longName = UserData()
        longName.landmarks = [.fixture(name: String(repeating: "A", count: 200))]
        
        let favorites = UserData()
        favorites.landmarks = [
            .fixture(id: 1, name: "A", isFavorite: true),
            .fixture(id: 2, name: "B", isFavorite: false)
        ]
        
        return Group {
            LandmarkList()
                .environmentObject(twoRows)
            
            LandmarkList()
                .environmentObject(longList)
            
            LandmarkList()
                .environmentObject(longName)
            
            LandmarkList()
                .environmentObject(favorites)
        }.previewDevice("iPhone SE")
    }
}

Source Code

You can find the complete source code here. It is published under the “Unlicense”, which allows you to do whatever you want with it.

Summary

SwiftUI previews are actually pieces of test code inserted into your production codebase. Their quality is equally important as that of the rest of your production code. We have discussed three techniques that will help you improve previews code:

Extracting reusable previews into components.
Preview presets.
The Fixture Object pattern.

As a further reading I recommend Testing SwiftUI Views, where I explain why you shouldn’t be using SwiftUI previews as your visual regression tool.

Yet Another Swift Blog

Code Generating Swift Mocks with Sourcery

Mock Objects Overview

Understanding Sourcery

Integrating Sourcery to Xcode Project

Code Generating a Mock

Using Mocks in Unit Tests

Source Code

Summary

Further Reading

Custom Popup in SwiftUI

Popup View Modifier

Aligning the Popup

Animating Popup Transition

Adding Direction

Source Code

Callable Objects and callAsFunction() in Swift

Types representing functions

Passing generic functions

Function identity

Bound functions

Delegation

Wrapping Up

Effective Auto Layout Programmatically in Swift

Auto Layout Programmatically vs Storyboard

Auto Layout DSL

Focused, Independent Components

Callbacks as a Communication Pattern

Stack Views Over Auto Layout Constraints

SwiftUI Previews

Summary

SwiftUI View Lifecycle

Understanding SwiftUI Views

SwiftUI View Lifecycle

Appearing

Updating

Disappearing

Further Reading

Unit Testing Asynchronous Code in Swift

System Under Test

Mocking in Swift

Testing Before & After

Expectations

More Use Cases for Expectations

Busy Assertion

Summary

Source Code

Further reading

Working with an Internet Connection on iOS with Swift: Best Practices

Checking Connectivity Before Firing a Request

Enabling or Disabling App Features Based on Internet Connection

Attaching Constraints to Network Operations

Summary

Infinite List Scroll with SwiftUI and Combine

Firing Paginated HTTP Request

Implementing Static List

Implementing the View Model

Implementing Infinite Scroll

Source Code

Further Reading

Swift Pointers Overview: Unsafe, Buffer, Raw and Managed Pointers

What is Memory

Pointers Overview

Swift Unsafe Pointers

Using Raw Pointers

Using Typed and Buffer Pointers

Opaque and Managed Swift Pointers

Summary

Further Reading

SwiftUI Previews at Scale

Problem Statement

Technique #1: Extracting Reusable Previews

Technique #2: Preview Presets

Technique #3: Fixture Object Pattern

Source Code

Summary