feat: add Module 08 — Advanced Testing curriculum

Five projects covering parametrize, mocking, fixtures, property-based
testing with Hypothesis, and FastAPI integration testing. Follows the
alter/break/fix/explain pattern established by earlier modules.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: travisjneuman

projects/modules/08-testing-advanced/01-parametrize/README.md

@@ -0,0 +1,80 @@
+# Module 08 / Project 01 — Parametrize
+
+[README](../../../../README.md) · [Module Index](../README.md)
+
+## Focus
+
+- `@pytest.mark.parametrize` to run one test function with many different inputs
+- Single-parameter and multi-parameter parametrize decorators
+- The `ids` parameter for readable test output
+- Testing utility functions with boundary values and edge cases
+
+## Why this project exists
+
+Writing a separate test function for every input you want to check is tedious and creates a wall of nearly identical code. `@pytest.mark.parametrize` solves this by letting you define one test function and feed it a table of inputs and expected outputs. Pytest runs it once per row, reporting each as a separate test case. This is how professional codebases test functions that must handle many different inputs.
+
+## Run
+
+```bash
+cd projects/modules/08-testing-advanced/01-parametrize
+pytest tests/test_utils.py -v
+```
+
+## Expected output
+
+```text
+tests/test_utils.py::test_validate_email[valid-user@example.com] PASSED
+tests/test_utils.py::test_validate_email[valid-name.tag@domain.org] PASSED
+tests/test_utils.py::test_validate_email[invalid-missing-at] PASSED
+tests/test_utils.py::test_validate_email[invalid-empty-string] PASSED
+...
+tests/test_utils.py::test_celsius_to_fahrenheit[freezing] PASSED
+tests/test_utils.py::test_celsius_to_fahrenheit[boiling] PASSED
+...
+tests/test_utils.py::test_is_palindrome[racecar-True] PASSED
+tests/test_utils.py::test_is_palindrome[hello-False] PASSED
+...
+tests/test_utils.py::test_clamp[below-minimum] PASSED
+tests/test_utils.py::test_clamp[above-maximum] PASSED
+...
+```
+
+Each parametrized case appears as a separate test with a readable name. All should pass.
+
+## Alter it
+
+1. Add three more email test cases to `test_validate_email`: one with a `+` in the local part, one with multiple dots in the domain, and one with a missing domain.
+2. Add a parametrize case for `celsius_to_fahrenheit` using absolute zero (-273.15 C = -459.67 F).
+3. Add a new parametrized test for `clamp` where `min_val` equals `max_val`. What should happen when the range is a single point?
+
+## Break it
+
+1. Change one of the expected values in `test_celsius_to_fahrenheit` to be wrong (e.g., change 32.0 to 33.0). Run the tests and read the failure output carefully — pytest shows you exactly which parametrize case failed and what the actual vs expected values were.
+2. Remove the `ids` parameter from one of the parametrize decorators and run with `-v`. Notice how the test names become less readable.
+3. Add a duplicate test ID and see what pytest does.
+
+## Fix it
+
+1. Fix the broken expected value you changed above.
+2. Add the `ids` back and verify the verbose output is readable again.
+3. If any of your new test cases from "Alter it" fail, fix either the test or the function (decide which one is wrong first).
+
+## Explain it
+
+1. What is the difference between writing five separate test functions and one parametrized test with five cases?
+2. What does the `ids` parameter do and why does it matter?
+3. How does pytest report a failure in a parametrized test differently from a regular test?
+4. When would you use multi-parameter parametrize (multiple arguments) vs single-parameter?
+
+## Mastery check
+
+You can move on when you can:
+
+- Write a parametrized test from memory, without looking at examples.
+- Explain what `ids` does and why you should use it.
+- Add new test cases to an existing parametrized test in under a minute.
+- Read pytest's parametrize failure output and understand which case failed and why.
+
+## Next
+
+[Project 02 — Mocking](../02-mocking/)

