Most iOS architectural patterns rely on protocols to define what data and behaviors (i.e. interfaces) will be available to client code. This is a perfectly workable approach, but it adds quite a bit of overhead in terms of creating the protocol and multiple conforming types.

For example:

protocol AuthenticationProvider { 
  var isAuthenticated: Bool { get } 
  var authToken: String? { get } 
  var authError: Error? { get } 
  func logInWithCredentials(_ credentials: Credentials) 
  func logOut()
}

This protocol minimally needs to be adopted two times: once for the actual production functionality, and once by a mock type for testing:

class AuthenticationManager: AuthenticationProvider { 
  var isAuthenticated: Bool 
  var authToken: String? 
  var authError: Error?

  func logInWithCredentials(_ credentials: Credentials) {
    // Add _production_ implementation 
  }

  func logOut() {
    // Add _production_ implementation 
  }
}

class MockAuthenticationManager: AuthenticationProvider { 
  var isAuthenticated: Bool 
  var authToken: String? 
  var authError: Error?

  func logInWithCredentials(_ credentials: Credentials) {
    // Add _mock_ implementation 
  }

  func logOut() {
    // Add _mock_ implementation 
  }
}

So at a bare minimum, this approach requires the creation of three significantly redundant types in order to use.

Now let’s contrast with a model-defined interface approach. Instead of declaring a protocol that must be conformed to, we declare the same data and behaviors as a model struct. Instead of having protocol methods, the struct contains closures that can be invoked:

struct AuthenticationModel { 
  let isAuthenticated: Bool
  let authToken: String?
  let authError: Error?
  let logInWithCredentials: (Credentials) -> Void 
  let logOut: () -> Void
}

Here there is no need to conform to a protocol or define redundant concrete types. Instead for a screen or class that depends on this model, the production code can pass in an instance with “real” closures and values, while test code can simply initialize the struct with mock values and closures like this:

let mockAuthenticationModel: AuthenticationModel =
  .init(isAuthenticated: false,
        authToken: nil,
        authError: nil,
        logInWithCredentials: { loginExpectation.fulfill() },
        logOut: { XCTFail("Incorrectly called logOut") })

testSubject = .init(authmodel: mockAuthenticationModel)

So we can see that model-defined interfaces immediately reduce redundancy and the number of types which must be defined. However, this is just the beginning and a relatively minor benefit. The most important benefits of model-defined interfaces are compiler-enforced safety, reduction in test cases and defensive code, and self-documenting API.

Compiler-Enforced Safety

Looking at the AuthenticationModel example above, you might notice some potential for misuse or undefined behavior. Specifically:

• What happens if you call logOut() when the user is already logged out?
• What happens if you call logInWithCredentials() when the user is already logged in?

In fact, when it comes to authentication functionality, we don’t want to allow either of these possibilities to even happen at all!

And these sorts of cases are where model-defined interfaces really shine. Here is how we can adjust our model to more accurately represent the safe usage of this API:

enum AuthenticationModel { 
  case authenticated(Authenticated) 
  case notAuthenticated(NotAuthenticated)  

  struct Authenticated {
    let logOut: () -> Void
  }

  struct NotAuthenticated {
    let logInWithCredentials: (Credentials) -> Void
  }
}

We have now made AuthenticationModel an enum with two distinct states or cases: .authenticated and .notAuthenticated. Note that the logOut closure only exists in the .authenticated state, and the logInWithCredentials closure only exists in the .notAuthenticated state. Because of this definition, it is now impossible for a developer to mistakenly invoke a closure in the wrong state because the compiler itself won’t allow it!

This kind of contextual API surface is simply not possible to express using protocols!

Reduction in Test Cases and Defensive Code

Beyond the potentially unsafe behaviors we were able to clean up above by limiting their existence only to the correct state, there are more potential issues you may have noticed with our original protocol:

protocol AuthenticationProvider { 
  var isAuthenticated: Bool { get } 
  var authToken: String? { get } 
  var authError: Error? { get } 
  func logInWithCredentials(_ credentials: Credentials) 
  func logOut()
}

Specifically, we have a few properties that suggest implicit but not documented rules. For example:

• There is an optional authToken property, which should probably be nil when isAuthenticated == false and should probably never be nil when isAuthenticated == true.
• There is an authError property, which should conversely never be nil whenisAuthenticated == true, since authentication was successful and so shouldn't have resulted in an error!

These are in addition to the already noted implicit rules that

• If isAuthenticated == true the logInWithCredentials() method should be ignored
• If isAuthenticated == false the logOut() method should be ignored.

In a typical protocol-based approach, these implicit rules would need to be enforced through test cases and defensive code. For example, defensive code would look something like this:

class AuthenticationManager: AuthenticationProvider { 
  var isAuthenticated: Bool 
  var authToken: String? 
  var authError: Error?

  func logInWithCredentials(_ credentials: Credentials) {
    guard !isAuthenticated else { return } // <-- Defensive code to early exit if called in wrong context
    // Perform actual log in here
  }

  func logOut() {
    guard isAuthenticated else { return } // <-- Defensive code to early exit if called in wrong context
    // Perform actual log out here
  }
}

and example test cases might look something like this:

// If we log in with valid credentials we should be authenticated and should have a token
func testAuthTokenIsNotNil() {
  let authentication = AuthenticationManager()
  authentication.logInWithCredentials(.validTestCredentials) // We pass in valid credentials
  XCTAssertTrue(authentication.isAuthenticated) // We expect authentication to succeed
  XCTAssertNotNil(authentication.authToken) // If authentication succeeded the token must not be nil
}

// If we attempt login with invalid credentials we should not be authenticated and should NOT have a token
func testAuthTokenIsNil() {
  let authentication = AuthenticationManager()
  authentication.logInWithCredentials(.invalidTestCredentials) // We pass in invalid credentials
  XCTAssertFalse(authentication.isAuthenticated) // We expect authentication to fail
  XCTAssertNil(authentication.authToken) // If authentication didn't succeed the token MUST be nil
}

// If we log in with valid credentials there should not be any error
func testErrorIsNil() {
  let authentication = AuthenticationManager()
  authentication.logInWithCredentials(.validTestCredentials)
  XCTAssertTrue(authentication.isAuthenticated) // We expect authentication to succeed
  XCTAssertNil(authentication.error) // If authentication succeeded the error property should be nil
}

It's worth pointing out that the defensive coding and test cases needed to validate these implicit rules would need to be implemented for every type that conforms to the protocol!

Let's finish converting this protocol-defined interface to a model-defined interface and see what happens:

enum AuthenticationModel { 
  case authenticated(Authenticated) 
  case notAuthenticated(NotAuthenticated)  

  struct Authenticated {
    let authToken: String
    let logOut: () -> Void
  }

  struct NotAuthenticated {
    let error: Error?
    let logInWithCredentials: (Credentials) -> Void
  }
}

Note how we have added the error and authToken properties to only the appropriate context. And the isAuthenticated property is itself replaced by the enum cases of .notAuthenticated and .authenticated. What does this achieve? Well since it is no longer possible to even attempt to access the authToken or call logOut() in a .notAuthenticated state, we can remove all defensive coding associated with validating the implicit rules. The same goes for accessing error or calling logInWithCredentials() in an .authenticated state. And beyond removing any defensive code, we can also remove the test cases that validated these implicit rules as well, since invalid combinations of property values and states are now impossible.

In essence, we have moved implicit rules that had to be tested and checked in defensive code into explicit rules defined in the types themselves. Which again allows the compiler to enforce them rather than requiring humans to remember and correctly handle these rules manually.

For just this simple example converting the protocol-defined interface into a model-defined interface with two distinct cases would allow us to remove at least 8 units tests and associated defensive code:

• When authToken should / should not be nil
• When error should / should not be nil
• When logOut can / can't be called
• When logInWithCredentials can / can't be called

For readers who are familiar with Algebraic Data Types, it is mathematically demonstrable that these kinds of enum-based models require fewer test cases. Here's a brief explanation of how:

A struct is called a Product Type. This means that the total number of distinct values or variations of a struct type can be calculated by multiplying the possible values of its properties (the product of all its properties). So, for a struct like this:

struct AuthenticationModel {
  let isAuthenticated: Bool // <-- Bool has 2 possible values
  let authToken: String? // <-- String? has two possible values: .none or .some (not counting associated values)
  let error: Error? // <-- Error? has two possible values: .none or .some (not counting associated values)
}

