The Essential Checklist for Python TDD Practitioners

Pre-TDD Setup: Tools & Environment
Understand the TDD Cycle: Red → Green → Refactor
Writing Effective Test Cases
Dependencies and Mocking in Python
Integration with Your Development Workflow
Best Practices for Sustainable TDD
Troubleshooting Common TDD Pitfalls
Conclusion
References

1. Pre-TDD Setup: Tools & Environment

Before diving into TDD, ensure your Python environment is configured with the right tools to streamline testing.

✅ Essential Testing Libraries

Test Runners:
Use pytest (recommended for its simplicity, fixtures, and rich plugin ecosystem) or Python’s built-in unittest (if you prefer standard library tools).
```
pip install pytest  # For pytest  
```
Mocking:
Python’s unittest.mock (standard library) or pytest-mock (simpler wrapper for unittest.mock in pytest) to simulate external dependencies.
```
pip install pytest-mock  # Optional, for pytest users  
```

Test Coverage:
coverage.py to measure how much code your tests execute.

pip install coverage pytest-cov  # pytest-cov integrates coverage with pytest

Linters/Formatters:
flake8, black, or ruff to enforce code quality—clean code is easier to test!

✅ Environment Configuration

Isolated Environments: Use venv, conda, or poetry to avoid dependency conflicts.

python -m venv .venv && source .venv/bin/activate  # Linux/macOS  
.venv\Scripts\activate  # Windows

Reproducibility: Track dependencies with requirements.txt or pyproject.toml (Poetry/Pipenv) to ensure consistent setups across teams.

2. Understand the TDD Cycle: Red → Green → Refactor

TDD revolves around a three-step loop. Mastering this cycle is foundational to success.

✅ Red: Write a Failing Test

Test a Specific Behavior: Focus on what the code should do, not how it does it. For example, if building a greet function, test that greet("Alice") returns "Hello, Alice!".
Keep It Minimal: Write the smallest test that could possibly fail. Avoid overcomplicating with edge cases initially—you’ll add those later.

Example:

# test_greeting.py  
def test_greet_returns_personalized_message():  
    from greeting import greet  
    assert greet("Alice") == "Hello, Alice!"  # Fails initially (no greet function)

✅ Green: Write the Simplest Code to Pass

No Over-Engineering: Prioritize making the test pass, not perfect code. If the test expects "Hello, Alice!", hardcode return "Hello, Alice!" if needed—you’ll refactor later.
Run Tests Frequently: Use pytest test_greeting.py to confirm the test now passes.

Example:

# greeting.py  
def greet(name):  
    return "Hello, Alice!"  # Minimal code to pass the test

✅ Refactor: Improve Code Without Breaking Tests

Clean Up: Remove duplication, improve readability, or optimize performance—but only if tests pass.
Refactor Tests Too: Tests need maintenance too! Simplify repetitive setup with fixtures (see Section 3).

Example Refactor:

# greeting.py (refactored)  
def greet(name: str) -> str:  
    return f"Hello, {name}!"  # Generalizes to any name, test still passes

3. Writing Effective Test Cases

Tests are only useful if they’re reliable, maintainable, and cover critical behaviors.

✅ Follow the AAA Pattern

Structure tests with Arrange-Act-Assert:

Arrange: Set up inputs and dependencies (e.g., create test data, initialize objects).
Act: Call the function/method being tested.

Assert: Verify the result matches expectations.

def test_divide_returns_quotient():  
    # Arrange  
    a, b = 10, 2  
    # Act  
    result = divide(a, b)  
    # Assert  
    assert result == 5

✅ Name Tests Clearly

Use descriptive names like test_[function]_[scenario]_[expected_result] to make failures self-documenting.

Bad: test_divide()
Good: test_divide_positive_numbers_returns_correct_quotient()

✅ Test Isolation

Each test must run independently—no shared state between tests. Use pytest fixtures to reset state between runs.

import pytest  

@pytest.fixture  
def fresh_database():  
    db = Database()  
    yield db  
    db.clear()  # Teardown: Reset after test  

def test_add_user_to_database(fresh_database):  
    fresh_database.add_user("Alice")  
    assert fresh_database.get_user("Alice") is not None

✅ Cover Edge Cases

Test scenarios like:

Empty inputs (greet("") → "Hello, !" or a validation error?).
Boundary values (e.g., calculate_tax(1000) for a tax bracket cutoff).
Invalid inputs (e.g., divide(5, 0) should raise ZeroDivisionError).

✅ Use Parameterized Tests

Test multiple input-output pairs with @pytest.mark.parametrize to reduce duplication.

import pytest  

@pytest.mark.parametrize("name, expected", [  
    ("Alice", "Hello, Alice!"),  
    ("Bob", "Hello, Bob!"),  
    ("", "Hello, !"),  # Edge case  
])  
def test_greet_handles_multiple_names(name, expected):  
    from greeting import greet  
    assert greet(name) == expected

4. Dependencies and Mocking in Python

External systems (APIs, databases, files) can slow tests or make them flaky. Use mocking to control these dependencies.

