If you ever tried to understand why the Xcode build system complains about a compilation cycle or optimize a build where a particular step is invalidated between executions, there aren’t any good visualization tools that might help with troubleshooting other than build logs or Build Timelines added in Xcode 14. While these two techniques might still give some insights, 1) they are only available as a post-build artifact so aren’t useful to troubleshoot build system dependency cycles and 2) these approaches have limitations.

From what I observe, many engineers underestimate the complexity of build systems. That is especially the case for Xcode users where predefined templates bootstrap the project magically and developers don’t have to set up steps manually.

In this blog post, we will scratch the surface of the Xcode build system and audit what steps are involved when you press ⌘+R in a visual representation of a build graph using XCBuildAnalyzer.

Scenario I — build cycle

For sure you have seen an error saying that you have a cyclic dependency in your project, which might be just a simple oversight with incorrectly set target dependencies, but in more complex scenarios (mixed ObjC&Swift target, I am looking at you), the fix might not be simple. If that happens, Xcode provides a simplified cycle detail in the Report navigator view and prints the “raw dependency cycle trace” below.

The latter data is quite difficult to analyze but gives us some clues about the internal implementation of the build system. It consists of all nodes and commands that constitute a cycle in the build system graph.

Commands are actual steps that have a concreted action like calling an external application, while nodes are just virtual nodes, convenient for setting dependencies between commands. You can think of commands as real actions and nodes as breakpoints describing what kind of outputs/inputs a given command produces/depends on. A list of sample commands and nodes below might give you a clue of their differences:

Command (with tool involved):

• Copy (file-copy)
• SwiftDriver Compilation (swift-driver-compilation)
• SwiftMergeGeneratedHeaders (swift-header-tool)
• WriteAuxiliaryFile (auxiliary-file)
• PhaseScriptExecution (shell)
• CreateBuildDirectory (create-build-directory)
• ClangStatCache (shell)
• VersionPlistTaskProducer (phony)
• CodeSign (code-sign-task)

Nodes:

• entry
• begin-scanning
• begin-compiling
• copy-headers-completion

In our example, a quick inspection of all nodes and commands provides an overview of things happening. Names refer to module map/header map creation, validation, assets compilation, and other terms that not always might be obvious. To have a better mapping of all relations between steps, having a graphical visualization of all these nodes might be helpful. Fortunately, for each build (including those that failed with a cycle error), Xcode generates a full dump of the build graph nodes in the DerivedData. Despite the representation being in a readable JSON format, navigating through a large object file might be tricky, which is why I created an experimental macOS app, XCBuildAnalyzer, that draws it on a 2D plane.

The build analyzer can draw a graph that might look familiar to you if you have ever troubleshooted memory cycles in Xcode or Instruments. The goal of this app is to draw the graph in a digestive format, easier to create a mental model of parts in a cycle. Download the app and drag and drop the .xcodeproj or Package.swift after building it in Xcode.

As you may guess, the graph itself is very big so drawing it on a screen wouldn’t be helpful — thus, the app presents a subgraph, similar to the one generated for our example.

If you follow the yellow cycle path, you find that Library1 depends on Library2 in links:

• [Library1] end -> [Lirary2] entry
• [Library2] modules-ready -> [Library1] begin-compilation

That cycle is something we have to resolve — there aren’t any ready-to-apply fixes — problems are project-specific and the analysis should be carried over case-by-case.
For details, the XCBuildAnalyzer app allows expanding nodes in the graph to disclose steps relevant to troubleshooting.

Tip: the build graph view can very easily get out of control as you expand nodes. If that happens, just start the process from the beginning, just like you would do in the Xcode memory inspector.

Scenario II — missing dependencies

Do you recall a problem with random and transient Swift errors happening after cleaning a project or building on a different machine with the message No such model {HereModule}? That might be caused by incorrectly defined target dependencies and based on a nondeterministic order of compilation, the required {HereModule} might, or might not be ready yes.

If your project contains only a few targets, probably you can quickly find a missing link, but for bigger projects with dozens or hundreds of targets, that might be tricky.

The first sign of a problem can surface right after opening the graph and realizing that nodes from the problematic target {HereModule} are missing. That implies that you haven’t set any dependency to that module and it works on your machine because you built that target earlier or using a different scheme. But if both targets are on a list, let’s find the first common node that depends on two targets. First, we have to find which compilation target reported an error. In Xcode’s report navigator pick Recent and Errors only selectors to filter all other steps:

To inspect a problem, we want to find a relation between build graph nodes “finishing the Top2” and “beginning of the Down3“. Let’s open XCBuildAnalyzer and with the ⌘key, select [Top2] modules-ready and [Down3] begin-compiling. Let’s analyze the result below:

Let’s start by reading the graph from right to left. The build system always starts the analysis from theend node (0.) and traverses through the graph to find the steps required for execution.
Firstly, we can realize that there is no direct or indirect relation between Down3 (1.) and Top2 targets (2.). So why isTop2 even included in the build and why the build system is not complaining all the time? As seen, Top3 (3.) is the target that has an explicit dependency on a Top2, and based on the compilation order, Top2 and Top3 might be compiled prior to Down3.

Note that even the graph renders Down3 begin-compilling to the right of [Top2] modules-ready , that doesn’t mean it will be executed later. Remember that the graph represents relations between nodes; it does not represent a timeline.

Once we add a missing dependency in Xcode and compile the project again, the subgraph reveals the expected dependencies between Down3 and Top2:

Scenario III — curiosity

The last reason why you may want to review the build graph is pure curiosity. For instance, Xcode 15 introduced a nice feature to generate Swift/ObjC type with all of your Assets symbols (for more details, read this blogpost). You might ask yourself: (1) how is that implemented? and (2) can I safely modify .xcassets content from prebuild shell build scripts so the generated asset symbols file will always reflect the change?

Finding a starting point for the assets symbols generation shouldn’t be difficult because node names are often self-explanatory (like CompileAssetCatalog, GenerateAssetSymbols , TestTargetTaskProducer, etc.). In our case, that will be GenerateAssetSymbols and on the right pane of the XCBuildAnalyzer, you can find that it is an external shell command (actool) invocation. Bonus: you can inspect the list of args and ENVs passed to that external command.

As expected, this step will output two files (ObjC and Swift) and take Assets.xcassets directory as input.

Question 2: Can I safely modify .xcassets content from pre-build shell build scripts so the generated asset symbols file will always reflect the change?

For the second question, before jumping into heavy 2D graph visualization, let’s add a shell script and analyze raw Xcode’s build output logs to see which one was executed first.

In the logs, seems that our script was indeed scheduled first, but is that a coincidence? Maybe we were just lucky? Let’s open the project in XCBuildAnalyzer and compare the relationship between [GenerateAssetSymbols] xxx.swift and <execute-shell-script> . From the left pane select two nodes (you can use ⌘ or ⇧ keys) and you will get something like:

Success! So there is a strong relation between those two steps and we can be confident that GeneratedAssetSymbol.swift will be generated after the script is done. Saying that we can safely modify the .xcassets directory, and the actoolwill respect it.

