As a big advocate of Test-Driven Development (TDD), I have spent a good amount of time wondering why 95% of my conversations about TDD with other engineers go something like this: “Yes, TDD is clearly the right way to build software. But I don’t actually do it.” At this point, the usual reasons and explanations are laid out: “It’s hard to know what tests to write until I have written the code.”
“How can I know how the tests should work if I don’t know how the code works?” It is true that if you are testing something that uses completely unfamiliar technology, you probably don’t know yet how to go about testing it. Most of the time, though, the technology is perfectly familiar. It’s not the tools that are unfamiliar and scary - it’s the product that you are trying to build. Enter my ✨One Simple Trick™✨… Forget about the code completely (for now). All of it. Don’t think about the implementation, and don’t think about the test code either. Instead, just write a plan for how the product should work. Here’s how I do it: Step 1 Start by writing simple comments in human language. Write as many as you can think of, with one per requirement, acceptance criteria, scenario, edge case, or error. Here’s an example: // animals.test.ts
// Plan for new API endpoint: GET /animals

// returns a list of animals with the ID and name

// paginated 10 at a time by default

// can change the pagination size

// optionally filters by species type (in the query params)

// returns a 403 error if not authenticated Of course, the code has to happen at some point. But by starting with comments like this, it removes all of the psychological resistance to the idea of writing tests, allowing you to focus on what you’re trying to build. Step 2 Write the actual tests one by one by converting each comment into an assertion. // animals.test.ts

import { request } from "supertest";
import { app } from "./app";

it('returns a list of animals with the ID and name', async () => {
  const result = await request(app).get('/animals');
  
  result.forEach(animal => {
    expect(animal).toEqual({
      id: expect.any(String),
      name: expect.any(String),
    });
  });
})

// paginated 10 at a time by default

// can change the pagination size

// optionally filters by species type (in the query params)

// returns a 403 error if not authenticated It is worth noting that this technique is best paired with the philosophy of Write Tests. Not Too Many. Mostly Integration. While the ‘comments-first’ approach can be applied to unit tests, it is much easier to start with higher-level, more product-focused integration tests. Step 3 Write the bare minimum application code to make the first test pass. For example, to make this first test pass, you could return this hardcoded array from the API endpoint: // animals.ts

res.send([{ id: "foo", name: "bar"}]); Step 4 Clearly, this isn’t enough. The urge to immediately write more code is strong. This critical moment is the final hurdle to overcome, and it is the hardest. Resist the urge! Stop, take a deep breath, and look back at your commented plan. Is there anything on that list that will force you to change the code to fix the glaring issue that you’ve seen? If yes, great! Keep going, it will be fixed soon. If not, you have two options: Improve your current test to have more specific checks
Add another comment to your plan for the missing requirement Step 5 Repeat the process. Write the next test, check that it fails, and then write the minimum code to make it pass. That’s it. Congratulations, you just TDD’ed! It will be worth it, I promise. Thank you for reading. This is the first of my new series, Dev Diaries, where I will be writing about something I’ve done, something I’ve learned, or something that I’ve found interesting that day. As a big advocate of Test-Driven Development (TDD), I have spent a good amount of time wondering why 95% of my conversations about TDD with other engineers go something like this: “Yes, TDD is clearly the right way to build software. But I don’t actually do it.” “Yes, TDD is clearly the right way to build software. But I don’t actually do it.” At this point, the usual reasons and explanations are laid out: “It’s hard to know what tests to write until I have written the code.” “How can I know how the tests should work if I don’t know how the code works?” “It’s hard to know what tests to write until I have written the code.” “It’s hard to know what tests to write until I have written the code.” “How can I know how the tests should work if I don’t know how the code works?” “How can I know how the tests should work if I don’t know how the code works?” It is true that if you are testing something that uses completely unfamiliar technology, you probably don’t know yet how to go about testing it. Most of the time, though, the technology is perfectly familiar. It’s not the tools that are unfamiliar and scary - it’s the product that you are trying to build. tools product that you are trying to build. Enter my ✨One Simple Trick™✨… Forget about the code completely (for now) . All of it. Don’t think about the implementation, and don’t think about the test code either. Forget about the code completely (for now) Instead, just write a plan for how the product should work . Here’s how I do it: just write a plan for how the product should work Step 1 Start by writing simple comments in human language. Write as many as you can think of, with one per requirement, acceptance criteria, scenario, edge case, or error. Here’s an example: // animals.test.ts
// Plan for new API endpoint: GET /animals

