test-driven-development

Test-Driven Development (TDD)

Overview

Write the test first. Watch it fail. Write minimal code to pass. Keep the test suite from rotting.

Three core principles:

1. If you didn't watch the test fail, you don't know if it tests the right thing.
2. A test you can't trust is worse than no test — it creates false confidence.
3. Tests are project assets with a lifecycle — ungoverned tests become a graveyard.

Violating the letter of the rules is violating the spirit of the rules.

When to Use

Always:

• New features
• Bug fixes
• Refactoring
• Behavior changes

Exceptions (ask the user first):

• Throwaway prototypes
• Generated code
• Configuration files

Thinking "skip TDD just this once"? Stop. That's rationalization.

---

Part 1: The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Write code before the test? Delete it. Start over.

No exceptions:

• Don't keep it as "reference"
• Don't "adapt" it while writing tests
• Don't look at it
• Delete means delete

Implement fresh from tests. Period.

---

Part 2: Red-Green-Refactor Cycle

RED — Write Failing Test

Write one minimal test showing what should happen.

Good test:

def test_retries_failed_operations_3_times():
    attempts = 0
    def operation():
        nonlocal attempts
        attempts += 1
        if attempts < 3:
            raise Exception('fail')
        return 'success'

    result = retry_operation(operation)

    assert result == 'success'
    assert attempts == 3

Clear name, tests real behavior, one thing.

Bad test:

def test_retry_works():
    mock = MagicMock()
    mock.side_effect = [Exception(), Exception(), 'success']
    result = retry_operation(mock)
    assert result == 'success'  # What about retry count? Timing?

Vague name, tests mock not real code.

Requirements:

• One behavior per test
• Clear descriptive name ("and" in name? Split it)
• Real code, not mocks (unless truly unavoidable — see Part 4)
• Name describes behavior, not implementation
• Assert on observable effects: return values, state changes, output, side effects — not internal call counts