Forem: Ibrahima Ciss

Sign-in with Apple: from client to server-side validation

Ibrahima Ciss — Tue, 05 Apr 2022 11:39:40 +0000

I was working on an upcoming app called Charabia , and I needed some ways to log the user into the app. But I wanted that experience to be really smooth; I don't want to pop up a signup or login form. So I thought that Sign-in with Apple would be a good fit for that, so I added it plus the option to sign in with Google.
The logic is pretty simple. Once you tap on one of these buttons, you authenticate via the client SDK. For Sign in with Apple (or SIWA, I like to call it 😉), it's the AuthenticationServices framework that takes care of that, and for Google, I've installed the Google Sign-In Swift package. Once authenticated, both SDK will send you a token or authorization code you can send to your backend server for verification. That's the tricky part because it requires a lot of configuration beforehand in order to get all the different elements necessary for the validation. After a successful verification, depending on the user's existence in the database, we might create the user from the decoded pieces of information contained in the JWT token. If he doesn't exist yet, we create the record in the user table and send him back to the client with an access token he can use for subsequent requests on the RESTful API.
Let's see how to do all that in this article. I've separated this guide into three main sections:

Client side setup
Keys creation
Server-side validation

Excited? Let jump right into it without any further ado.

Client-side setup

Let's first start by creating the app. It's a single app that uses SwiftUI.

For the sake of simplicity, we'll use a single file, the ContentView, to host all of our code (and it shouldn't be long 😅). iOS 14 added a convenient way to sign in with Apple with a view named SignInWithAppleButton that is directly configurable via its initializer.



SignInWithAppleButton(
  label: SignInWithAppleButton.Label, 
  onRequest: (ASAuthorizationAppleIDRequest) -> Void,
  onCompletion: ((Result<ASAuthorization, Error>) -> Void)
)

The onRequest and onCompletion arguments are both closures, the first to configure the request and the second to process the result. I'll put these methods in a ViewModel to decouple the view from the logic. It looks like this:



import SwiftUI
import Combine
import AuthenticationServices


final class ViewModel: ObservableObject {

  func handle(request: ASAuthorizationAppleIDRequest) {
  }

  func handle(completion result: Result<ASAuthorization, Error>) {
  }

}


struct ContentView: View {
  @StateObject private var viewModel = ViewModel()

    var body: some View {
      VStack {
        Spacer()
        Text("👋 Hello SIWA")
          .font(.title)
        Spacer()
        SignInWithAppleButton(
          .continue,
          onRequest: viewModel.handle(request:),
          onCompletion: viewModel.handle(completion:)
        )
        .frame(height: 48)
      }.padding()
    }
}

For the authorization request, let ask for user email and the fullName.



func handle(request: ASAuthorizationAppleIDRequest) {
  request.requestedScopes = [.fullName, .email]
}

Go to the project settings and select your main target; in "Signing & Capabilities" tab, add the "Sign in with Apple" capability.

Now you can run the app. Note that you have to use a physical device to test SIWA; there is an unresolved bug since iOS13 simulators.
Anyway, it should look like this.

Once the button is tapped, you'll have the SIWA popup and you can either use your email or a private one that'll forward to your real email and set a name as well.
Be aware; this popup will appear only once before you accept it via Face-Id or Touch-Id; for subsequent login, you'll have another popup for authorization. Thus, if you want the user pieces of information like his name, you have to handle it the first time the popup is shown. But if you messed up, I will show you how you can later reset the popup and show it like it was the first time.
Now, once we accept (or deny), the handle completion method is fired, and we can send the authorization code provided to our backend for validation.



final class ViewModel: ObservableObject {

  func handle(request: ASAuthorizationAppleIDRequest) {
    request.requestedScopes = [.fullName, .email]
  }

  func handle(completion result: Result<ASAuthorization, Error>) {
    switch result {
      case .success(let authorization):
        guard let credential = authorization.credential as? ASAuthorizationAppleIDCredential,
        let tokenData = credential.authorizationCode,
        let token = String(data: tokenData, encoding: .utf8)
        else { print("error"); return }
        send(token: token)
      case .failure(let error):
        print(error.localizedDescription)
    }
  }

  private func send(token: String) {
    guard let authData = try? JSONEncoder().encode(["token": token]) else {
      return
    }
    let url = URL(string: "https://yourbackend.example.com/tokensignin")!
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")

    let task = URLSession.shared.uploadTask(with: request, from: authData) { data, response, error in
      // Handle response from your backend.
    }
    task.resume()
  }

}

That's all we need to do for our client. That's pretty simple, right. Now let's handle the public and secret keys configuration that'll help us validate the token generated by the client.

Keys Creation and configuration

Now let's create the keys (public and secret) we need to verify the client's authorization code.

Go to developer.apple.com and log into your account
Click on “Certificates, IDs & Profiles” on the left sidebar
Once the page loaded, go to the “Keys” menu to create a new key
Click on the “+” icon, then put the name of the key, I am going to call it siwatut
Check the “Sign in with Apple” checkbox and click on the “Configure” button
It’ll redirect you to a key configuration page, and you’ll see a select textfield for picking the app you want to create key. Choose you app and click on the “Save” button.
It’ll redirect you back to the key configuration page, now click on the “Continue” button
You’ll see a summary of key creation, click on “Register” to create the key
Now, step really important, you have to click on the “Download” button in order to save the key locally on your computer. I recommend to save it somewhere safe in your disk.
Rename the private key AuthKey_keyid.p8 to key.txt
Now, open your terminal and go to the location of key.txt
Install the JWT Gem with sudo gem install jwt
Once done, create a file called client_secret.rb to process the private key and open it in your favorite text editor
Put that content in it: ```ruby

require 'jwt'

key_file = 'key.txt'
team_id = 'your-team-id'
client_id = 'dev.ibrahima.siwa-tut'
key_id = 'your-key-id'

ecdsa_key = OpenSSL::PKey::EC.new IO.read key_file

headers = {
'kid' => key_id
}

claims = {
'iss' => team_id,
'iat' => Time.now.to_i,
'exp' => Time.now.to_i + 86400*180,
'aud' => 'https://appleid.apple.com',
'sub' => client_id,
}

token = JWT.encode claims, ecdsa_key, 'ES256', headers

puts token

- `team_id` can be found on the top-right corner when logged into your Apple Developer account
- `client_id` is our app’s bundle identifier
- `key_id` is the private key identifier created at step 9 above
1. Save the file, go back to your terminal and type the command
```bash


ruby client_secret.rb

If everything goes well, it should print a JWT token on the terminal.

Copy and save it somewhere in the meantime, and we will use it in our backend.
Now that we have generated our JWT token, let's process it in our backend to extract the pieces of information we need.

Server-side validation

For the backend, I’m going to use Laravel PHP framework. You can, of course, use any server-side framework (Express, Django, Rails, etc.) of your choice. I already have a fresh installation of Laravel.
Now I'll copy the token we generate earlier in the .env, an environment file like so:



SIWA_CLIENT_ID=dev.ibrahima.siwa-tut # your xcode bundle identifer used to generate the token
SIWA_CLIENT_SECRET= # the jwt token generated earlier
SIWA_GRANT_TYPE=authorization_code # used in the validation request

Now let's add an endpoint that the client'll hit. I'll go to the web.php route file, and I create a controller for handling the request.



// web.php
Route::post('tokensignin', [AuthController::class, 'handleSIWALogin']);



// AuthController.php

<?php

namespace App\Http\Controllers;

use App\Models\User;
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;
use Illuminate\Http\JsonResponse;
use GuzzleHttp\Exception\GuzzleException;


class AuthController extends Controller
{

    public function handleSIWALogin()
    {
        $authorizationCode = request()->input('token'); // 1
        $body = 'client_id=' . env('SIWA_CLIENT_ID') . '&client_secret=' . env('SIWA_CLIENT_SECRET') . '&code=' . $authorizationCode . '&grant_type=authorization_code';
        $client = new Client();
        $request = new Request("POST", "https://appleid.apple.com/auth/token", ["Content-Type" => "application/x-www-form-urlencoded"], $body); // 2
        try {
            $response = $client->send($request); // 3
            $data = json_decode($response->getBody(), true);
            $payload = json_decode(base64_decode(str_replace('_', '/', str_replace('-', '+', explode('.', $data['id_token'])[1]))), true); // 4
            if ($payload['email']) return $this->createOrLogUser($payload); // 5
            return $this->respondWithError("Could not authenticate with this token");
        } catch (GuzzleException $e) {
            return $this->respondWithError($e->getMessage()); // 6
        }
    }

    private function createOrLogUser($payload): JsonResponse
    {
        // create the user if he's not yet in the database or return him with (if he already exists) with a token and send it back to the client
    }

    private function respondWithError($message): JsonResponse
    {
        // return a json response representing an error
    }
}

Don't be intimidated by the code above, and it's pretty straightforward. Let's see the different steps needed to verify the token:

We retrieve the token sent by the client
We construct a request that'll be sent to Apple's server for authenticating the token. You'll find here the list of parameters
We send the request
If the request was successful, we extract the payload with the json_decode method in the id_token field
With the email extracted, we try to log the user or create him in the database, then send the authentication token to the client
If something is wrong, we return an error. The client should be logged in with the token generated by the backend that'll serve for authentication for the subsequent requests. You can print the authorization code on Xcode for testing purposes and make a post request to apple servers with all your credentials created earlier. The result should look like this:

Resetting Sign in with Apple authorization popup.

As I told you before, the authorization popup where you give your name and decide to share or use a private email will show once. After accepting, there will be another popup for subsequent authorization. I know that you might want to retrieve all the user data like his name for testing, but if you haven't done that the first time, you have no chance to do it later. You can reset the Sign in with Apple authorization popup by following these steps.

Go to the Settings app of your phone
Select your iCloud profile at the top
Go to "Password & Security"
Go to "Apps using Apple ID"
Select the concerned app and tap on "Stop using Apple ID" That's it. Next time you'll want to authorize, it'll bring you the original popup giving you the option to share or not your real email and to customize your name.

Final Thoughts

As you can see, validating the authorization code provided by Sign in with Apple isn’t difficult, it just requires some setup that can be tedious, I know 😔. For more informations, I recommend reading the docs about user verification and token validation from Apple docs:

Verifying a user
Token generation and validation Hope you find this article useful. Let me know if you have any questions on Twitter.

SOLID Principles in Swift: Open/Closed Principle

Ibrahima Ciss — Tue, 19 Jan 2021 12:21:36 +0000

Last week we revised the Single Responsibility Principle or SRP, today let's have a look at the Open/Closed Principle or OCP, which states: "Entities should be open for extension, but closed for modification." Let's break this definition down.

Entities, think of it as classes, structs or methods should be simple to change.
Closed for modification, we want to change that entity's behavior without modifying its source code. This can be really problematic. How the heck can we change the behavior of the entity without touching its source code? And that's when we come back to the term extension. We should think about extensibility while writing our entities.

Committing the sin

Without any further ado, let see an example of this principle being applied hoping it’ll click for you.
For that, let’s imagine we have a Square class with its properties like so:

class Square {

  private(set) var width: Double
  private(set) var height: Double

  init(width: Double, height: Double) {
    self.width = width
    self.height = height
  }

}

Now, we say that we want to calculate the total area of squares. If we follow the Single Responsibility Principle, we might create a separated class that is dedicating to calculate that area:

class AreaCalculator {

  func calculate(squares: Square...) -> Double {
    return squares.reduce(0) { $0 + $1.width * $1.height }
  }

}

If we run this, it works flawlessly:

let square1 = Square(width: 10, height: 10) // 100
let square2 = Square(width: 20, height: 20) // 400
let square3 = Square(width: 30, height: 30) // 900

let calculator = AreaCalculator()
calculator.calculate(squares: square1, square2, square3) // 1400

Now let's say we want to calculate the circle's areas as well. Our first thought might be to create a Circle class.

class Circle {

  private(set) var radius: Double