Warning! Having the right asset symbol in Swift/ObjC is just a partial success. To ensure that the modified assets will be included in the application bundle, we need to ensure that the assets compilation step (CompileAssetCatalog) is also dependent on the run script. With just a few clicks you can validate that this is also a case — Assets.car (the compiled assets representation) will also include updated assets.

Epilogue

XCBuildAnalyzer is one of those tools that sit in your toolbelt and you hope to never need it. However, it might be helpful if you hit a tricky build system problem that you cannot resolve in a conventional way: by reading logs or double-checking Xcode target dependencies.

So let’s hope for the best, but prepare for the worst — try out XCBuildAnalyzer and say hello to the Xcode build system internals!

How to effectively verify unit test side effect without code generation in Swift

Often we need to unit test code with side-effects that interact with other parts of your system using abstraction — protocols in Swift. There are many techniques to build that abstraction and verify if our code works as expected: stubbing, spying, dummying etc.

Previously, I made a deep dive into auto-generating a stub placeholder that allows seamless customization of a mock’s function behavior right in a test case. Let’s extend that approach with a spy registration that observes and records side-effects generated during a test case.

What you need to know first

Let me present in a nutshell how you can speed up a process of building function’s stub with some Swift compiler help (for details refer to my previous post).

Assume that you wish to create a mock for a protocol containing some function (for the sake of this article named addUser(name:)). And instead of creating it from scratch with a custom flag(s) and/or embedded assertions, for each function generate only a single variable as a placeholder to be called internally during that function’s call. In a traditional way, you would need to manually provide a type of that placeholder's function but with lazy modifier and some simple helper function stub, it can be inferred by a Swift type system. The final solution would look as simple as:

In a test case, you need to explicitly register behavior of addUser with a concrete implementation, like:

Problem statement

The benefit is that we don’t have to manually specify the type of addUserAction variable. However, generating its body (addUserAction) has to be done on a test case-level which often leads to messy variable declaration and assignments as above. The aim of this article is to completely eliminate that manual step of action declaration which in a first place can positively affect test case readability and as a by-product positively affect development speed and joy.

Step 1: stub split

Firstly, let’s modify our stub function and separate its input and output types into two generic types:

it works also for functions that take several parameters —then the type will be a tuple with corresponding types, like:

Nice mock stubbing

Once we split the type of our entire stub’s type into Input (I)and Output (O) generics, as a low hanging fruit we can make a stub builder that generates nice stub — one that returns some predefined value:

Once action placeholder is build using niceStub, in a testcase we don’t have to manually “register” the function’s body before calling the protocol’s function:

Another simple improvement here is defining predefined return values for some popular types (like 0 for Int, false for Bool, nil for Optional<T> etc.). With a simple DefaultProvidable protocol that specifies a default value of a given type and more specific niceStub, stubbing is as simple as never before:

What if the function doesn’t return anything? In a Swift language all functions actually return something, Void if not specified. Void is implemented as a zero-length tuple and as a non fully fledged type it cannot conform to any type like DefaultProvidable. No worries, Swift type system can correctly select the right implementation if we introduce another niceStub specifically for functions that return Void:

func niceStub<I>(of: (I) -> Void ) -> (I) -> Void {
return { _ in }
}

Call arguments spy

Although we have a simple way to define stub, we completely ignore passed arguments there. However, it not uncommon to inspect arguments that have been passed to the mock object and to achieve that we need to apply another trick. Thanks that body of a mock’s function (like addUserAction) is defined as a variable we can easily edit its behavior in a testcase runtime.

To apply a spy, just inject an intermediate spy layer that stores all the arguments call in a recorder and performs already specified body.

If you are not familiar with Swiftinout modifier, it gives a change to modify the value of passed argument once it is finished. It resembles a bit passing pointer argument in Objective-C but with a restriction that it cannot escape that “pointer”.

spyCalls takes an inout argument of a function to spy, injects a function that records its arguments to ArgRecords<I> and then calls original stub implementation.

Implementation of a missing ArgRecords is really straight-forward as this is just a custom collection to keep track of all records. It needs to be represented as a reference type collection and backing up by the simplest Array is often enough (as long as you don’t expect any multithread read/write operations).

ArgRecords resembles a Collection but here it specifies custom subscript return type. Instead of T, I suggest returning optional T? just to not crash tests if the expected spy index is out of range. In practice, subscript result lands in XCTAssertEqual which automatically aligns optionality types and gracefully could handle out-of-range access:

Technically, subscript could return non-optional T and conform to Collection but any out-of-range access crashes the test suit —it is up to you what type to select.

Further improvements

If you find it useful and promising, this is just a beginning! The presented approach sets up a foundation for much more complexed and omnipotent testing toolset that supports synchronous or asynchronous expectations, return values control with some syntactic sugar API. Open-source StubKit library is based on that approach and provides a set of extensions (some of them are described below).

Improvement 1 — support for throwing functions

Until now we assumed that our stubbing function does not throw. If it does, we need to prepare twin declarations of stub and spyCalls that are capable of stubbing and spying functions with throws modifier:

Improvement 2 — generics functions

Creating a stub/mock of a function that is generic is a bit tricky. As long as you expect only one specification, your entire mock can be generic with a force-casting (aka unwrapping):

However, if a single generic type for a stub is unacceptable, you should prepare a set of expecting specializations and choose one that matches. Please refer to StubKit’s documentation for detailed example.

Improvement 3— Convenient ArgRecords comparison

So far in the assert section we had to manually compare each subsequent call manually:

With straightforward conformance to Swift’s ExpressibleByArrayLiteral protocol, ArgRecords can be initialized directly from an array literal (like [1,2])

Furthermore, if we spy a function that takes a single Equatable argument, entireArgRecords can easily conform to Equatable:

By wrapping these two improvements, the Swift compiler automatically aligns appropriate types and makes such idiomatic assertion possible:

Summary

Writing and working with a manually created stub or mock seems to be a bit boring and wearisome step. Contrary to other languages (Ruby or JavaScript) lack of type dynamism API in Swift prevents more flexible and automatic testing tool. Technically Swift ABI lays some groundwork for magical testing library, but as Doug Gregor wrote, “it would be a bunch of work (…) yet doable”.

I believe that the presented in this article approach eliminates some degree of dummy code that has to be written, although some minimal work to prepare a mock/stub is still required. The greatest benefit is concise and self-explanatory test case without a flood of intermediate variables placed around stubs and test case scope.

How do you assert that your code doesn’t introduce any unexpected cycles that lead to memory leaks? Do you actually verify weak/strong references in unit tests? If you find these questions interesting, let me demonstrate how you can write a concise and self-explanatory Swift test case that verifies correct reference type.

Weak verification

Whether your code keeps a strong or weak reference to some other object is crucial for non-garbage-collected languages like Swift. Even a tiny mistake may lead to a leak, invalid behavior or even crash. Although I don’t see many developers writing them, I believe that verification on a unit test level for misaligned reference type should a part of the implementation cycle— no matter if you practice TDD approach or not. Maybe our developer community categorizes them as second-class citizens because we are not sure how to write them and their readability is often far from perfect?
Let’s consider the simplest possible test that checks if an instance of a listener added to MasterClass’s is kept weakly:

We can identify several code-smells there, including:

1. unnecessary weakListener — duplication of listener just to inspect if a weak reference becomes nil
2. Optional type of a listener (with force unwrap )— to let it be nilled
3. manual assignment (weakListener=listener) of a strong reference to a weak one

Even if you fix the second issue by introducing a scope that automatically releases listener at the end of its lifetime, this could end up with even more esoteric code:

Tip: Swift’s do block we often identify with do-catch structure that catches Errors, while standalone do keyword is still a valid scope generator. As you may expect, within a body of suchdo block you cannot call try since potential thrown Error wouldn’t be handled.

Alternatively, you may find XCTestCase’s addTeardownBlock function useful here. Similarly to defer keyword it defers the execution a block until all other commands in a test case finish — practically just before tearDown function. Nifty approach yet with a bit limited flexibility due to potential execution reorder.

Weakly-scoped — `with` inspiration

Many modern languages (like Kotlin) provide setup functions intended to build up an instance in a self-contained scope (often named as with,apply), like:

In a discussion started by Erica Sadun, the Swift community considered adding it to a language. Ignoring the self-rebinding syntax, the implementation would be really straight-forward — take a starting instance T, mutate it in a block that takes that reference’s copy as an inout parameter and return mutated value:

Maybe you already noticed that our initial problem resembles the solution that discussed with tries to solve. To verify weak reference we had to:

1. take initial/starting value of some generic T reference type
2. pass it to the block body that presumably leverages it (e.g. adds a listener, send as a function argument etc.)
3. observe our initial instance weak reference if it is nil

Combining the approaches in the first paragraph and with implementation, one may try to write it as follows:

At glance, it looks OK but the above snippet doesn’t work as one might expect. Even the dummies weaklyScopedNaive(MasterListener(), action: {_ in }) always returns non-nil value because first(v) argument keeps a strong reference until the end of weaklyScopedNaive function, making in practice weakValue a strong reference.

Weakly-scoped solution

To overcome that problem we should transfer instance generation to the scope controlled by us and observe a weak reference after the scope destroy. No matter how complex that sounds, Swift provides such feature out the box — @autoclosure. Originally, it was designed to instantiate heavy instances on demand, to not compromise performance but it perfectly suits our need. Let’s introduce small changes to our function’s definition (add @autoclosure and rethrows):

autoreleasepool (don’t mix up with autoclosure) could be useful if you play with Objective-C objects that might receive autorelease message (instead of release one that always happens for Swift class), that deffers deallocation until end of autoreleasepool. If you don’t expect Objective-C instancess, do scope is enough.

Let’s come back to our initial test case and try to rewrite it using weaklyScoped helper:

It presents the essence of our test case scenario with a clear separation into Arrange, Act, Assert sections and elimination of noisy assignments. All the commands perform in a synchronous manner so complex scenarios with several steps also can apply this technique.

Summary

Test cases that verify reference types (strong vs weak) can eliminate plenty of invisible, nasty bugs affecting memory footprint or invalid behavior. If you ever found them clumsy and counter-intuitive to read, with the presented approach we can eliminate most of their drawbacks.
Although the weaklyScoped implementation uses some advanced Swift features (autoclosure, rethrow ) the final test case is simple and self-explanatory, even for beginners.

Add-on:

The usability of weaklyScoped function exceeds that trivial scenario with a listener or delegate. You can leverage it for leak detection or even completion-cancellation. For the inspiration on how to track them, see snippet below:

If you want to configure your iOS/Mac (Swift or Objective-C) build with some alternative variant, there are plenty of different approaches to follow. In general, you can divide them into two clusters: switch it in runtime (e.g. parsing Info.plist) or compile-time (leveraging Swift Compilation Conditions/Preprocessor Macro or define new target). Obviously, we always prefer the compile-time check but the overhead often may overweight its benefits.

This post will present an alternative way to control a file variant selection based on Xcode Build Rules (in contrast to traditional Xcode targets).

Problem statement

There are plenty of solutions to build a different flavor of the app that may differ in:

• endpoint address (e.g. staging vs production)
• logic (e.g. enable/disable geofencing check)

For more details, let me recommend this post, which presents most of them in details.
Long story short, for Swift development you can choose between:

• Compilation Conditions to use #if DEBUG ... #endif structure to include or disable given block of code
• separate targets, where each target contains a separate, dedicated file with a specific code for given configuration
• runtime checks from .plist input file or environment variable

Each has a drawback, to mention:

• iffing on compilation conditions may lead to a messy code with a plethora of #if that affects the readability
• separate targets introduce the unnecessary need to include all the “shared” codebase and configuration to all of them
• for runtime configuration, we lose compile-time check.

Wouldn’t be great if we could have a solution with a single target that depending on a configuration uses a specific variant of a file?

Solution: Use or skip a .swift file using custom Build Rule

Traditionally, Xcode targets give you a chance to selectively choose which file to include for compilation. You may leverage it to replace one source file with another one that specifies other baseURL or completely different logic strategy. For the sake of this post, let’s assume that we want to use one of two different Configuration_X.swift files:

// Configuration_S.swift
struct Configuration {
  let baseUrl = "https://staging.example.com/"
}

// Configuration_P.swift
struct Configuration {
  let baseUrl = "https://example.com/"
}

Without targets, we can achieve that using custom “Build Rules”, less popular tab in Xcode’s project, where you can specify how to process project files depending on their filename.

When adding a custom Build Rule, you have to specify file pattern, a shell script to apply and what is the output file of your script. Then, Xcode during a compilation process will evaluate your script for files that match given pattern instead of a default behavior (e.g. compiling .swift files). Please keep in mind that custom Build Rules have a precedence over the embedded rules — that gives us a chance to override the default compilation behavior.

For our solution, we will follow the algorithm:

• include all versions of Configuration_X.swift into a single target
• Xcode project specifies a dummy Build Rule that swallows files you want to skip (exclude from a build)
• all other files (out of xxxxx_x.swift format) are processed as usual

To control which files to swallow in a dummy Build Rule we will create a separate Xcode Configuration with User-Defined Setting CONFIGURATION_VARIANT (the setting name is of course up to you):

Above configuration means that for “Debug” configuration we would like to choose staging file variants with “S” postfix (xxxxx_S.swift) and for “Release” production with "P” postfix (xxxxx_P.swift).

There is plenty alternative options to specify User-Defined Build Setting, e.g. `buildsetting=value` argument for xcodebuild terminal command.

Coming back to our newly created Build Rule, let’s specify that we want to manually process a subset of the project’s .swift files:

1. Process Swift files that end with a single-character postfix other than CONFIGURATION_VARIANT (please note that Xcode uses simple pattern matching rather than more powerful regular expressions here)
2. The script creates in a derived directory an empty file with _skipped postfix
3. Specify that Xcode should process just created empty file instead of an original one — here we technically consider the body of a file as empty.

Please note that we operate on a $DERIVED_FILE_DIR directory so given script creates a file in a build directory and doesn’t modify an original file, potentially under source control.

As a result: no more multiple-targets, no more #if... #endif blocks, no runtime checks— Build Setting (e.g. specific for a Configuration) controls if a given file should be included or not.