✅ When to Mock

Mock:

External services (e.g., a payment gateway).
Slow operations (e.g., a database query that takes 5 seconds).
Unreliable dependencies (e.g., a third-party API with rate limits).

✅ Master `unittest.mock`

Python’s unittest.mock library lets you replace real objects with “fake” ones. Use patch to mock functions/classes.

Example: Mocking an API Call

# weather.py  
import requests  

def get_temperature(city: str) -> float:  
    response = requests.get(f"https://api.weather.com/temp?city={city}")  
    return response.json()["temp"]

# test_weather.py  
from unittest.mock import patch, MagicMock  
def test_get_temperature_uses_api_correctly():  
    with patch("weather.requests.get") as mock_get:  
        # Arrange: Mock the API response  
        mock_response = MagicMock()  
        mock_response.json.return_value = {"temp": 22.5}  
        mock_get.return_value = mock_response  

        # Act  
        result = get_temperature("Paris")  

        # Assert: Verify API was called with the right URL  
        mock_get.assert_called_once_with("https://api.weather.com/temp?city=Paris")  
        assert result == 22.5

✅ Avoid Over-Mocking

Don’t mock internal functions or pure logic—test those directly.
Prefer “real” dependencies for critical paths (e.g., use a test database like SQLite instead of mocking all DB calls).

5. Integration with Your Development Workflow

TDD works best when testing becomes part of your daily routine, not an afterthought.

✅ Run Tests Frequently

Pre-Commit Hooks: Use the pre-commit framework to run tests (and linters) before commits.

# .pre-commit-config.yaml  
repos:  
  - repo: local  
    hooks:  
      - id: run-tests  
        name: Run tests  
        entry: pytest  
        language: system  
        pass_filenames: false

On Save: Use pytest-watch to re-run tests automatically when files change:
```
pip install pytest-watch  
ptw  # Runs pytest on every save  
```

✅ CI/CD Integration

Automate testing in your pipeline (GitHub Actions, GitLab CI, etc.) to catch regressions early.

Example GitHub Actions Workflow:

# .github/workflows/ci.yml  
name: Tests  
on: [push, pull_request]  
jobs:  
  test:  
    runs-on: ubuntu-latest  
    steps:  
      - uses: actions/checkout@v4  
      - uses: actions/setup-python@v5  
        with: { python-version: "3.11" }  
      - run: pip install -r requirements.txt  
      - run: pytest --cov=myapp  # Run tests and check coverage

✅ Set Coverage Goals

Aim for high coverage (e.g., 80-90%) but don’t chase 100% blindly. Focus on critical paths (e.g., payment processing) over trivial code (e.g., simple getters). Use pytest --cov=myapp to generate reports.

6. Best Practices for Sustainable TDD

TDD is a long-term investment. Keep your tests maintainable to avoid technical debt.

✅ Refactor Tests Too

Tests are code too! Remove duplication, simplify assertions, and delete obsolete tests (e.g., after refactoring the code under test).

✅ Use Fixtures for Repeated Setup

pytest fixtures eliminate redundant code (e.g., creating test users or database connections).

@pytest.fixture  
def user_database():  
    db = UserDatabase()  
    db.add_user("test_user", "password123")  
    return db  

def test_user_login(user_database):  
    assert user_database.login("test_user", "password123") is True

✅ Test Behavior, Not Implementation

Avoid testing private methods or internal logic—focus on the public API. If you refactor the internals, tests should still pass.
Bad: Testing that _calculate_tax_rate() returns 0.2 (implementation detail).
Good: Testing that calculate_total(100) returns 120 (behavior).

✅ Balance Unit and Integration Tests

Follow the test pyramid:

Unit tests (bottom): Fast, isolated, test individual components (most tests here).
Integration tests (middle): Test interactions between components (e.g., API + database).
End-to-end tests (top): Test the full app flow (e.g., user login → checkout) sparingly—they’re slow!

7. Troubleshooting Common TDD Pitfalls

Even experienced practitioners hit roadblocks. Here’s how to fix them.

✅ Flaky Tests

Causes: Shared state between tests, timing issues (e.g., async code), or external dependencies.
Fixes: Use isolated fixtures, mock external systems, or add retries for flaky tests (e.g., pytest-rerunfailures).

✅ Slow Tests

Causes: Unmocked databases, large test suites, or unoptimized code.
Fixes: Mock slow dependencies, run tests in parallel (pytest-xdist), or split large test suites into smaller chunks.

✅ Hard-to-Test Code

Signs: Tight coupling (e.g., a function that creates its own database connection), global state, or overly complex logic.
Fixes: Refactor with dependency injection (pass dependencies as arguments), split large functions, or use design patterns like Factory or Strategy.

8. Conclusion

TDD isn’t just about writing tests—it’s a mindset that prioritizes clarity, reliability, and iterative improvement. By following this checklist, Python practitioners can avoid common pitfalls, build maintainable test suites, and deliver code with confidence. Remember: TDD is a skill—practice the cycle, refine your tests, and adapt these guidelines to your team’s needs.

Table of Contents