  init(radius: Double) {
    self.radius = radius
  }

}

In the code above, we notice that we call everything square (in the AreaCalculator class) because we didn't think about the possibility that we'll need to calculate the area for anything other than a square. So we'll have to edit the original AreaCalculator class, meaning we broke the Open/Closed Principle.
Let's see how to change the behavior of the calculate method before refactoring it.

class AreaCalculator {

  func calculate(shapes: AnyObject...) -> Double {
    var totalArea: Double = 0
    for shape in shapes {
      if shape is Square {
        let square = shape as! Square
        totalArea += square.width * square.height
      }
      if shape is Circle {
        let circle = shape as! Circle
        totalArea += circle.radius * circle.radius * Double.pi
      }
    }
    return totalArea
  }

}

Swift being a static language, the calculate method has to accept an array of AnyObject, then we manually check the type of the object.
And if we run now the code, we have something like this:

let calculator = AreaCalculator()

let square1 = Square(width: 10, height: 10) // 100
let square2 = Square(width: 20, height: 20) // 400
let square3 = Square(width: 30, height: 30) // 900
let cirlcle1 = Circle(radius: 10) // 314.15926
let cirlcle2 = Circle(radius: 20) // 1256.6370

calculator.calculate(shapes: square1, square2, square3, cirlcle1, cirlcle2) // 2970.79632

Like we said above, we clearly break the Open/Closed Principle by doing this. The AreaCalculator is opened for modification when it should be closed. However, you might be thinking, oh no, it's not a big deal, add a few if statements, and you're done, don't worry about this principle. Ok, fair enough, but let say we also need to calculate the area of a triangle, kite, hexagon, pentagon, and some other …gon shapes (screwed right 😅). Do you think we need to add endless if statements in the calculate method every single time we make a change? Of course no. But now, what can be the solution to make the AreaCalculator closed for modification 🤔?

Coding to an interface (or protocol): the cure

In order to extend the behavior of the AreaCalculator while keeping it closed for modification, we need to separate that behavior behind an interface (or protocol in Swift) and then flip the dependencies around, as Uncle Bob said. It can be a little tricky at first to get this, but let's break it down step by step.

Separating the external behavior behind an interface

To do that, we’ll create a Shape protocol like so:

protocol Shape {
  var area: Double { get }
}

The nice thing about Swift is we can have properties in Protocols or interfaces and this particularly reads well: a Shape has an area 😁
Now we need to implement or to conform to that interface in each concrete class.

class Square: Shape {

  private(set) var width: Double
  private(set) var height: Double

  var area: Double {
    return width * height
  }

  init(width: Double, height: Double) {
    self.width = width
    self.height = height
  }

}


class Circle: Shape {

  private(set) var radius: Double

  var area: Double {
    return radius * radius * Double.pi
  }

  init(radius: Double) {
    self.radius = radius
  }

}

Step 1 is done, let’s focus on step 2 now.

Flip the dependencies around

To do so, rather than accepting an AnyObject array in our calculate method, we’ll accept an array of Shape.

class AreaCalculator {

  func calculate(shapes: Shape...) -> Double {
    return shapes.reduce(0) { $0 + $1.area }
  }

}

Because we code to an interface and implement it to the Square and Cercle classes, we're 100% sure that they'll have an area property. We simply use it to calculate the sum of all shapes' area.
This is really powerful because if we need to calculate a triangle's area, for instance, we'll just have to create the Triangle class, make sure that it conforms to the Shape protocol, then set the area property along with the formula for calculating the area of a triangle, and we pass that into the calculate method of AreaCalculator.
Notice that we never ever touch the AreaCalculator class again because it already knows how to calculate shape areas.

Conclusion

As a developer, we should strive to write collaborative code. What I mean by that is we should help our fellow colleague or friend to be able to extend the functionality of a system without needing to modify the source code of any existing classes. Yes, it can be difficult at first glance, but by applying these S.O.L.I.D. principles, we can achieve this goal easier. I hope this example makes something click for you for your understanding of the Open/Closed Principle. Next, we'll have a more in-depth look at the Interface Segregation Principle; until then, have a nice week, and may the force be with you 👊.