// returns a list of animals with the ID and name

// paginated 10 at a time by default

// can change the pagination size

// optionally filters by species type (in the query params)

// returns a 403 error if not authenticated // animals.test.ts
// Plan for new API endpoint: GET /animals

// returns a list of animals with the ID and name

// paginated 10 at a time by default

// can change the pagination size

// optionally filters by species type (in the query params)

// returns a 403 error if not authenticated Of course, the code has to happen at some point. But by starting with comments like this, it removes all of the psychological resistance to the idea of writing tests, allowing you to focus on what you’re trying to build. Step 2 Write the actual tests one by one by converting each comment into an assertion. // animals.test.ts

import { request } from "supertest";
import { app } from "./app";

it('returns a list of animals with the ID and name', async () => {
  const result = await request(app).get('/animals');
  
  result.forEach(animal => {
    expect(animal).toEqual({
      id: expect.any(String),
      name: expect.any(String),
    });
  });
})

// paginated 10 at a time by default

// can change the pagination size

// optionally filters by species type (in the query params)

// returns a 403 error if not authenticated // animals.test.ts

import { request } from "supertest";
import { app } from "./app";

it('returns a list of animals with the ID and name', async () => {
  const result = await request(app).get('/animals');
  
  result.forEach(animal => {
    expect(animal).toEqual({
      id: expect.any(String),
      name: expect.any(String),
    });
  });
})

// paginated 10 at a time by default

// can change the pagination size

// optionally filters by species type (in the query params)

// returns a 403 error if not authenticated It is worth noting that this technique is best paired with the philosophy of Write Tests. Not Too Many. Mostly Integration. While the ‘comments-first’ approach can be applied to unit tests, it is much easier to start with higher-level, more product-focused integration tests. Write Tests. Not Too Many. Mostly Integration. Step 3 Write the bare minimum application code to make the first test pass. For example, to make this first test pass, you could return this hardcoded array from the API endpoint: // animals.ts

res.send([{ id: "foo", name: "bar"}]); // animals.ts

res.send([{ id: "foo", name: "bar"}]); Step 4 Clearly, this isn’t enough. The urge to immediately write more code is strong. This critical moment is the final hurdle to overcome, and it is the hardest. Resist the urge! Stop, take a deep breath, and look back at your commented plan. Is there anything on that list that will force you to change the code to fix the glaring issue that you’ve seen? force you If yes, great! Keep going, it will be fixed soon. If not, you have two options: Improve your current test to have more specific checks Add another comment to your plan for the missing requirement Improve your current test to have more specific checks Add another comment to your plan for the missing requirement Step 5 Repeat the process. Write the next test, check that it fails, and then write the minimum code to make it pass. That’s it. Congratulations, you just TDD’ed! It will be worth it, I promise. Thank you for reading. This is the first of my new series, Dev Diaries, where I will be writing about something I’ve done, something I’ve learned, or something that I’ve found interesting that day.

This story contains new, firsthand information uncovered by the writer.

Dev Diary #1: TDD Is Easy, When You Forget About The Code

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Dev Diary #2: Run Away from Nesting Functions in Your Code

AlloyCI Dev Diary — Part 1

AlloyCI Dev Diary — Part 3

Dev Diary #3: The Sneaky Issue That Was Silently Ruining Our Database

Angular & Spring Boot - Using Serenity BDD for Integration Testing

API Integrations Can Give Your Business A Single Source of Truth

Dev Diary #2: Run Away from Nesting Functions in Your Code

AlloyCI Dev Diary — Part 1

AlloyCI Dev Diary — Part 3

Dev Diary #3: The Sneaky Issue That Was Silently Ruining Our Database

Angular & Spring Boot - Using Serenity BDD for Integration Testing

API Integrations Can Give Your Business A Single Source of Truth

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps