TDD Is Design, One Failing Test at a Time

8 min read

The Ticket Forgot the Warehouse

17.11.2026, By Stephan Schwab

Stephan Schwab

The customer clicks Cancel while someone in the warehouse is still pulling items off the shelf. The software says it's cancelled. The warehouse hasn't agreed to stop. A small function has just made a promise the business can't keep. In a Python example, a failing test makes that promise visible and forces a decision about what the customer should see while the warehouse is still working. Making the test pass gives the decision a place in the code. The next failing test shows what we still got wrong.

A developer listens closely as a warehouse colleague points to a cancelled customer order beside a laptop and a notebook sketch.
The useful design question came from the person who would have to stop the order.

One Example Is Enough to Start an Argument

The first test chooses an interface and a behavior. Those are already design decisions.

Use a deliberately small, invented order system. An order waiting for the warehouse can be cancelled immediately. We have not yet agreed what happens once picking starts.

In test_order.py, write the first example:

import unittest

from order import Order, cancel


class CancellationTests(unittest.TestCase):
    def test_waiting_order_can_be_cancelled(self):
        order = Order(state="waiting")

        result = cancel(order)

        self.assertEqual("cancelled", result.state)

Use a supported Python 3 release. From the directory containing the example files, run the standard library’s unittest runner:

python3 -m unittest -v

At first the import fails because order.py does not exist. Create enough structure to reach the behavior we actually want to check:

from dataclasses import dataclass


@dataclass(frozen=True)
class Order:
    state: str


def cancel(order: Order) -> Order:
    raise NotImplementedError

Run the test again. It now reaches cancel and fails with NotImplementedError. We know why it is red. A misspelled import would tell us something about our typing. This failure tells us that cancellation has no implementation yet.

Notice the decisions already made. Cancellation is an operation on an order. It returns an order whose state we can inspect. The input is an immutable value, so callers can keep the original without it changing behind their backs. We could have chosen a mutable object or a command handler instead. A test does not eliminate those choices. It makes us try one.

Now replace the file’s import with from dataclasses import dataclass, replace, keep the Order class, and replace cancel with:

def cancel(order: Order) -> Order:
    return replace(order, state="cancelled")

The test passes. The implementation satisfies our only example. It is also wrong for orders already leaving the building.

That is a useful distinction to discover while the program still fits on a screen.

The Second Test Needs Someone Else’s Answer

An automated test can preserve a business decision. It cannot authorize one.

Ask the warehouse colleague what cancellation means after picking has started. She cannot promise an immediate stop: a worker might be away from the device. Sales agrees that the customer should see a cancellation request until the warehouse confirms it. A shipped order needs the returns process instead.

Those are decisions for this example, not universal laws of commerce. Another business might choose a different policy. The developer should not quietly settle it by reaching for the nearest if statement.

Add these two methods inside CancellationTests in test_order.py:

    def test_picking_order_records_a_request(self):
        order = Order(state="picking")

        result = cancel(order)

        self.assertEqual("cancellation_requested", result.state)

    def test_shipped_order_remains_shipped(self):
        order = Order(state="shipped")

        result = cancel(order)

        self.assertEqual("shipped", result.state)

Run the suite. The first example still passes. Both new examples fail: the function returns cancelled for everything. This is the productive kind of embarrassment. We have caught a false promise before the customer receives it in an email.

Change the function:

def cancel(order: Order) -> Order:
    if order.state == "picking":
        return replace(order, state="cancellation_requested")
    if order.state == "shipped":
        return order
    return replace(order, state="cancelled")

Three examples pass. Three examples are also not the entire problem.

What if the customer presses the button twice while picking continues? Our function takes an existing cancellation_requested state and turns it into cancelled. It has invented warehouse confirmation out of a repeated click. Very efficient. Completely unearned.

Add the repeated-click example inside CancellationTests:

    def test_repeated_request_does_not_confirm_cancellation(self):
        order = Order(state="cancellation_requested")

        result = cancel(order)

        self.assertEqual("cancellation_requested", result.state)

Watch it fail. In cancel, replace if order.state == "shipped": with if order.state in ("shipped", "cancellation_requested"): and run the suite again. The repeated request now leaves the state alone. Add a fifth test that passes an already cancelled order and expects cancelled. That one should pass immediately. The behavior was already there. The example makes it explicit.

Refactoring Gives the Rule a Nameable Shape

Green tests create room to improve the representation without renegotiating the behavior.

The conditionals now express a small transition rule. Repeated strings make it easy to mistype a state, and the final catch-all quietly treats every unrecognized state as cancellable. Give the known states explicit names and list the allowed cancellation outcomes.

Here is the complete final order.py, replacing the earlier string-based version:

from dataclasses import dataclass, replace
from enum import Enum


class State(Enum):
    WAITING = "waiting"
    PICKING = "picking"
    CANCELLATION_REQUESTED = "cancellation_requested"
    CANCELLED = "cancelled"
    SHIPPED = "shipped"


@dataclass(frozen=True)
class Order:
    state: State