A sample app that demonstrates it is available on GitHub.

Finally, please note that this technique isn’t limited to .swift files. With a small modification of a Build Rule presented above, you may apply it for Objective-C files, images, assets or other data like .json files too.

Summary

Build Rules is a tool often underestimated and barely used by iOS/Mac developers. This post demonstrates how it can be useful to selectively include/exclude .swift files from a compilation process. Now we have another alternative to consider before immersing to the world of multiple-target projects or conditional-based code.

One limitation is that we can use only single-character postfix marker (like _A.swift, _B.swift, _1.swift etc.) as Xcode does not support glob or regex file matching in Build Rules tab. Feel free to duplicate OpenRadar suggestion that gives Build Rules more control on that.

Often we need to unit test a code with side-effects that interact with other parts of your system by abstraction— protocols in Swift. There are many ways to verify if it works as expected: stubbing, spying, dummying etc. In general, engineers dubbed these forms as mocks, even “test double” is a legit name for that.

FYI, “test double” name comes from “stunt double” in the film industry.

Writing test doubles (like stubs or mocks) is a boring process in Swift and developers often try to generate it automatically by using tools like Sourcery/SwiftyMocky. However, if you wish to have more granular control or don’t want to introduce a new step to the build process, there is one trick to quickly (at least quicker) implement a test double.

Side note: stubbing/mocking difference

If you know how stubbing and mocking works, you can easily skip the following two chapters and jump to the next chapter or directly to the solution.

First, let’s distinguish what is the difference between stubs and mocks as they are quite similar. The fundamental difference sits in a verification process:

• for stubs, a test case has to manually call some methods to verify that expected side-effect happened
• mocks make verification automatically using predefined configuration

Let’s compare it in a pseudo-swift code:

CounterMock is preconfigured during initialization contrary to CounterStub where at the verification step we need to explicitly compare some addCalledTimes property to 3. The way these two test doubles are implemented is an implementation detail. The general rule of thumb is that verification distinguishes if we are using a stub or a mock (or mixed hybrid).

Stubbing a function

Let’s leave theoretical discussion off and go back to the ground. How actually a stub can be implemented in Swift? We want to create an object that conforms to a protocol with a chance to 1) verify if given functions have been called with the expected arguments and 2) control functions return values.
There are many approaches to do that, and the simplest is to introduce as many properties as behaviors we want to track into a stub. E.g. if you want to very that function has been called given times, add a counter, increment it in a function and after the test verify its value — as presented in the snippet above.
However, an alternative is to add an additional variable that provides a function placeholder (with almost the same signature type as the function) and call it when conforming to the protocol. I wrote almost because we will make it optional just for convenience if a test case completely wants to ignore a given function.

In this blog post, we will talk about protocol functions since variables are relatively simple to stub — just by introducing an instance.

For the sake of this post, let’s think about the simplest protocol that synchronously saves a username to a database and returns a boolean to inform if a procedure succeeded or not. Its mock would look like that:

For a function addUser, we introduced a variable addUserAction — a function that is evaluated every time addUser is called. Then, in a test scenario you can 1) verify that your system under test (testing code) indeed called that function and 2) emulate how database reacts (whether return true or false):

Generally speaking, by introducing addUserAction variable that matches functions arguments and return types, we let a test case to define a body of the relevant function of a protocol.

By the way, if you don’t like optionality of addUserAction property you may continue with an equivalent implementation:

Solution: inferred type

In the stub presented above, we had to explicitly provide a type of addUserAction variable. For short functions, it seems to be an easy task but for ones that involve several arguments, closures, (re)throws, @autoclosure it may end up with a fight between you and the compiler. To overcome such burdensomeness, we can leverage Swift’s type inference system. The solution involves a global function that returns nil value of the same type as an argument:

At first, it looks like a nonsense function but we will use it only to pull out T type, not its value.

Functions are first-class citizens in Swift, so we can pass a function as an argument to asNil to get a nil instance where Wrapped type matches the function type. In the example below, we have a variable addUserAction initialized as a nil value of the same type as our protocol’s function. That is exactly what previously we had to write down manually:

It is required to mark this variable a lazy because referencing addUser implicitly depends on self, which cannot be accessed before full initialization.

Our Database protocol is very simple so the benefit is not so spectacular, but for extremely complicated function, the gain is significant. Like here:

Another benefit of this technique is that in case of protocol’s type modification we don’t have to touch stub’s implementation at all — the compiler will automatically update types.

Summary

We developers love concentrating on a real problem rather than spending time on boring and dummy tasks like implementing test doubles. Fortunately, Swift’s static type analyzer provides a handful tool — we can leverage it to auto-infer property type used in unit test stub implementation. Then, in a matter of seconds, we can have a stub ready to work, flexible and fully customizable in a test case.

I’d like to thank Mateusz Maćkowiak for inspiring me to write this post.

Edit (16th of November):

Some people wrote me that described approach has a downside: unit test does not explicitly verify which side effects are made and furthermore it requires to provide a fallback return value when a test case did not specify concrete xxxAction implementation (the ?? false part).
I agree, both arguments are true so if you share these concerns, let me present an alternative approach:

Instead of asNil function, we will replace it with stub(of:), which behaves like implicitly unwrapped T.

Starting with Swift 4.1, ImplicitlyUnwrappedOptional has been reimplemented but if you still remember it, you can think of stub(of:) returning T!.

Unit test crashes in runtime if you call addUser(name:) before initialising addUserAction in a test case. As a benefit, 1) you have full control which side effects are allowed to be called (any non expected call to a stub crashes/fails a test) and 2) you don’t need to specify fallback return values.

Now, you have a choice. If you prefer to:

• never crash in unit tests -> use asNil approach
• have full control of side effects -> use stub(of:).

We all love protocol extensions, one of the most powerful element of protocol oriented programming (POP) in Swift. Despite their unquestionable benefits, there are some rare cases where you should avoid them. In this article, let me demonstrate a potential trap that your API consumer may fall into when trying to unit test a code that depends on some protocol extension function.

Quick reminder: method dispatching

In Swift we have three kinds of method dispatching: static, vtable and message dispatching. If you are not familiar with this terms, let me recommend a great post from Riazlab’s. In short, dispatching methods use different techniques to choose a concrete implementation of you function to execute if the same signature is defined in several places (e.g. parent class or protocol extension). For instance, 1) having a class that inherits from NSObject will always use message dispatching and 2) value types (structs, enums) will always use static dispatch.

OK, let’s go back to our dangerous scenario, where as an API creators (and we all are API designers, do you remember presentation by John Sundell?) we follow best practices and provide protocol abstraction for our public API. For the sake of this article, let’s assume we wish to expose a logger class that may log verbose and error messages, as shown below:

At glance it looks OK, but what if we wish to add a convenient API functions to log particular level? Protocol extension looks as a perfect match:

So far so good. If we have some hypothetical API consumer where generic Logger abstraction is used in System class, it can directly call a method to log verbosely, like below:

This works as expected, but let’s go over unit tests of a System class?

Testing API protocol extensions