projects/modules/08-testing-advanced/01-parametrize/notes.md

@@ -0,0 +1,10 @@
+# Notes — Parametrize
+
+## What I learned
+
+
+## What confused me
+
+
+## What I want to explore next
+

projects/modules/08-testing-advanced/01-parametrize/project.py

@@ -0,0 +1,128 @@
+"""
+Project 01 — Parametrize
+
+A collection of small utility functions designed to be tested with
+@pytest.mark.parametrize. Each function is simple enough to understand
+quickly, but has enough edge cases to make parametrized testing valuable.
+
+These are the kind of utility functions you find in real codebases —
+small, pure, and used everywhere. Getting their edge cases right matters.
+"""
+
+import re
+
+
+def validate_email(address):
+    """
+    Check whether a string looks like a valid email address.
+
+    This is a simplified check — real email validation is surprisingly
+    complex (RFC 5321 allows things you would never expect). We check for:
+    - At least one @ symbol
+    - Something before the @
+    - Something after the @ that contains a dot
+
+    Returns True if the address looks valid, False otherwise.
+    """
+    # An empty string or non-string input is never a valid email.
+    if not isinstance(address, str) or not address:
+        return False
+
+    # Use a simple regex pattern. This is not perfect, but it catches
+    # the most common mistakes: missing @, missing domain, missing dot.
+    # The pattern says: one or more characters, then @, then one or more
+    # characters, then a dot, then one or more characters.
+    pattern = r"^[^@\s]+@[^@\s]+\.[^@\s]+$"
+    return bool(re.match(pattern, address))
+
+
+def celsius_to_fahrenheit(celsius):
+    """
+    Convert a temperature from Celsius to Fahrenheit.
+
+    The formula is: F = C * 9/5 + 32
+
+    This is a textbook pure function — same input always gives same output,
+    no side effects. Perfect for parametrized testing because you can list
+    known conversion pairs and verify them all at once.
+    """
+    # The formula comes from the relationship between the two scales.
+    # Water freezes at 0°C / 32°F and boils at 100°C / 212°F.
+    return celsius * 9 / 5 + 32
+
+
+def is_palindrome(text):
+    """
+    Check whether a string reads the same forwards and backwards.
+
+    Ignores case and non-alphanumeric characters, so "A man, a plan,
+    a canal: Panama" is considered a palindrome.
+
+    Returns True if the text is a palindrome, False otherwise.
+    """
+    # Strip out everything that is not a letter or digit, then lowercase.
+    # This lets us handle punctuation and mixed case gracefully.
+    cleaned = re.sub(r"[^a-zA-Z0-9]", "", text).lower()
+
+    # An empty string after cleaning is technically a palindrome
+    # (it reads the same in both directions: nothing).
+    if not cleaned:
+        return True
+
+    # Compare the string to its reverse. Python's slice [::-1] reverses
+    # a string by stepping backwards through every character.
+    return cleaned == cleaned[::-1]
+
+
+def clamp(value, min_val, max_val):
+    """
+    Restrict a number to a given range.
+
+    If value is below min_val, return min_val.
+    If value is above max_val, return max_val.
+    Otherwise, return value unchanged.
+
+    This is a common utility in game development, UI code, and data
+    processing — anywhere you need to keep a number within bounds.
+    """
+    # Validate that the range makes sense. If someone passes min > max,
+    # that is a programming error and we should not silently return garbage.
+    if min_val > max_val:
+        raise ValueError(
+            f"min_val ({min_val}) must not be greater than max_val ({max_val})"
+        )
+
+    # Python's built-in min() and max() make this a one-liner.
+    # max(value, min_val) ensures we are at least min_val.
+    # min(..., max_val) ensures we do not exceed max_val.
+    return min(max(value, min_val), max_val)
+
+
+# ── Demo ────────────────────────────────────────────────────────────────
+# Run this file directly to see the functions in action.
+# The real tests are in tests/test_utils.py — run them with pytest.
+
+if __name__ == "__main__":
+    # Email validation examples
+    print("=== Email Validation ===")
+    test_emails = ["user@example.com", "bad-email", "", "a@b.c", "@missing.com"]
+    for email in test_emails:
+        print(f"  {email!r:30s} -> {validate_email(email)}")
+
+    # Temperature conversion examples
+    print("\n=== Celsius to Fahrenheit ===")
+    test_temps = [0, 100, -40, 37]
+    for c in test_temps:
+        print(f"  {c}°C -> {celsius_to_fahrenheit(c)}°F")
+
+    # Palindrome examples
+    print("\n=== Palindrome Check ===")
+    test_words = ["racecar", "hello", "A man a plan a canal Panama", ""]
+    for word in test_words:
+        print(f"  {word!r:40s} -> {is_palindrome(word)}")
+
+    # Clamp examples
+    print("\n=== Clamp ===")
+    test_clamps = [(5, 0, 10), (-3, 0, 10), (15, 0, 10), (5, 5, 5)]
+    for value, lo, hi in test_clamps:
+        print(f"  clamp({value}, {lo}, {hi}) -> {clamp(value, lo, hi)}")