CANCELLATION_OUTCOME = {
    State.WAITING: State.CANCELLED,
    State.PICKING: State.CANCELLATION_REQUESTED,
    State.CANCELLATION_REQUESTED: State.CANCELLATION_REQUESTED,
    State.CANCELLED: State.CANCELLED,
    State.SHIPPED: State.SHIPPED,
}


def cancel(order: Order) -> Order:
    return replace(order, state=CANCELLATION_OUTCOME[order.state])

That table is a design choice worth discussing. For five states, explicit conditionals could also be perfectly readable. Here the table lets the developer and warehouse colleague inspect every cancellation outcome in one place. The five agreed outcomes stay the same. The table also deliberately drops the old fallback for unsupported states. A missing entry now raises KeyError. External input still needs validation at the application’s boundary. A Python type annotation does not enforce that for us.

Replace test_order.py with the complete suite below. The examples now use the named states, while keeping the behavior agreed in the earlier steps:

import unittest

from order import Order, State, cancel


class CancellationTests(unittest.TestCase):
    def test_waiting_order_can_be_cancelled(self):
        order = Order(State.WAITING)

        result = cancel(order)

        self.assertEqual(State.CANCELLED, result.state)
        self.assertEqual(State.WAITING, order.state)

    def test_picking_order_records_a_request(self):
        result = cancel(Order(State.PICKING))

        self.assertEqual(State.CANCELLATION_REQUESTED, result.state)

    def test_shipped_order_remains_shipped(self):
        result = cancel(Order(State.SHIPPED))

        self.assertEqual(State.SHIPPED, result.state)

    def test_repeated_request_does_not_confirm_cancellation(self):
        order = Order(State.CANCELLATION_REQUESTED)

        result = cancel(order)

        self.assertEqual(State.CANCELLATION_REQUESTED, result.state)

    def test_cancelled_order_stays_cancelled(self):
        result = cancel(Order(State.CANCELLED))

        self.assertEqual(State.CANCELLED, result.state)

Run the same command again. All five tests should pass. No testing library to install, no web framework, no database. We are examining one rule without forcing the entire application to attend.

The red, green, refactor cycle joins implementation and design through feedback. The Agile Alliance’s definition of TDD explicitly includes design through refactoring. Writing tests after a finished implementation can check behavior, but it cannot retrospectively create this sequence of discoveries.

The Database Has Not Read Our Unit Tests

A correct in-memory transition still needs a safe way to meet concurrent work and external effects.

Our function assumes the state it receives is current. In production, the warehouse might start picking between reading waiting and saving cancelled. A passing unit test says nothing about whether that race is handled.

The application needs a way to accept the state change only if the stored version still matches the one it read, then handle a conflict explicitly. Depending on the database and surrounding design, that may involve a conditional update or transaction. Test that boundary against the real storage behavior, including competing updates.

Warehouse confirmation needs its own transition and examples. So do payment adjustments, stock reservations, and shipment. If changing the order must also send a durable message, test what happens when saving succeeds and sending fails. Repeating a message must not produce a second refund. None of those responsibilities lives in the tiny function above.

The user interface also needs to distinguish the outcomes. A returned SHIPPED order must not trigger a cheerful cancellation confirmation. The function preserves state; it is not the entire customer conversation.

TDD can guide those boundaries too. It does not make five unit tests a certificate of production readiness. A test suite that stays green because it never meets the database is capable of remarkable optimism.

Finished Design Is an Expensive Fiction

Separate responsibilities when useful. Keep new evidence able to change earlier decisions.

Now consider a process in which analysis finishes first, design receives approval, developers implement it, and testers inspect the result afterward. The cancellation question arrives during implementation. The approved design has only waiting, cancelled, and shipped.

Someone now has to decide whether a missing state is useful learning or an unauthorized deviation. If changing the document requires a meeting next Thursday, the organization has made pretending cheaper than understanding.

Different people can contribute different expertise. Architectural constraints can be established before a small feature. A regulated system may need explicit evidence and approval. None of that requires new information to become unwelcome once a phase is declared complete.

The warehouse colleague supplied knowledge the original ticket lacked. The tests gave that knowledge a precise expression. The implementation revealed another question about repeated requests. Refactoring made the resulting rule easier to inspect. Each activity changed what the next activity needed to do.

That is why software development is design. A diagram can capture an important decision. The work of making the decision fit reality continues when the code starts answering back.

Keep the feedback small enough to use. Write the next example. Watch it fail for a reason you understand. Make it pass. Improve the design while keeping the agreement intact.

And when the warehouse asks an awkward question, pull up a chair. The ticket was never going to answer it.

Talk It Through

Tell me what is happening. I listen, ask a few practical questions, and reflect back what I see: where the risk may sit, what may be blocking delivery, and what looks worth checking next. No pitch, no obligation. Confidential and direct.

Talk it through. Practical reflection, no pitch.

Start a Conversation

Newsletter: No methodology theater. No fluff.
Delivery insights and drama you won't find elsewhere.

×