test(tests): normalize player stub to fake, rename 404 test (#559)

CHANGELOG.md

@@ -53,6 +53,12 @@ This project uses famous football coaches as release codenames, following an A-Z
 
 ### Changed
 
+- `tests/player_stub.py` renamed to `tests/player_fake.py`; class docstring
+  updated to reflect fake (not stub) role; module-level docstring added
+  documenting the three-term data-state vocabulary (`existing`, `nonexistent`,
+  `unknown`); imports in `conftest.py` and `test_main.py` updated accordingly;
+  `test_request_get_player_id_nonexistent_response_status_not_found` renamed to
+  `test_request_get_player_id_unknown_response_status_not_found` (#559)
 - `GET /players/` cache check changed from `if not players` to
   `if players is None` so that an empty collection is cached correctly
   instead of triggering a DB fetch on every request (#530)

tests/conftest.py

@@ -4,7 +4,7 @@
 import pytest
 from fastapi.testclient import TestClient
 from main import app
-from tests.player_stub import Player, nonexistent_player
+from tests.player_fake import Player, nonexistent_player
 
 # Suppress the DeprecationWarning from httpx
 warnings.filterwarnings("ignore", category=DeprecationWarning)
@@ -31,7 +31,7 @@ def nonexistent_player_in_db(client: Any) -> Generator[Player, None, None]:
     Creates the nonexistent player in the database and removes it on teardown.
 
     Yields:
-        Player: The player stub created in the database.
+        Player: The fake player created in the database.
     """
     player: Player = nonexistent_player()
     client.post("/players/", json=player.__dict__)

tests/player_stub.py → tests/player_fake.py

@@ -1,6 +1,16 @@
+"""
+Test fakes for Player data-state scenarios.
+
+Three-term vocabulary:
+    existing     — player is present in the database
+    nonexistent  — player is absent, valid shape for creation (POST scenarios)
+    unknown      — valid ID format, absent from database (404-by-lookup scenarios)
+"""
+
+
 class Player:
     """
-    Test stub representing a Player.
+    Test fake representing a Player.
     """
 
     def __init__(
@@ -30,9 +40,9 @@ def __init__(
         self.starting11 = starting11
 
 
-def existing_player():
+def existing_player() -> Player:
     """
-    Creates a test stub for an existing Player.
+    Creates a test fake for an existing Player.
     """
     return Player(
         id="01772c59-43f0-5d85-b913-c78e4e281452",
@@ -49,9 +59,9 @@ def existing_player():
     )
 
 
-def nonexistent_player():
+def nonexistent_player() -> Player:
     """
-    Creates a test stub for a nonexistent (new) Player.
+    Creates a test fake for a nonexistent (new) Player.
     No id is provided; the server generates a UUID on creation.
     """
     return Player(
@@ -67,9 +77,9 @@ def nonexistent_player():
     )
 
 
-def unknown_player():
+def unknown_player() -> Player:
     """
-    Creates a test stub for an unknown Player (valid UUID format, not in database).
+    Creates a test fake for an unknown Player (valid UUID format, not in database).
     """
     return Player(
         id="00000000-0000-0000-0000-000000000000",

tests/test_main.py

@@ -18,7 +18,7 @@
 
 from uuid import UUID
 
-from tests.player_stub import (
+from tests.player_fake import (
     existing_player,
     nonexistent_player,
     unknown_player,
@@ -92,8 +92,8 @@ def test_request_get_players_response_body_each_player_has_uuid(client):
 # GET /players/{player_id} -----------------------------------------------------
 
 
-def test_request_get_player_id_nonexistent_response_status_not_found(client):
-    """GET /players/{player_id} with nonexistent UUID returns 404 Not Found"""
+def test_request_get_player_id_unknown_response_status_not_found(client):
+    """GET /players/{player_id} with unknown UUID returns 404 Not Found"""
     # Arrange
     player_id = unknown_player().id
     # Act