// Multiply the possible distinct values of each property and you get 2 x 2 x 2 = 8 *minimum* possible variations of AuthenticationModel (again, not counting the associated String and Error values themselves)

With a minimum of 8 distinct combinations of properties, you would need to write a minimum of 8 unit tests to validate the proper combinations.

Now let's look at the enum version. An enum is called a Sum Type. This means that the total number of distinct values of that type can be calculated by adding together its cases (the sum of all its cases). So for the enum version:

enum AuthenticationModel { 
  case authenticated(Authenticated) // 1 case
  case notAuthenticated(NotAuthenticated) //  1 case

  struct Authenticated {
    let authToken: String
    let logOut: () -> Void
  }

  struct NotAuthenticated {
    let error: Error?
    let logInWithCredentials: (Credentials) -> Void
  }
}

// Add the cases and you find that there are 1 + 1 = 2 *minimum* possible variations of AuthenticationModel. Because we have removed optionality from authToken, even if we count the 2 possible values for error in the NotAuthenticated associated value struct, we still have a *minimum* of only 1(.authenticated) + 1(.notAuthenticated) * 2 (possible values for .notAuthenticated: 1 with .some error and 1 with .none error) = 3 distinct cases to test.

This is oversimplified and a little hand-wavy in the interest of simplicity and brevity, but hopefully you can see the mathematical pattern at play which suggests that simply by removing possible combinations of different properties in a struct and replacing them with fewer properties in distinct enum cases we are in fact provably reducing the minimum number of test cases which should be written for our model!

But wait, there's more — a final important benefit of enum-based models that simply cannot be matched by protocol-defined interfaces...

Self-Documenting API

If you've been coding for iOS for a few years, you know how painful certain APIs can be due to implicit, often unknown rules about what methods can be called at what time and in what order. Some classic examples:

• UIViewPropertyAnimator is a perfect example of the unsafe APIs we've been addressing. Its state property has three possible values (.active, .inactive, and .stopped) and depending on which is current, the different methods you call on the animator will either work correctly or crash the app. For example, you should not call startAnimation() if the state is .stopped and if you do the app will crash. Unfortunately, if you've used this API before you know that the only way to fully discover all the implicit "rules" is through trial and error or trying to find good 3rd party blog posts about it.
• UITableView can be triggered into a variety of crashes if you call insertRows(), deleteRows(), etc. without first calling beginUpdates() and without finishing with endUpdates(). But there is no self-documenting aspect to the code which suggests at all that beginUpdates() should be called first and that endUpdates() should be called at the end.

Ultimately in both of the above examples (and many many more in both Apple and non-Apple APIs), what the developer is faced with is a long list of methods which will be suggested by autocomplete and can be called at any time. It's very difficult to understand which methods are safe or appropriate to call at a given time. Similarly, there are many properties which may be irrelevant or unpopulated in the the current context of an API, yet they are still all listed by autocompletion and accessible to call, which creates a higher amount of noise to signal and can cause confusion.

Enter once again model-defined interfaces and enum models!

We've already covered how this pattern increases safety and reduces the need for defensive coding and the number of required test cases. But as a last note, we will also examine how it takes self-documenting code to a whole new level and makes things much easier and clearer for developers.

Let's start with a simplified representation of the API for Apple's UIViewPropertyAnimator:

enum AnimationState {
  case inactive
  case active
  case stopped
}

protocol UIViewAnimating {
  var state: AnimationState { get }
  var isInterruptible: Bool { get set }
  func startAnimation()
  func stopAnimation()
}

And here are some of the implicit rules:

Unfortunately, these rules have only spotty documentation and require research or trial-and-error to discover. And the code / API itself is not at all self-documenting in regards to these rules.

So as an experiment let's conceive of a refactor to this API to make it an enum model:

enum UIViewPropertyAnimator {
  case inactive(Inactive)
  case active(Active)
  case stopped(Stopped)

  struct Inactive {
    let startAnimation: () -> Void
    var isInterruptible: Bool // Gettable and settable
  }

  struct Active {
    let isInterruptible: Bool // Gettable / read-only so never crashes
    let startAnimation: () -> Void
    let stopAnimation: () -> Void
  }

