🔴🟢 Test-Driven Development Workflow

What Is TDD?

Test-Driven Development (TDD) is a workflow where you write a failing test first, then write just enough code to make it pass, then improve the code. The test isn't an afterthought that verifies finished work — it's a specification you write in advance that drives the design of the code.

The mental shift is subtle but powerful. Before writing any implementation, you must decide exactly what "working" means and express it as an executable test. That forces clarity: you design the interface from the caller's point of view before you get lost in the internals.

💡 Net before the tightrope: TDD builds the safety net before you step out onto the wire. You define what a fall looks like — and what catching it looks like — before you take a single risky step.

The TDD Cycle: Red, Green, Refactor

TDD is a tight, repeating loop with three phases. Each pass through it should take minutes, not hours.

🔴 Red — write a failing test

Describe the behavior you want as a test. It must fail (because the code doesn't exist yet). This step forces you to define success before you build. It's the blueprint before the house.

🟢 Green — make it pass

Write the minimum code to turn the test green. Resist elegance here — a hard-coded return is fine if it passes. The goal is a working slice, not a masterpiece. It's the rough prototype.

🔵 Refactor — improve the code

With a passing test as your safety net, clean up: remove duplication, rename for clarity, extract functions — running the test after each change to confirm nothing broke. This is redesigning the prototype for durability without changing what it does.

TDD in Practice: A JavaScript Example

Let's build an email validator test-first with Vitest (Jest syntax is identical).

🔴 Step 1: Red — the failing test

// emailValidator.test.js
import { describe, it, expect } from 'vitest';
import { isValidEmail } from './emailValidator.js';

describe('isValidEmail', () => {
  it('accepts well-formed addresses', () => {
    expect(isValidEmail('user@example.com')).toBe(true);
    expect(isValidEmail('name.surname@domain.co.uk')).toBe(true);
  });

  it('rejects malformed addresses', () => {
    expect(isValidEmail('not-an-email')).toBe(false);
    expect(isValidEmail('missing@domain')).toBe(false);
    expect(isValidEmail('@domain.com')).toBe(false);
    expect(isValidEmail('')).toBe(false);
  });
});

FAIL  emailValidator.test.js
  ✗ isValidEmail accepts well-formed addresses
    Error: Failed to resolve import "./emailValidator.js"

🟢 Step 2: Green — minimal code to pass

// emailValidator.js
export function isValidEmail(email) {
  if (!email) return false;
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}

The tests now pass. Note we wrote only what the tests demanded — nothing more.

🔵 Step 3: Refactor — harden without breaking

// emailValidator.js — after refactoring
export function isValidEmail(email) {
  if (typeof email !== 'string' || email.length === 0) return false;
  if (email.length > 254) return false; // RFC upper bound

  const emailRegex =
    /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
  return emailRegex.test(email);
}

We made the implementation more robust and the tests are still green — proof our behavior didn't drift. That confidence is the whole point of the refactor step.

TDD in Practice: A Python Example

The same rhythm applies in any language. Here's a shopping-cart total calculator built with pytest.

🔴 Step 1: Red — the failing test

# test_cart.py
from cart import calculate_total

def test_total_without_discount():
    items = [
        {"name": "Keyboard", "price": 50.00, "quantity": 1},
        {"name": "Mouse", "price": 25.00, "quantity": 2},
    ]
    assert calculate_total(items) == 100.00

def test_total_with_discount():
    items = [
        {"name": "Monitor", "price": 200.00, "quantity": 1},
        {"name": "Headphones", "price": 100.00, "quantity": 1},
    ]
    assert calculate_total(items, discount_percent=10) == 270.00

🟢 Step 2: Green — minimal code to pass

# cart.py
def calculate_total(items, discount_percent=0):
    total = sum(item["price"] * item["quantity"] for item in items)
    if discount_percent:
        total -= total * (discount_percent / 100)
    return total

🔵 Step 3: Refactor — validate inputs and document

# cart.py — refactored
def calculate_total(items, discount_percent=0):
    """Return the cart total after an optional percentage discount.

    Args:
        items: list of dicts with 'price' and 'quantity'.
        discount_percent: discount to apply, 0-100.
    Returns:
        float rounded to 2 decimal places.
    """
    if not items:
        return 0

    if not 0 <= discount_percent <= 100:
        raise ValueError("discount_percent must be between 0 and 100")

    subtotal = sum(
        item.get("price", 0) * item.get("quantity", 0)
        for item in items
    )
    total = subtotal - subtotal * (discount_percent / 100)
    return round(total, 2)

Once the refactor is in place, add tests for the new edge cases (empty cart, invalid discount) — and watch them pass too.

Benefits & When to Use It

TDD shines in some situations more than others. Reach for it when:

• The logic is complex, with many rules and edge cases to pin down.
• You're fixing a bug — write a failing test that reproduces it, then make it pass so it never returns.
• You're refactoring legacy code and need tests to lock in current behavior first.
• You're designing an API and want the caller's experience to drive the shape.
• Requirements are clear enough to express as concrete test cases.

Common Pitfalls

TDD is simple to describe and easy to do badly. Watch for these traps.

BDD & ATDD

TDD has close relatives that push the "test first" idea toward the business.

Behavior-Driven Development (BDD)

BDD frames tests as human-readable behavior, often in Given-When-Then form, so non-developers can read and even help write them:

// BDD style with Vitest-Cucumber
import { loadFeature, describeFeature } from '@amiceli/vitest-cucumber';

const feature = await loadFeature('./features/shoppingCart.feature');

describeFeature(feature, ({ Scenario }) => {
  Scenario('Adding items to the cart', ({ Given, When, Then }) => {
    let cart;
    Given('I have an empty shopping cart', () => { cart = new ShoppingCart(); });
    When('I add a $50 keyboard to the cart', () => {
      cart.addItem({ name: 'Keyboard', price: 50 });
    });
    Then('the cart total should be $50', () => {
      expect(cart.getTotal()).toBe(50);
    });
  });
});

Acceptance Test-Driven Development (ATDD)

ATDD starts even higher: the team defines user-facing acceptance criteria first, writes acceptance tests from them, and only then drops into unit-level TDD.

Hands-on Exercise

// stringCalculator.test.js — start here
import { describe, it, expect } from 'vitest';
import { add } from './stringCalculator.js';

describe('String Calculator', () => {
  it('returns 0 for an empty string', () => {
    expect(add('')).toBe(0);
  });

  // Add one test at a time, making each pass before the next.
});

// stringCalculator.js
export function add(numbers) {
  if (numbers === '') return 0;

  const parts = numbers.split(/[,\n]/).map(Number);
  const negatives = parts.filter((n) => n < 0);
  if (negatives.length) {
    throw new Error(`negatives not allowed: ${negatives.join(', ')}`);
  }
  return parts.reduce((sum, n) => sum + n, 0);
}

// stringCalculator.test.js — the grown suite
import { describe, it, expect } from 'vitest';
import { add } from './stringCalculator.js';

describe('String Calculator', () => {
  it('returns 0 for an empty string', () => expect(add('')).toBe(0));
  it('returns the number for a single value', () => expect(add('5')).toBe(5));
  it('sums comma-separated numbers', () => expect(add('1,2,3')).toBe(6));
  it('allows newline separators', () => expect(add('1\n2,3')).toBe(6));
  it('throws on negatives', () => {
    expect(() => add('1,-2')).toThrow(/negatives not allowed: -2/);
  });
});

Summary & Quiz

📚 Further Reading

• Martin Fowler — Test-Driven Development
• Vitest — testing framework docs
• pytest — Python testing docs

🚀 What's Next?

Now that you understand the TDD workflow, we'll get hands-on with the tooling: the Jest testing framework — matchers, mocks, setup/teardown, and how to structure a real test suite.