SOLID Principles in Swift: Single Responsibility Principle

Ibrahima Ciss — Mon, 11 Jan 2021 10:04:29 +0000

This week, let’s revise the S.O.L.I.D. principles and have an in-depth look at the first and probably most well-known principle: the Single Responsibility or SRP.
This principle states: A class should have one, and only one reason to change. I think this definition can be a little bit abstract for some. Think of it this way: An object should only have a single reason to change (this doesn’t help either 😭) or ** A class should exactly have just one and only one job** (much better 😁) or ultimately A class should only have a single responsibility.
Violating this principle causes classes to become more complex and harder to test and maintain. However, the challenging part is to see whether a class has multiple reasons to change or if it has many responsibilities.

Committing the sin:

I'm going to give an example in the iOS world where we see a view controller having more than one responsibility. It's a mistake many young developers make in their first days as an iOS Developer. And generally in a MVC architecture, the controller is the place where we throw a lot of unrelated things because I guess it's easier and more convenient to stay at one place and see all the code associated with that particular controller.

final class LoginViewController: UIViewController {

  private var emailTextField: UITextField!
  private var passwordTextField: UITextField!
  private var submitButton: UIButton!

  // initializers...

  override func viewDidLoad() {
    super.viewDidLoad()
    setupView()
  }

  private func setupView() {
    // ... other view related code here
    submitButton.addTarget(self, action: #selector(submitButtonTapped), for: .touchUpInside)
  }

  @objc private func submitButtonTapped() {
    signinUser(email: emailTextField.text ?? "", password: passwordTextField.text ?? "")
  }

}

This is straight forward, a simple login screen with two text fields: an email and password fields and a submit button. When the button is tapped, we try to log the user in. This seems to be perfectly okay until we add the remaining methods.
We're going to put them in an extension like this:

extension LoginViewController {

  // 1
  private func signinUser(email: String, password: String) {
    let url = URL(string: "https://my-api.com")!
    let json = ["email": email, "password": password]
    let jsonData = try! JSONSerialization.data(withJSONObject: json, options: [])
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.httpBody = jsonData
    request.addValue("application/json", forHTTPHeaderField: "Content-Type")
    request.addValue("application/json", forHTTPHeaderField: "Accept")

    let task = URLSession.shared.dataTask(with: request)  { (data, response, error) in
      if let error = error {
        DispatchQueue.main.async {
          self.showErrorAlert(message: error.localizedDescription)
        }
      }
      guard let data = data else {
        self.showErrorAlert(message: "sorry, could not log in, try later")
        return
      }
      // 2
      let user = try! JSONDecoder().decode(User.self, from: data)
      self.log(user: user)
      DispatchQueue.main.async {
        self.showWelcomeMessage(user: user)
      }
    }
    task.resume()
  }

  private func showErrorAlert(message: String) {
    // logic to show an error alert
  }

  private func showWelcomeMessage(user: User) {
    // logic to show a welcome message
  }

  // 3
  private func log(user: User) {
    // log user logic
  }
}

We can see the controller violates the SRP because we write some methods that are responsible for very different things.

The signinUser method is responsible for making a network call and tries to log the user in
Still in the signinUser, we try to convert the data we get from the API call to a domain object, a User in our example
We have a log method that'll probably log the user's information to a remote service.

By putting the code for these methods and actions into the LoginViewController class, we have coupled each of these actors to the others, and we can now see the controller has more than one responsibility. If we refer to Apple documentation, a view controller's main responsibilities include the following:

Updating the contents of the views, usually in response to changes to the underlying data.
Responding to user interactions with views.
Resizing views and managing the layout of the overall interface.
Coordinating with other objects—including other view controllers—in your app. Now let’s see how we can improve things and respect the SRP.

Refactoring: the cure

When we want our classes to respect the SRP, this generally means we must create additional objects that'll have a single responsibility and use different techniques to make them communicate with each other. Let's see how we can apply this in our example.
The first thing to do might be to extract the logic for performing an API request call to a separate object.

struct APIClient {

  func load(from request: URLRequest, completionHandler: @escaping (Result<Data, Error>) -> ()) {
    let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
      if let error = error {
        return completionHandler(.failure(error))
      }
      completionHandler(.success(data ?? Data()))
    }
    task.resume()
  }

}

The advantage of doing this is we now have a dedicated object that is only responsible for performing an API call and nothing else. Sweet, let's add another object for decoding the data from the API to a domain object.

struct Decoder<A> where A: Decodable {

  func decode(from data: Data) throws -> A {
    do {
      let object = try JSONDecoder().decode(A.self, from: data)
      return object
    } catch {
      fatalError(error.localizedDescription)
    }
  }

}

Again, we have a very simple object with a single responsibility: decoding data to a domain object.
Now let's add the final object responsible for logging the user.

protocol Loggable {
  var infos: String { get }
}

struct Logger<A> where A: Loggable {

  func log(object: A) {
    print("doing some logging stuff with \(object.infos)")
  }

}

You see in this example, all the objects have a single method. Of course, they could have many, but the point is, it's totally fine to have a class or struct with a single method and if you add more, ask yourself if the method you're about to add does belong to the class.
Now that we have our different object responsible for specific tasks, the next question is, how would we connect them? We have several solutions here, but the two commons ones in the iOS world are probably:

Injecting all these objects to the LoginViewController via constructor injection
Create a ViewModel class that holds instances of the APlClient, Decoder and Logger objects then inject the ViewModel via LoginViewController constructor. I find the last solution a better option, so the view controller is not aware of network calls, decoding, and other stuff, and with the arrival of SwiftUI, we tend to use this pattern a lot. We'll have something like this:

class LoginViewModel {

  private var logger: Logger<User>
  private var apiClient: APIClient
  private var decoder: Decoder<User>

  init(logger: Logger<User>, apiClient: APIClient, decoder: Decoder<User>) {
    self.logger = logger
    self.apiClient = apiClient
    self.decoder = decoder
  }

  func signin(email: String, password: String, completionHandler: @escaping (Result<User, Error>)->()) {
    let url = URL(string: "https://my-api.com")!
    let json = ["email": email, "password": password]
    let jsonData = try! JSONSerialization.data(withJSONObject: json, options: [])
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.httpBody = jsonData
    request.addValue("application/json", forHTTPHeaderField: "Content-Type")
    request.addValue("application/json", forHTTPHeaderField: "Accept")

    apiClient.load(from: request) { response in
      switch response {
        case .success(let data):
          let user = try! self.decoder.decode(from: data)
          self.logger.log(object: user)
          completionHandler(.success(user))
        case .failure(let error):
          completionHandler(.failure(error))
      }
    }

  }

}

Now we can use this view model in the LoginViewController class and let him handle the user sign-in:

final class LoginViewController: UIViewController {

  private var emailTextField: UITextField!
  private var passwordTextField: UITextField!
  private var submitButton: UIButton!

  private let viewModel: LoginViewModel

  init(viewModel: LoginViewModel) {
    self.viewModel = viewModel
    super.init(nibName: nil, bundle: nil)
  }

  required init?(coder: NSCoder) {
    fatalError("init(coder:) has not been implemented")
  }

  override func viewDidLoad() {
    super.viewDidLoad()
    setupView()
  }

  private func setupView() {
    // ... other view related code here
    submitButton.addTarget(self, action: #selector(submitButtonTapped), for: .touchUpInside)
  }

  @objc private func submitButtonTapped() {
    viewModel.signin(email: emailTextField.text ?? "",
                     password: passwordTextField.text ?? "") { response in
      switch response {
        case .success(let user): self.showWelcomeMessage(user: user)
        case .failure(let error): self.showErrorAlert(message: error.localizedDescription)
      }
    }
  }

  private func showErrorAlert(message: String) {
    DispatchQueue.main.async {
      // logic to show an error alert
    }
  }

  private func showWelcomeMessage(user: User) {
    DispatchQueue.main.async {
      // logic to show a welcome message
    }
  }

}

I don't know about you, but I think this is a much cleaner code. The controller is not aware of anything; he just handles user inputs and responds to them. We have a loosely coupled, more maintainable, and testable code now. That's all about the S.O.L.I.D principles, and as a bonus, our view controller is no more bloated (we have a joke in iOS and it's said MVC stands for Massive View Controller 😅).

Conclusion

The core of the SRP is each class should have its own responsibility, or in other words, it should have exactly one reason to change. If you start identifying multiple consumers and multiple reasons for a class to change, chances are you need to extract some of that logic into their dedicated classes. But as we said above, the most challenging part of this principle is knowing the object boundaries or identifying when an object begins to have more than one responsibility or reason to change. This comes with practice and constant reflection; we should always ask ourselves the right questions in order to move in the right direction. Next week, we'll go through the Open-Closed Principle. Until then, have a nice week, and may the force be with you 👊.

I was doing TDD wrong and you (probably) are

Ibrahima Ciss — Mon, 04 Jan 2021 08:42:25 +0000

I was recently reading Test-Driven Development book by Kent Beck, and it doesn’t take me long to realize that I was doing TDD wrong. I started this practice a couple of years ago, and I would never have thought in my wildest dream doing it the wrong way, but here I am.

First let’s revise TDD principles, shall we?

Write a failing test (Red)
Write the minimum amount of code to make the test passes (Green)
Remove duplications (Refactor)

What I was doing completely wrong was step 2 and 3.

Doing TDD the wrong way

To illustrate that I’ll take a simple FizzBuzz example. Again, let’s see the requirements of this kata before implementing it (the wrong way):

For multiple of three, print “Fizz” instead of the number
For multiple of five, print “Buzz”
For numbers which are multiples of both three and five, print “FizzBuzz” So, I would create the test class and write the first failing test:

import XCTest

class FizzBuzzTests: XCTestCase {

  func test_it_returns_fizz_for_multiple_of_three() {
    [3, 6, 9, 12].forEach {
      XCTAssertEqual("fizz", FizzBuzz.convert($0))
    }
  }

}

At this phase, the code won’t even compile because there is no class or struct called FizzBuzz. Let’s go ahead and create it.

struct FizzBuzz {

}

Again it doesn’t compile because there is no convert method, let's add it.

struct FizzBuzz {

  static func convert(_ number: Int) -> String {    

  }

}

At this point, we have just one error left saying “Missing return in a function expected to return 'String’” and it’s right, we say the convert method should return a String, but we return Void instead.
Now the wrong part of me doing TDD (I can’t even call it TDD now, shame on me 🤧), I would directly put the concrete implementation of that method like so:

struct FizzBuzz {

  static func convert(_ number: Int) -> String {
    if number % 3 == 0 { return "fizz" }
    return ""
  }

}

Now, I have no compilation error and If I run the test, it passes successfully, and you can see a smile on my face. Let’s continue by writing the remaining tests.

import XCTest

  func test_it_returns_fizz_for_multiple_of_three() {
    [3, 6, 9, 12].forEach {
      XCTAssertEqual("fizz", FizzBuzz.convert($0))
    }
  }

  func test_it_returns_buzz_for_multiple_of_five() {
    [5, 10, 20, 25].forEach {
      XCTAssertEqual("buzz", FizzBuzz.convert($0))
    }
  }

  func test_it_returns_fizzbuzz_for_multiple_of_three_and() {
    [15, 30, 45, 60].forEach {
      XCTAssertEqual("fizzbuzz", FizzBuzz.convert($0))
    }
  }

  func test_it_returns_the_original_number_if_not_divisible_by_three_or_five() {
    [1, 2, 4, 7].forEach {
      XCTAssertEqual("\($0)", FizzBuzz.convert($0))
    }
  }

}

Now let’s write the complete struct that’ll make all these tests pass.

struct FizzBuzz {