  struct Stopped {
    let isInterruptible: Bool // Gettable / read-only so never crashes
  }
}

By converting this API into an enum with explicit states, we have managed to make most of these rules self-documenting (what is valid or safe to call in each state is made clear by the types themselves), and autocomplete will never suggest or show an invalid or unsafe property or method for the current state of the animator!

This makes it much easier and clearer for developers to understand and use. Comparing for example, an animator in the .stopped state, the protocol-defined version of the API would expose 2 properties (state and isInterruptible) and 2 methods in the list of members provided by autocomplete, and the compiler would allow a developer to invoke any of them. However, one method would do nothing in this state, the other method will cause a crash, and 1 property would cause a crash if set! Therefore 75% percent of the exposed API is non-functional or downright unsafe to use.

Looking at the enum model version of the same API, the .stopped case only exposes a single isInterruptible property in a read-only form which is safe. The unsafe methods and the ability to attempt to set the isInterruptible property don't even exist, will not show up in autocomplete and will not compile if called. So the developer clearly sees the only available information in this state, and the code self-documents the unsafe or non-functional members by removing them entirely in this context!

Implementation Details

Some readers may have wondered "if all of these model behaviors return Void, how are changes to the model received?" This is a key implementation detail for the model-defined interface approach: it is ideally suited specifically to reactive code with unidirectional data flow. In practice, consumers of the API would depend on a publisher of instances of the model, for example:

struct AuthenticationView: View {
  @State var model: AuthenticationModel
  let modelPublisher: AnyPublisher<AuthenticationModel, Never>
  var body: some View {
    VStack {
      switch model {
        case .authenticated(let authenticated):
          Text("Authentication token: \(model.authToken)")
          Button("Log Out", action: { model.logOut() })
        case .notAuthenticated(let notAuthenticated):
          if let error = notAuthenticated.error {
            Text("Error: \(error)")
          }
          Button("Log In", action: { notAuthenticated.logInWithCredentials(.valid) })
      }
    }.onReceive(modelPublisher) { model = $0 }
  }
}

So it is up to some external code to publish a stream of the AuthenticationModel which can be consumed by the view. That same external code would populate the different behavior closures within each instance of AuthenticationModel (like the logOut closure). Those closures would perform some logic and then result in a new value of AuthenticationModel being published to the stream.

Summary

So in summary, model-defined interfaces are a reactive, unidirectional pattern for building safe, self-documenting and less redundant APIs. And they reduce the number of test cases and amount of defensive coding required as well! When compared to a tradition protocol-defined interface approach, they provide more benefits and less drawbacks across the board!

Further Exploration

If you're interested in seeing concrete example applications using model-defined interfaces and an architecture built from the ground up around this paradigm, check out Source Architecture on Github! And as always feel free to contact me with your questions or comments (or leave them below)

Having been an iOS developer at quite a few tech companies, from small to large, I’ve found that they all mostly share the same painful reality of software development:

• Lots of fragile legacy code that is risky to refactor or update because it is untested
• Tests can’t be written for legacy code because what it even does (and why) is unknown. Plus, since it doesn’t have tests in the first place it is usually not written to easily allow for testability at a later date.
• Tests (usually unit tests) written for new / recent code rarely or never catch actual bugs. Emphasis is placed on writing these tests, but the return on investment is questionable since even with thousands of tests run continuously, roughly the same volume of bugs occur in production as existed before the thousands of tests.
• When refactors or changes to recent code are needed, the unit tests usually end up having to be modified, rewritten, or simply turned off, since they are usually too tightly coupled to a specific implementation.
• Eventually this recent code, with its disabled, short-circuited or reduced-coverage tests turns into legacy untested code that is fragile and risky to refactor, starting the cycle again.

Typically, software teams to solve this vicious cycle with the “enforcement of testing” approach, which looks something like:

a. All PRs must have tests with them , and / or
b. Code coverage percentage must not be lowered with any new PRs.

This seems reasonable on the surface, except that this sort of mandate doesn’t really ensure good or meaningful testing. It’s easy to write a test that technically results in “coverage” but will never catch any bugs. This ends up just perpetuating the cycle above and does nothing to address legacy code either.

The underlying problem