projects/modules/08-testing-advanced/01-parametrize/tests/test_utils.py

@@ -0,0 +1,169 @@
+"""
+Tests for Project 01 — Parametrize
+
+This file demonstrates @pytest.mark.parametrize, which lets you run one
+test function with many different inputs. Instead of writing ten separate
+test functions that all look the same, you write one and give it a table
+of inputs and expected outputs.
+
+Run with: pytest tests/test_utils.py -v
+The -v flag shows each parametrize case as a separate line in the output.
+"""
+
+import pytest
+
+# Import the functions we are testing. The ".." means "go up one directory"
+# but pytest handles this automatically when you run from the project root.
+from project import validate_email, celsius_to_fahrenheit, is_palindrome, clamp
+
+
+# ── validate_email ──────────────────────────────────────────────────────
+# WHY: Email validation has many edge cases. A parametrized test lets us
+# list them all in one place and add new cases without writing new functions.
+
+@pytest.mark.parametrize(
+    "email, expected",
+    [
+        # --- Valid emails ---
+        ("user@example.com", True),           # Standard email
+        ("name.tag@domain.org", True),        # Dots in local part
+        ("user+filter@gmail.com", True),      # Plus addressing (common in Gmail)
+        ("x@y.io", True),                     # Minimal valid email
+        ("UPPER@CASE.COM", True),             # Case should not matter for format
+
+        # --- Invalid emails ---
+        ("missing-at-sign", False),           # No @ symbol at all
+        ("", False),                          # Empty string
+        ("@no-local-part.com", False),        # Nothing before @
+        ("spaces in@email.com", False),       # Spaces are not allowed
+        ("double@@at.com", False),            # Two @ symbols
+    ],
+    # ids makes the test output readable. Without it, pytest shows the raw
+    # parameter tuple. With it, you get a human-friendly label.
+    ids=[
+        "valid-user@example.com",
+        "valid-name.tag@domain.org",
+        "valid-plus-addressing",
+        "valid-minimal",
+        "valid-uppercase",
+        "invalid-missing-at",
+        "invalid-empty-string",
+        "invalid-no-local-part",
+        "invalid-spaces",
+        "invalid-double-at",
+    ],
+)
+def test_validate_email(email, expected):
+    """Each row in the parametrize table becomes a separate test case."""
+    assert validate_email(email) == expected
+
+
+# WHY: We also want to make sure non-string inputs are handled gracefully.
+# This is a separate parametrize because the input type is different.
+
+@pytest.mark.parametrize(
+    "bad_input",
+    [None, 42, [], {}],
+    ids=["none", "integer", "list", "dict"],
+)
+def test_validate_email_rejects_non_strings(bad_input):
+    """Non-string inputs should always return False, never crash."""
+    assert validate_email(bad_input) is False
+
+
+# ── celsius_to_fahrenheit ───────────────────────────────────────────────
+# WHY: Temperature conversion has well-known reference points. We test
+# the famous ones (freezing, boiling, body temp, the crossover point)
+# to make sure the formula is implemented correctly.
+
+@pytest.mark.parametrize(
+    "celsius, expected_fahrenheit",
+    [
+        (0, 32.0),        # Freezing point of water
+        (100, 212.0),     # Boiling point of water
+        (-40, -40.0),     # The crossover point (same in both scales!)
+        (37, 98.6),       # Human body temperature
+        (-273.15, -459.67),  # Absolute zero
+    ],
+    ids=["freezing", "boiling", "crossover", "body-temp", "absolute-zero"],
+)
+def test_celsius_to_fahrenheit(celsius, expected_fahrenheit):
+    """Verify known temperature conversion pairs."""
+    # We use pytest.approx because floating-point math can introduce tiny
+    # rounding errors. pytest.approx checks that the values are "close enough"
+    # (within a very small tolerance, by default 1e-6).
+    assert celsius_to_fahrenheit(celsius) == pytest.approx(expected_fahrenheit)
+
+
+# ── is_palindrome ───────────────────────────────────────────────────────
+# WHY: Palindrome checking involves string cleaning (removing punctuation,
+# ignoring case). We need to test both the core logic and the cleaning.
+
+@pytest.mark.parametrize(
+    "text, expected",
+    [
+        ("racecar", True),                          # Classic palindrome
+        ("hello", False),                           # Clearly not a palindrome
+        ("A man a plan a canal Panama", True),      # Sentence palindrome with spaces
+        ("Was it a car or a cat I saw?", True),     # Punctuation and mixed case
+        ("", True),                                 # Empty string is a palindrome
+        ("a", True),                                # Single character
+        ("ab", False),                              # Two different characters
+        ("Madam", True),                            # Mixed case palindrome
+    ],
+    ids=[
+        "racecar",
+        "hello",
+        "sentence-palindrome",
+        "punctuation-mixed-case",
+        "empty-string",
+        "single-char",
+        "two-different-chars",
+        "mixed-case-madam",
+    ],
+)
+def test_is_palindrome(text, expected):
+    """Test palindrome detection with various inputs including edge cases."""
+    assert is_palindrome(text) == expected
+
+
+# ── clamp ───────────────────────────────────────────────────────────────
+# WHY: Clamp has three distinct behaviors (below min, above max, in range)
+# plus edge cases at the boundaries. Parametrize lets us cover them all
+# in a compact table.
+
+@pytest.mark.parametrize(
+    "value, min_val, max_val, expected",
+    [
+        (5, 0, 10, 5),       # Value already in range — returned unchanged
+        (-3, 0, 10, 0),      # Below minimum — clamped up to min
+        (15, 0, 10, 10),     # Above maximum — clamped down to max
+        (0, 0, 10, 0),       # Exactly at minimum — boundary case
+        (10, 0, 10, 10),     # Exactly at maximum — boundary case
+        (5, 5, 5, 5),        # Min equals max — only one valid value
+        (-100, -50, 50, -50),  # Negative range
+        (3.5, 0, 10, 3.5),  # Float value in range
+    ],
+    ids=[
+        "in-range",
+        "below-minimum",
+        "above-maximum",
+        "at-minimum",
+        "at-maximum",
+        "single-point-range",
+        "negative-range",
+        "float-value",
+    ],
+)
+def test_clamp(value, min_val, max_val, expected):
+    """Test clamp with values inside, outside, and at the boundaries."""
+    assert clamp(value, min_val, max_val) == expected
+
+
+# WHY: Clamp should raise an error when min > max. This is a separate test
+# because we are testing for an exception, not a return value.
+
+def test_clamp_raises_on_invalid_range():
+    """Passing min > max is a programming error and should raise ValueError."""
+    with pytest.raises(ValueError, match="must not be greater than"):
+        clamp(5, 10, 0)