  static func convert(_ number: Int) -> String {
    if number % 3 == 0 && number % 5 == 0 { return "fizzbuzz" }
    if number % 3 == 0 { return "fizz" }
    if number % 5 == 0 { return "buzz" }
    return "\(number)"
  }

}

When we run the tests, they all pass. For me, this was completely correct because I wrote the failing test, then the code that make the test passes (even though it’s not the minimum amount of code necessary to turn to green), and what about the third step, the refactoring phase? Well, I would do probably something like this:

struct FizzBuzz {

  static func convert(_ number: Int) -> String {
    var result = ""
    if number % 3 == 0 { result += "fizz" }
    if number % 5 == 0 { result += "buzz" }
    return result.count > 0 ? result : "\(number)"
  }

}

The code looks sexier even though we have the same number of lines and the tests still pass. At this point, I’m all happy, and I’ll call it a day.
This is not how TDD is supposed to work, this is just a cycle of writing a failing test and making it pass. What about the step 2, which states to write the minimum amount of code necessary to make the test pass? And step 3 where we’re supposed to refactor by removing duplication?
Ok, but one particular question arises “Does it even matter if the code works? I mean, at the end of the day, we have a good implementation of our fizzbuzz kata and a suite of tests validating it correctness”. Yes, for me, it does. Doing things this way might work for sure, but it’s violating the core principles of TDD and as Kent said in his book:
“Quickly getting that bar to go to green dominates everything else. If a clean, simple solution is obvious, then type it in. If the clean, simple solution is obvious, but it will take you a minute, then make a note of it and get back to the main problem, which is getting the bar green in seconds.” which just means we have to make the test pass as quickly as possible and refactor afterwards. Now let’s do TDD the right way.

Doing TDD the right way (Fake it, ’til you make it)

Now we’ve seen how I was doing TDD the wrong way, let’s see how things should really work. For that, I’m going to take the same example as above.

The first step is to write a failing test. Easy enough.

import XCTest

class FizzBuzzTests: XCTestCase {

  func test_it_returns_fizz_for_multiple_of_three() {
    [3, 6, 9, 12].forEach {
      XCTAssertEqual("fizz", FizzBuzz.convert($0))
    }
  }

}

The second step is to write the least required code to make the test pass (remember, for this one, I would create the struct and the convert method then fill it with the concrete implementation like I did above). This time, the code would look like this.

struct FizzBuzz {

  static func convert(_ number: Int) -> String {
    return "fizz"
  }

}

When we run the test, of course it passes. We went to green as quickly as possible: we fake it by using stubs. And yes, this is not the correct implementation, but remember, we want to go green as soon as possible, no matter what.

The third step is refactoring to remove duplications. Hum, ok, but with this code, where is the duplication? Usually, you see duplication between two pieces of code, but here the duplication is between the data in the test and the data in the code (aha 💡). So, we’ll replace our code by the correct implementation:

struct FizzBuzz {

  static func convert(_ number: Int) -> String {
    var result = ""
    if number % 3 == 0 { result += "fizz" }
    return result.count > 0 ? result : "\(number)"
  }

}

And we can repeat the whole cycle for the remaining tests. Doing things this way has a couple of effects that make “Fake It” powerful:

Psychological: having a green bar feels completely different from having a red bar. When the bar is green, you know where you stand. You can refactor from there with confidence.
Scope control: programmers are good at imagining all sorts of future problems. Starting with one concrete example and generalizing from there prevents you from prematurely confusing yourself with extraneous concerns. You can do a better job of solving the immediate problem because you are focused. When you go to implement the next test case, you can focus on that one, too, knowing that the previous test is guaranteed to work.

Conclusion

The part I totally missed I think was the refactoring one. I was getting trapped by making things work as soon as possible with the correct implementation without using any sort of stubs or mocks which results of me violating the rules. The second mistake was whenever I heard the word “refactor”, I thought it refers to moving code around, making it look sexier, re-run the tests suite to ensure everything is still working, etc... Sure that’s refactoring, who can blame you for thinking that way? But from a TDD perspective the true meaning of the word is to remove duplications by removing the stubs (generally constant values) and replacing them with their correct implementation. If you want to learn more about TDD, I highly recommend Kent’s book: Test-Driven Development By Example, you can find it on Amazon.