Let us verify that our System actually logs a verbose message to a logger, every time we start it. Piece of cake. First we have to create a mock that conforms to a Logger protocol and keep track of all calls to verbose function. At the end, verify that verbose function has been called as expected:

It may be surprising for you, especially knowing that System actually logs a verbose message in a production code, but this test fails with a message:

XCTAssertEqual failed: (“[]”) is not equal to (“[“System started”]”)

Failing scenario

To understand what went wrong, we have to analyse dispatching method used to execute logger.verbose(message:) inside System.start(). System instance has a reference to a protocol Logger which provides function verbose in a protocol extension. By design Swift will always use static dispatch to call protocol extension’s implementation, no matter if actual implementation of a logger (LogMock in our case) implements verbose(_:String) or not.

One way to workaround it to verifying if LogMock.log(_:message) has been called correctly. It may seem like a rational idea at first, but but there’s an inherent problem with this approach —in System class tests, we have just began testing real verbose(message:) implementation from the API, written by a third-party developer. Potential implementation change or bug in Logger.verbose(_:String) could influence our test result. Unit test, as even name suggests, should validate the single unit of a code (here System class), in a highly isolated context.

How to define API protocol correctly?

Solution to this problem is really simple. As API designer all you have to do is to include all the functions/variables that you want to expose in a protocol extension into a main protocol definition, like:

This changes a dispatching method of a verbose(message:) and error(message:) functions into vtable , which resolves an implementation in a runtime. As a result, our test scenario executes verbose(message:) from a LogMock implementation, as you would expect:

Customer flow

Above fix is dedicated to API creators, but even if you don’t have access to modify protocol declaration, there is a remedy for your troubles. You’ll need to depend on your custom protocol that inherits from an original one and includes all declarations that API designer exposes only from protocol extension. In the meantime, while waiting for API designer’s fix, you are not blocked anymore.

Summary

We talked about protocol extensions and saw that testing a code that depends on a protocol extensions could be tricky. Fortunately, there is a really simple remedy for that — just include functions/variables definitions from a public protocol extension in your protocol definition. So when you hear yourself saying, “Let’s just implement it in a protocol extensions”, you’ll know it’s time to backpedal and ensure that static dispatch would not thwart customer’s unit tests.

For all their advantages, dynamic nature of vtable dispatching has some performance overhead comparing static one, which does not have to perform a table lookup. However, difference isn’t noticeable in most cases so it sounds as a reasonable tradeoff to make your API testable.

There isn’t a lot of articles about error handling in the iOS ecosystem, even this seems to be a non easy and substantial component of each app. Today, I wish to tackle this problem and present my solution towards less disruptive error handling in the iOS app.

Initial state

To ensure that we are on the same page, by an error I will mean an instance that conforms to Swift’s Error type and error handling is a reaction to it. These errors may arrive in a synchronous manner (disk operations, invalid argument) or asynchronously (no Internet connection, session token invalidated etc.). First group is obviously easier to deal, thanks to Swift’s standard do-catch structure. Very often, straightforward bottom-up procedure is sufficient, where an error breaks execution and it is automatically passed to a caller. If you have an asynchronous API with completion handler, developers are free to choose among plenty of techniques (to mention promises or RX streams) that also frequently follows the bottom-up model. In general bottom-up means that we propagate an error to our parent layer if we cannot handle it completely.

I found out that in many cases bottom-up direction is not a best approach and leads to a frustration when an error has to traverses plenty of layers up just to reach the one that is able to consume it. To give you an example, let’s assume that APIClient received 401 Unauthorised HTTP response, and your app should return to the initial login screen. Does it sound familiar for you to check if completion handler in a ViewModel is able to handle particular error, if not pass it to its Flow Coordinator, which then passes it to the parent(s) Flow Coordinator to finally reach to a generic place where you instruct the navigation controller to move back to the root. It ends up with a code that switches on an error extensively, like:

In case you chose delegate mechanism for a communication between distinguish elements, your delegate protocols may start to swell — every coordinator should include error events of its nested children. I observed that in many apps upper layers in a tree can handler only some specific errors (like session invalidated or unsupported API version) and below there is an aggregation point where all errors are presented to the UI (in a form of alert view or similar). So instead of starting from a bottom layer, I suggest reverting the propagation order, and start from the top layer and pass it down only when the parent layer wasn’t able to handle it.

Note that in a root element we obtained a single aggregation point of all errors in the app what may be useful for analytics purpose.

So, let’s will divide error handling process into two phases:

• Phase 1: propagate events up to its parent (unconditionally)
• Phase 2: propagate event down, layer by layer to find one that can handle it

Such procedure is not a completely new idea, for instance JavaScript uses a very similar technique called bubbling event delegate to dispatch touch events to DOM elements.

Protocol definition

Implementation of a top-bottom error handling architecture is not a difficult task. Let me demonstrate you that you can easily implement it within 50 lines of code with a generic protocol oriented solution that is open for extensions.

For the purpose of this article, I will use function names inspired by Swift’s keywords list (catch,throw, finally). While some of you may take it as a bit controversial, I believe such analogy helps understanding it.

We will define the only one protocol, ErrorHandleable, that will be used as a node in an error-handling tree. Each instance keeps a reference to a parent layer used in the Phase 1 propagation and encapsulates a generic closure (HandleAction) used in the Phase 2, that decides whether it should be populated down or not (throws an error or not).

API is very concise and consists of only two functions:

• throw is a function that begins handling an error (Phase 1) and receives an optional closure finally that is called after the handling process with an argument informing whether some layer did eventually handle it or not
• catch receives an error (Phase 2) and decides if it should be populated down or not

Take a look how could potential API call may look like:

Note that when using this API, contrary to protocol definition, you don’t have to escape keyword-reserved names (like throw). Swift infers that we mean function instead of expression here.