The reason why this cycle is so hard to break is because the apparent problem (lack of tests) is not the real problem, but is merely a symptom of the real problem. Additionally, merely increasing the quantity of tests does not result in a well-tested codebase.

So what is the real underlying problem? It’s a lack of clear, documented, testable requirements for everything in the codebase.

Keep in mind that programming is a one-way hashing algorithm that turns requirements into source code. It is not possible to unhash source code back into the requirements that resulted in that code. Comments can be very helpful in illuminating motivations, but they are informal and prone to rot. Therefore, the process of programming is a lossy process that loses intent and context along the way, unless the intent and context (i.e. requirements) are explicitly persisted and maintained somehow.

Typically how this underlying problem manifests is when some individual developer is expected to:

1. Receive some vague, incomplete description of what to implement
2. Create a (hopefully) working implementation (and if it doesn’t work, hopefully it will be caught before it is released by QA or other internal testing)
3. Then invent their own tests to “provide code coverage” for the code they wrote.

Six months later, no one knows exactly how the code that developer wrote works or why it was written that way (including the developer themself!) and the best you could do is maybe try to search through JIRA looking for the ticket that described what the original request was (which doesn't include all the conversations, etc. that happened during development).

Or, maybe your team is really good and wrote out some sort of technical design doc in Google Docs or Confluence in advance. That's better, but not only is it decoupled and separate from the code itself (so may not be easy to find), but it starts becoming obsolete as soon as development starts due to workarounds, bug fixes, edge cases and more being discovered and implemented during development. Not to mention the iterative process of change that comes immediately afterwards which causes the code to change without the documentation itself being updated.

So to solve this whole mess, the missing ingredient of explicit, testable requirements needs to be introduced at every stage of development (grooming, iteration, bug fixes). And those requirements must be constantly in sync with the actual reality of the code, not maintained in a separate universe somewhere.

What is a good requirement?

First, let me be clear that I’m not advocating for long rambling requirements documents that are worked on for weeks before any code can be written. While that has many advantages over no requirements, it's a slow process that is just as prone to rapid obsolescence.

A good requirement is a conceptual rule or intent coupled with specific examples to demonstrate how it is expected to behave. The number of examples included for a rule should be as many as needed to capture every unique behavior of the rule. Examples are what makes a requirement testable. Requirements without examples are not testable.

Example of a bad requirement:

Debit card users shouldn't be able to overdraft

👆 This requirement is missing context and has no clarifying or testable examples

So let’s try to make it better:

Debit card charges should be denied if the amount of the charge is greater than the user’s available balance

👆 Much better context! But not yet testable as there are no examples, and we could ask many questions about edge cases that are not answered by this single statement.

Rule: Debit card charges should be denied if the amount of the charge is greater than the user’s available balance
- Example: Given the user has a $50 available balance, when a $51 charge is requested then the transaction should be declined.
- Example: Given the user has a $50 available balance, when a $49 charge is requested then the transaction should be approved

👆 This is the first implementable, testable requirement! It has the rule and specific examples that can be easily tested. To illustrate, look how straightforward it would be to write tests for this requirement:

func testOverdraftDeclined() {
   let mockAccount = MockAccount()
   mockAccount.balance = 50.00
   let testTransaction = Transaction(account: mockAccount)
   let result = testTransaction.charge(51.00)
   XCTAssertEqual(result, .declined)
}

Note that at this point, this probably isn’t a truly complete requirement, but it’s defined enough to start coding, testing and moving ahead incrementally.

During development or perhaps QA, someone might notice a scenario that was not accounted for in the original requirement: if the user’s account has a pending charge, it is possible for the a new charge to use money that should be been reserved for the pending charge, resulting in an eventual overdraft.

Therefore, the requirement gets updated to:

Rule: Debit card charges should be denied if the amount of the charge is greater than the user’s available balance minus any pending transactions
- Example: Given the user has a $50 available balance, when a $51 charge is requested then the transaction should be declined.
- Example: Given the user has a $50 available balance, when a $49 charge is requested then the transaction should be approved
- Example: Given the user the user has a $50 available balance and there is a $25 pending charge on the user’s account, when a $49 charge is requested then the transaction should be declined

Notice how requirements get more specific and comprehensive over time, iteratively. Also note that a developer, product manager, or QA analyst coming back to this code years later can see exactly how the code is supposed to work.

Keeping requirements in sync with code

Now that we’ve looked at what good implementable requirements look like the next questions are:

• Where do we keep them?
• How do we test them?
• How do we ensure they don’t grow stale and out of sync with the actual state of code?

There can be different answers to these questions, but I strongly advocate for one answer that addresses all three: Requirements should be kept in inside the repo alongside the code and automatically tested on every commit using a test framework like Cucumber or (shameless plug) my own TestKit.

Let’s break this down a bit: the requirements given above as examples are all written in the “Given, When , Then” format for describing a behavior. This loose structure for expressing requirements has been formalized into a standard called Gherkin. Gherkin is just a set of keywords and conventions for writing these kinds of example-based requirements. Because of the “standardized” nature of Gherkin, it can be parsed and fed into testing frameworks, which can then attempt to validate every statement in the requirements

The most common framework for testing Gherkin requirements is called Cucumber, but it isn’t particularly well maintained for iOS. However, Gherkin is a defined standard and so other frameworks can be written and maintained to test Gherkin requirements, such as my previously mentioned TestKit and others. These frameworks all essentially work the same way:

• They provide a way for test code to register certain blocks of functionality in response to requirements that match specified RegEx patterns. For example this code registers test behaviors that will run in response to the requirement phrase "Given the user has a $50 available balance":

  given(“the user has a $50 available balance”){
        testAccount = MockAccount()
        testAccount.balance = 50.00
  }
  

  This is how developers hook into requirements and "prove" each line in their test code. Because it uses RegEx, the registered test functionality can also be dynamic, e.g.

   given(“the user has a $(<balance>\d?) available balance”) {  
      guard let balance =$0[“balance”].floatValue else { 
          XCTFail(“Invalid balance in requirement”)
      }
      testAccount = MockAccount()
      testAccount.balance = balance  
  }
  

  This dynamic version will read any specified amount for the available balance out of a requirement and configure the mock account appropriately.

• They parse all requirements in a given file or folder

• If a requirement doesn’t have any test functionality registered to handle it, the test fails

• Each parsed line of every requirement has its associated test functionality invoked — in order — allowing tests to validate the requirements are true

There are all sorts of strategies and conventions to make this process as effective as possible (which I’ll be talking about more in future posts), but just looking at this basic setup it gives us the following benefits:

• Simply adding or changing a requirement in the project without having associated test code to prove it will fail the tests. This ensures that all requirements must be validated and tested at all times
• The test suite is ultimately based on high-level requirements, not implementation details, so tests are always able to validate successful refactors. Note that there may be implementation details in the registered test functions (like how to set a balance on a mock account), but these details are updated separately from the actual requirements, which the suite validates and which don't change due to refactoring.
• Any changes to the code which break a requirement will fail the tests. Any changes to the requirements which are not reflected in the code will cause the tests to fail as well.

In short, this approach brings us to the ideal state of requirements which are never out of sync with the code, and code which is never undocumented or diverged from requirements!

Bringing it all together

By using this requirements-driven approach to software development, we can finally achieve the sustainable process that has been so elusive. Once a codebase has been set up with a testing framework like Cucumber or TestKit (and has usable test setups for both UI tests and API (or “unit”) tests) it only requires one simple rule in order to keep the entire process working: “Requirements are always written before coding begins, and the first step to coding is updating the requirement”. This single rule ensures that testing occurs, documentation exists, developers are implementing the right thing, and refactors in the future will be safe and validated.

Note that bugs and bug fixes must follow this pattern as well. When tested requirements exist, a bug becomes simply a requirement example that wasn’t captured earlier. A bug is fixed by:
1. Adding the example to the requirements, including what should be the outcome of that example
2. Writing or fixing the code to validate that new example (while also continuing to meet all previously captured requirements and examples).

And thus the sustainable software development cycle looks like this:

• Product or QA (in the case of bugs) identify rules and examples that the product should follow (backlog)
• Product + Developers + QA ask questions and surface specific examples to identify how the rule should be followed for any possible scenario that is thought of (grooming). These examples are written as Gherkin requirements.
• Developers are assigned specific requirements to implement. The requirements are already captured in the project, the Jira ticket holds no requirements itself, just notes which previously decided requirements will be implemented. The requirements to be implemented ARE the tests, so the developer works on the implementation until all the requirements tests pass, which is when the ticket is done. Note that PRs can’t pass CI or merge until the developer has hooked up test functionality to prove the requirements.
• The cycle starts again and runs iteratively: based on user feedback or defects, product and / or QA provides new rules and examples which become requirements in the repo, and so on.
• When it comes time to complete refactor a portion of the application (say, from UIKit to SwiftUI), this can be done confidently knowing that all the same requirements that were used to defined all the existing code must also be validated against the new code as well.

Further discussion

While this basic arrangement really does provide a truly sustainable software development cycle, there are unsurprisingly devils in the details. I plan to address these in subsequent posts, but just to give proper acknowledgement to some of the key challenges:

• It requires a disciplined grooming process to translate all work into testable, example-based requirements. Ideally, this process would include product, QA and software engineers together in a discussion, asking questions and capturing rules and examples in Gherkin format (usually the best Gherkin-writer — often someone in QA or a developer — will translate the discussion into the actual Gherkin that everyone else give a thumbs up to). Similarly, it takes work with QA to translate bug reports into specific missing rules or examples.
• Writing good Gherkin to be plainly understandable and not overly implementation-focused takes practice. Additionally, Gherkin has a few conveniences and features that should be learned as well in order to facilitate the process. For example, tags can be used to limit requirements to certain platforms or OS versions, or to exclude new requirements from being tested until a ticket is in flight to implement those requirements, etc.
• Requirements are either focused on user experience (what the user sees) or API behaviors (what responses calling code will receive following method calls with certain parameter values, etc.). Testing both kinds of requirements means that the project needs to have basic testability in place for both code (i.e. mocks for unit tests, etc.) and UI (the ability to launch the app with various mock preconditions in place for when the UI is interacted with by test code).

I hope that the content in this article is nonetheless enough to get you started on the path to a well-tested, well-understood and sustainable project that can be maintained confidently without regressions!

Well, it leaves us free to think about how we can write good tests that are useful and practical! And the formula for that is very simple:

• Every feature, bug fix, coding task, etc. should have one or more clearly stated requirements. Not how this code is to be written, but what does this code have to do? Often, the requirement can be described from the perspective of the human who is using the app, e.g. “Tapping on the star should add this items to my list of favorites”. Requirements can also be described purely from a API perspective, e.g. “When there are already 100 favorites, adding an additional item to the favorites list should result in an error and no change to the existing favorites”.

• Each API requirement should be validated by an API test

• Each UI / user requirement should be validated by a UI test

• Every test should test the required behavior, not a specific implementation. If the implementation changes (whether the code underlying the API, or the layout or styling of elements in a UI), the tests should not need to change. In fact, the tests exist largely to validate that a change to the implementation still meets the same required behavior. So tests must only be concerned with the behavior, and not an implementation.

  For UI tests, this means validating and interacting with elements by identifier rather than looking them up by a specific screen or expecting a specific hierarchy. For API tests, this means that writing code and tests that address protocols / interfaces and abstractions, which can be explicitly passed mockable inputs, and validate explicit outputs (via mock expectations or return types) rather than digging into properties and internal state.

And that’s the entire formula. It’s kind of neat that the entire approach to testing (at a high level) can be boiled down to just these few points. But you’ll notice that every test you write using these simple principles will have value and align with the project objective. No time is spent writing tests that don’t validate an explicit requirement. Any deviation from required behavior (whether through refactor or the addition of new code) will cause tests to fail, easily proving their value. And as you gradually capture more and more and more of what your application does and needs to do as explicit requirements (more on that in an upcoming article), your test suite is giving you direct confidence that your code is meeting those requirements on every run.

Of course there is a lot more in the details (which we will continue to dig into with additional articles), but those details largely boil down to how to write good requirements, how to make tests more abstract (test the behavior, not the implementation), and perhaps some specific techniques for providing inputs and validating outputs.

There is a ton of room for creativity and mastery in these specific areas, and lots of work to do in capturing ALL the requirements of your app to test. Hopefully this starting point of a useful and practical approach to testing helps you focus on the parts that matter, and gets you the most bang for your testing buck!

Next up: We dive into details of how requirements and testing are part of sustainable software development “Creating a Sustainable ”