First, we built up a handling tree, where previousErrorHandler is some already existing handler received by some dependency inversion technique (e.g. dependency injection), and define two catch functions that potentially may handle an error. In a case that we observe an error in an asynchronous manner we throw it into our errorHandler instance to handle it. According to top-bottom procedure, it first climbs up into a root element, and then we visit all the nodes in the reversed order to finally find an element that completely consumed it (non-thrown action errorHandler#2).

In addition, nothing refrains from rewriting an error in an action block. Just throw completely new error (let’s say in errorHandler#1) and all beneath layers will observe modified one. However, remember that with great power comes great responsibility and use this capability with caution…

This protocol API is very generic, so we can add some extensions for convenience usage:

1. constraint caught errors into a generic type and transparently pass all others:

2. constraint caught errors into a single value (for a type conforming to Equatable protocol):

3. listen only for a particular type (or Equatable value) and never handle any error:

Sky is the limit for more protocol oriented extensions. For instance, you may add a function useful for synchronous API, that resembles do keyword — takes a throwing closure and begins a top-down handling in case of thrown error.

Presented above protocol definition is rather a starting point that can be easily customised for you specific needs —for instance I can imagine a use-case where you wish to control also Phase 1 propagation…

One possible implementation

Now, let’s try to create one possible implementation of ErrorHandleable — ErrorHandler. Root handler obviously contains no parent so its type has to be Optional and its default action is totally-transparent one that always propagates it down (functions are first-class citizens so nothing refrains us from introducing a default parameter in a signature):

Then, let’s provide an implementation of a required function throw, that accumulates an array with a path nodes:

When throw reaches the root node it performs Phase 2 by calling serve function which is also very simple: it calls an action and depending if it throws an error, passes it to a next element in a responsibility chain (next) or breaks it and calls finally closure:

The only one missing step is implementation for a catch function: it creates a child element with a defined action and current node defined as a parent:

If you combine entire ErrorHandler implementation, it takes only 50 lines of code. Code implementation with all extensions is available here for reference.

Final results

Having implementation of ErrorHandleable/ErrorHandler ready, we can take a look how would it look like in a real application, let’s say with MVVM+FC (Model-View-ViewModel + FlowCoordinator) architecture.

In a root ViewModel we instantiate ErrorHandler. Thanks to a fact that all errors within our app have to visit this node we have a perfect chance to automatically send it to our logging framework.

Once we have attached all the listeners, we pass rootError all the way down the view hierarchy, here RootCoordinator which does not handle nor listen for an errors.

Let’s assume it's child coordinator LoggedInCoordinator can handle one specific error ApplicationError.sessionInvalidated and presents any other ApplicationError with an alert. To achieve it, in LoggedInCoordinator we have to keep a strong reference to a parent handler and every time our coordinator sets up a new child, it builds a new handler using computed variable errorHandler. I used computed variable since we cannot assign it once in the initialiser as it’s action references to self , not fully initialised at the initialisation yet. When defining closure-based action remember to always keep a weak reference to self, otherwise you may easily introduce retain cycle and memory leak.

Once we obtained an error asynchronously while the app is running in ScreenViewModel, we start handling it by calling throw function:

As a result we achieved a simple API where:

1. entire error handling code is isolated in some parent element (here LoggedInCoordinator) and rest of a code does not care about it (unless it wishes to),
2. action handlers are type-safe,
3. code models native Swift syntax what improves its readability,
4. all hierarchy elements depend on a protocol ErrorHandleable, so isolating it for the sake of unit testing is not a problem.

Conclusions

Standard approach for handling an error by propagating it up does not scale well and if your code contains a lot of layers (nested coordinators or controllers), communication between them may easily get our of control. With a presented above top-down approach, all the errors traverse in the reverse order — from a root to a child layer — so parent layer decides if it is able to handle given error and its children do not necessarily have to care about it.

Implementation of such top-down architecture is quick and straightforward so in my opinion there is no need to introduce any third-party library, even any μFramework. You benefit from a solution that perfectly meets your requirements and you get rid of one external dependency. Perfect win-win! If you want to see it in action, here is a very simple sample app.

If you have any comments or any other error handling patterns to share, don’t hesitate to let me know on twitter @norapsi.

PS1

If you are wondering, what it has to do with a pinball game, here is an animation:

Thanks to Martyn Pękala and Jenus Dong for valuable suggestions.

Edit : Added github sample project

TLDR;
InjectionTDD (together with InjectionForXcode) runs unit tests on a simulator environment without rebuilding nor reinstalling the app. Implementation and tests are injected into already-running host app, thus work almost in a real-time within a standard, well-known Xcode IDE. In addition, to speed-up testing process, InjectionTDD runs only a subset of test cases — these related to your just-updated implementation file.

Goal

It is crucial to get quick feedback whether your tests are passing (green) or failing (red) if you are making TDD, but not only then. Wouldn’t be nice to instantly know that your change/fix does not introduce any regression somewhere else? Or maybe you are covering your implementation with new test cases and it becomes frustrating to rebuild test target all over again? If you observe the same issues, InjectionTDD can save you a lot of time!

Live updating

Normally, to run unit test you have to wait for several steps like: building, linking, installing entire app and connecting Xcode with lldb server. Depending on your configuration it may take up to dozens of seconds. However, during development we quite often modify only one particular file and then observe the results. InjectionForXcode saves a ton of time by compiling updated file on-fly and replacing/swizzling its implementation in a live iOS process. Very similar approach can be applied for unit testing. This is how InjectionForXcode+InjectionTDD works in general:

First, Xcode builds your test target, installs an app on a simulator and tries to perform first tests. However, dedicated framework called InjectionTDD, that you have to integrate into a test target, stalls test executions and keeps a runtime in a constant waiting loop.

Then, whenever you change something in Xcode, InjectionForXcode builds a slice of an application (only edited file + related unit tests) and injects it into already waiting “Hosting app”. At last, host app executes all tests and passes results back to the Xcode to presents them in its standard UI. Keep in mind that host app is not terminated afterwards and the entire process can be repeated all over again.

Installation process

Armed with theory background, let’s roll our sleeves up and play with it. You can start with any existing project with unit tests that is written in Swift or just try it out by pods command pod try InjectionTDD:

• Before any work, ensure that terminal command xcode-select -p points to the current Xcode version path. If not, assign correct version using -s option, like:
  sudo xcode-select -s /Applications/YOUR_XCODE.app/Contents/Developer

• Install free “Injection for Xcode” app (remember to install version with TDD support) from official site and run it. Note that application sits only in the tray.
• Integrate InjectionTDD framework to your test target (CocoaPods, Carthage and manual installations are supported). If you use CocoaPods, it’s a single line change:

target 'YourAppTests' do  
  pod 'InjectionTDD', '~> 0.5'
end

• Start your unit tests (⌘+U) on a simulator. After a while, Xcode console should print confirmation Connected to “Injection” plugin, ready to load x86_64 code:

• We are ready to edit and save any of your implementation .swift file and click on “Inject Source” option in the Injection menu tray (or use shortcut ⌃=).

InjectionForXcode starts magic and after a while you should see tests results in the console output and Test navigator (⌘+6) 🎉.

• Optionally: you can enable “File Watcher” in the tray menu so that injection happens automatically, whenever you save a file. This is really handy.
• Optionally: by default test results are printed to the console, but if you want to also present notification summary (as below), install custom Xcode breakpoints to achieve the same result (see manual):

How does it work under the hood?

If you are interested in the implementation details, here are four stages that happen whenever you introduce a change to the implementation file:

1. lookup of all test target files to find tests cases that directly call code from the implementation file: uses Swift’s metadata files .swiftdeps, (.swiftdeps describes which Swift symbols given file provides and depends on),
2. compile your swift project target using incremental build (commands are parsed from Xcode logs) and bundle it into a .framework,
3. send just compiled binary to the simulator process: iOS simulator app loads from a disk dynamic framework,
4. execute all XCTestCases on a simulator.

One tool fits all

Contrary to Objective-C, which depends on message dispatching, Swift uses also static dispatch, what makes runtime method swizzling impossible. However, for InjectionTDD is not a case, where implementation and unit tests are bound together in a linking process so that unit tests always point to up-to-date implementation. In other words, XCTestCases are tightly coupled (by the time of compilation) with a unique type that is under test.

Therefore, you can test all kinds of Swift types with all dispatching mechanisms: classes, final classes, structs, enums etc.

Best practices

By default, InjectionTDD framework stalls execution of all tests and waits for injected tests. This is intended during development, but on a CI machine we want to normally execute all tests and never expect any injected tests. If you are afraid that integrating InjectionTDD framework only locally is an overkill, there is a remedy. You can control test execution (whether run them normally or wait for injection) by special flag in a scheme environment variable calledINJECTION_TDD_SKIP. If you set it to TRUE, all your unit tests will execute as normal:

Therefore, it is recommended to keep at least two schemes committed to a repo:

1. Used for building, where INJECTION_TDD_SKIP=TRUE
2. TDD development only (disabled INJECTION_TDD_SKIP env.)

Your CI building script always use the first scheme, developers may switch to the latter one while coding.

Hint: to speed up entire injection process, development TDD scheme (2.) shouldn’t gather Code coverage. It can cut off couple of precious seconds.

Summary

“Injection for Xcode” is a powerful and popular tool for live-updating your application in a runtime, especially when mastering UI details. Nowadays, it supports also unit testing in real-time that saves a lot of time and provides great integration with Xcode IDE.

Installation is really straightforward: download Injection app, integrate CocoaPods or Carthage library to your test target and get ready for great TDD experience!

Testing completion-handler API happy path scenario is really simple with XCTestExpectation. Things get complicated if your test case has to verify whether given handler was not called. It is still straightforward if it’s called synchronously after some other event that you emulate. But how about a case where execution is deferred in time? In this article, I will demonstrate you a solution to achieve 100% sure that given completion handler will never be called — fast and reliable.

Problem statement

Let’s talk about unit tests of some asynchronous task that provides completion handler — let’s say downloading JSON from a server. It seems obvious that we have to verify if a completion is called in a happy-path scenario. XCTest has nice API for that: just create an expectation, fulfil it in a completion and wait for all fulfillments at the end of a test:

I am pretty sure you saw such kind of tests plenty of times.

However, I don’t see that much test scenarios where we check that something did not happen. One example regards initiating download task that is invalidated/cancelled before it actually finishes (succeeds or fails with an error). At glance, there is nothing wrong with simple XCTFail() in a completion that shouldn’t be called. In case something was wrong (presumably due to a bug), we will have a change to fail current test and see red test in Xcode or CI. But is it really enough? What would happen if our Downloader defines@escaped callback and calls its later e.g. in DispatchQueue.async block?

Deferred execution of unexpected handler (Completion Inquisition)

Just to remind you, unit test always uses main thread to operate and after it reaches the end of a function, it is immediately classified as failed (red) or passed (green). Therefore, deferred execution of XCTFail() does actually log some failure but Xcode is not able to determine which previous test it actually corresponds to. If you are lucky, you will see errors inXcode console, but your entire test will be still green:

Test Suite 'All tests' passed at 2017-09-05 18:44:31.858.

Executed 3 tests, with 0 failures (0 unexpected) in 0.209 (0.215) seconds

2017-09-05 18:44:31.865211+0200 NotCalledUnits[66089:3985807] *** Assertion failure in void _XCTFailureHandler(XCTestCase * _Nonnull, BOOL, const char * _Nonnull, NSUInteger, NSString * _Nonnull, NSString * _Nullable, ...)(), /Library/Caches/com.apple.xbs/Sources/XCTest_Sim/XCTest-13188/Sources/XCTestFramework/Core/XCTestAssertionsImpl.m:41

2017-09-05 18:44:31.866778+0200 NotCalledUnits[66089:3985807] *** Terminating app due to uncaught exception 'NSInternalInconsistencyException', reason: 'Parameter "test" must not be nil.'

*** First throw call stack:

(

0   CoreFoundation                      0x000000011184626b __exceptionPreprocess + 171

1   libobjc.A.dylib                     0x000000010dfa4f41 objc_exception_throw + 48

2   CoreFoundation                      0x000000011184b402 +[NSException raise:format:arguments:] + 98

3   Foundation                          0x000000010da81bd3 -[NSAssertionHandler handleFailureInFunction:file:lineNumber:description:] + 165
...
...
...

Naive solution

Another approach is to wait a bit and assume that as long completion did not pop up within, let’s say 0.1s, is will never be executed. It has two obvious cons:

• You have to guess how long to wait. Should it be 0.1s or 0.01s? If you set it incorrectly, it can easily end up with invalid or unstable tests.
• It increases single test duration which by default should be as quick as possible by default.

Both drawbacks may lead to a dangerous trap:

When your tests take too long or are unstable, your teammates (or future you) start ignoring them and sooner or later just ditch them.

One possible solution

Let me ask you a question: when do you have 100% sure that some external part of your system will never call a completion? Answer: In a case when no one keeps holds a completion block anymore!

To verify that nothing deferred execution of a block, we have to ensure that all other instances lost reference to a completion. OK, Sounds easy!

But how to implement it? Of course we cannot define weak reference to a block: ‘weak’ may only be applied to class and class-bound protocol types. So, let’s define simple class ReferenceObserver that just notifies its deinit:

Then, let’s modify a bit our previous test: initalize observer , bind its deallocation handler to fulfilling XCTest expectation (line 4) and capture reference inside our unexpected completion handler (line 8):

At the moment we have exactly two references to our ReferenceObserver instance: reference and capturedReference (in a completion). Note: we had to add dummy assignment to an anonymous variable _, otherwise Swift would not capture it at all.

As you can expect, let’s get rid of one of helper reference (just callreference = nil) and voilà:

Only completion handler block keeps reference to ReferenceObserver and once completion handler is removed from a memory, deinitCompletion expectation automatically becomes fulfilled:

Here is our final test:

We ended up with a solution that:

• does not unnecessary increase test duration because waitForExpectations quits immediately, after ReferenceObserver deinit.
• ensures that completion will never be called.

You may be wondering, what does 0.1s mean at the end of this test? It is just a maximum interval you let Downloader instance to clear its handler reference.

Alternative notation

If you are like me, and you don’t like optionals in your codebase even in your unit tests, you can leverage additional scope to get rid of ReferenceObserver? optional type. Did you know that you can create a do section without any catch, and it creates only an extra scope? If we init our ReferenceObserver in a dedicated scope, its reference will be deleted at the end of it and thus we can remove an optionality. Once //Arrange section ends, the only one reference to an observer will be attached to a downloader. Below notation is equivalent to a previous code:

The price that we have to pay here is readability. Some developer, non familiar with an empty do scope construction, may not understand what and why it actually occurs here. Therefore, despite my general reluctance to an optional, I would choose previous notation with ReferenceObserver?due to its readability and clearness.
What is your opinion on this? Do you agree with me? You can comment below or catch me on twitter, @norapsi .

Sidenote
At the end, let me here remind another golden rule about writing unit tests:

Every time you write a test, verify that if you modify implementation to simulate a potential bug, your tests will actually fail!

BTW. Such modified test is called a mutation test.

This is especially important for described above solutions. Please keep in mind that if you don’t correctly capture ReferenceObserver reference within a block, test may succeed false-positively.
If you are really afraid of it, you can add for instance an extra guard to a ReferenceObserver implementation and let it notify about deinit only after an explicit point in a test or manager reference lifetime by introducing extra scope using do{}. I would rather suggest to stick with a good-practice approach rather than adding an extra code. If you are interested, sample test with a safe-guard is available in this gist.

Summary

Presented solution suits very well for verifying “not-called” scenario that is fast and reliable. You may also find it useful to check whether something still keeps a reference to a block (with no reason) and potentially introduces memory leak.

Within couple of lines required to implement ReferenceObserver, you are finally sure that a given block will never be called without any delay. So now you can add this technique into you developer toolbox and protect yourself from unexpected Completion Inquisition.

Safety over simplicity

Swift language was designed with a focus on “safe by default” approach (do not confuse with “safe by design” — Swift does not prevents you from doing dangerous actions but only encourages for good practices). One of such incentive is a great support for sum and product data types, enum and struct, respectively. These types are great to limit number of potential states during compilation time so we don’t have to write any unit tests of cases that should never occur — you definitely prefer to never reach given state, rather than covering it with an obvious unit test.

Problem statement

Despite enums are super-powerful feature in our toolbox, you may find out that there is no simple and safe way to list all cases in an enum (I mean an enum without associated values, of course). I run into a problem of presenting UI picker with all potential states (modelled as an enum) that user could choose from. I needed just an array but Swift does not provide it out-of-the-box and swift-evolution proposal is still waiting for its turn for a review (detailed discussion and its history is available here).

Workarounds

Very often, Swift community suggests two workarounds to solve my problem (inspiration comes from https://theswiftdev.com/2017/01/05/18-swift-gist-generic-allvalues-for-enums/):

• make an enum representable by Int and increment a counter until you cannot anymore create a case:

• cast raw memory representation into an enum case

Both of those workarounds are not ideal: first assumes that developer assigns subsequent values (starting from 1 here) for all enums, while second solution may break when Swift changes enum memory representation (we still lack ABI stability in Swift).

In this post I wish to present another technique to list all of enum cases that is safe and independent of Swift implementation details .

TLDR;
To achieve that we can define dedicated RawRepresentable type for your enum and make this type expressible by String or Int literal. Keep in mind that if we try to initialise an enum using init(rawValue:), Swift takes all values of your RawRepresentable (that have corresponding case) one by one and compare it with your rawValue until finding equal value. Therefore, if we try to initialise with some rawValue that does not match any case, we will have a chance to gather all rawValues with corresponding enum inside == operator implementation.

Dedicated RawRepresentable type

Let’s define our goal: find an array with all cases of BestEnum that is represented by aString value:

Keep in mind that enum BestEnum: String is actually just a syntactic sugar for conforming to RawRepresentable protocol with RawValue = String. Let’s see how could we implement it manually:

We all love language features that generate boilerplate for us (other examples include: Codable protocol in Swift 4 and so awaited auto-synthesized Equatableconformance in Swift 5).

Unfortunately, for auto-conforming to RawRepresentable we can only use String or Int rawValues. If you try to use there your own type (let’s say enum BestEnum: TypeToBeAutoRepresentable), Swift compiler complains with:

raw type ‘TypeToBeAutoRepresentable’ is not expressible by any literal

Error message is actually a great hint and reveals that my previous statement that “only String and Int are possible” was invalid — it is enough that your type has to be expressible by a literal.

Fair enough, let’s define our new type that meets this requirement and call itBestEnumRaw. It has no special logic — it just stores String literal as a property value and allows to initialize it with no argument (I will discuss later why do we need dummyinit()):

If we now try to use this struct as a raw representation(enum BestEnum: BestEnumRaw), swift compiler still complains:

‘BestEnum’ declares raw type ‘BestEnumRaw’, but does not conform to RawRepresentable and conformance could not be synthesized

On the other hand, this error message is a bit misleading: our BestEnumRaw actually conforms to RawRepresentable, why does Swift suggest that conformance cannot be synthesized? Solutions is really simple: let’s conform to Equatable protocol and the error goes away:

So far, so good. Our code compiles and definition of our enum is self-explanatory:

Here comes a trick: let’s think what happens if you try to initialise BestEnum with some BestEnumRaw, let’s sayBestEnum(rawValue: BestEnumRaw())? Inference type says that a result of this expression is BestEnum?, so result of this expression should return someBestEnum case or nil, when provided rawValue does not correspond to any case. One may ask: how does Swift check if a given rawValue corresponds to an existing case? It just iterates over all cases and checks if its representable is equal to the value provided in an initialiser. Don’t be scared, it’s really simple. In our case it checks if:

• BestEnumRaw() == BestEnumRaw(stringLiteral:"my_case") ?
• BestEnumRaw() == BestEnumRaw(stringLiteral:"other_case") ?

Now it makes sense why does compiler complain when BestEnumRaw does not conform to Equatable protocol — otherwise it wouldn’t be able to compare both RawRepresentables and therefore impossible to create an enum with init(rawValue:).

Of course both comparisons return false so our initialiser fails and returnsnil. Nevertheless, we had a chance to catch all possible BestEnumRaw instance that actually have corresponding enum case. Ha! By having a list of all instance of raw representation, it is so trivial to create a list of all enum cases!

Catching all rawValues

So let’s add static variable all to our enum as a bucket for all rawValues:

and fill it whenever Swift observers comparison of non-trivialBestEnumRaw:

Do you remember that we have a dummy initializer of BestEnumRaw? Thanks to that if rawString == nil we know that it was not initialized from any literal so does not correspond to any enum.

Implementation is ready: we just need to call dummy initializer BestEnum(rawValue: BestEnumRaw()) and BestEnum.all contains String values of all cases 🎉

If you want to achieve an array of actual cases instead of Strings, just map them to a raw object and later flatMap to an enum.

Skip boilerplate code with third-party library

Solution described above is straightforward and you can implement it within couple of minutes for your enum (have a look on gist for a final code). However, if you feel it is cumbersome to implement custom RawRepresentable type for each enum, you can use third-party library EnumList that does it for you. EnumList provides generic struct that you can use as a RawRepresentable. Let me show you how we can define our sample BestEnum for EnumList:

Just use EnumListStringRaw<T> (or EnumListIntRaw<T>) as raw representable, where T defines a bucket struct to keep all rawValues. I suggest nested struct Values into your enum, so that fetching all values expression is self-explanatory: BestEnum.Values.all.

If you need to parse your enum into/from JSON, EnumList works perfectly with Codable protocol.

polac24/EnumList

Summary

This post describes how to solve particular problem to list all enum cases, which Swift does not provide out-of-the box. Even if you hardly ever need to use it, my aim was to encourage you to find some non-obvious workarounds before compromising Swift safety.

If you think that enum with incrementing Int rawValue is easier to implement, I want to warn you that it works nicely only for Int representation and it can be a trap for new developers not aware of continuous rawValues requirement. On the other hand, playing with withUnsafePointer is quite dangerous since compiler will not warn us if something has changed with in-memory representation— in such a case application would crash during runtime or worse.

Think twice if you ever have to compromise — Compilation-time safety first!

Update (03/19/18):

Great news! Swift 4.2 will include out-of-the box solution with auto-conformance for CaseIterable protocol that provides allCases colletion. Credits go to Robert Widmann for implementing SE-0194.

More info here.