test(backend): add FastAPI route tests with fake predictor service

Adds backend/app/tests/ covering the GET /healthz and POST /v1/captions contracts end-to-end without loading TensorFlow or any real model. A duck-typed FakePredictorService stands in on app.state, bypassing the lifespan. Covers 200, 400, 413, 415, 422, 503 plus request-id propagation through x-request-id.

pyproject.toml: pythonpath = ["backend"] under [tool.pytest.ini_options] so 'from app.* import ...' resolves under pytest from the repo root.

12 new tests, full suite 90 passing in ~30s.

CLAUDE.md

@@ -0,0 +1,73 @@
+# Project Conventions for Claude Code
+
+## CRITICAL: Commit & Attribution Rules
+
+**Claude Code MUST follow these rules without exception:**
+
+1. **NEVER add `Co-Authored-By: Claude` or any AI co-author trailer to commit messages.**
+2. **NEVER add `🤖 Generated with Claude Code` footers or any AI attribution.**
+3. **NEVER mention Claude, Anthropic, OpenAI, Copilot, AI, LLMs, or any model/assistant name in commit messages, code comments, file headers, documentation, PR descriptions, or changelogs.**
+4. **All commits must be authored solely by:**
+   - Name: `apoorvrajdev`
+   - Email: `apoorvrajmgr@gmail.com`
+5. **NEVER stage or commit changes on your own.** Only suggest commit messages — the user runs `git commit` themselves.
+6. **NEVER push to remote.** Only the user pushes.
+7. **NEVER create branches, tags, or releases on your own.**
+
+## Commit Message Format
+
+Use Conventional Commits. Examples:
+- `chore: initial repo scaffolding`
+- `feat(backend): add /caption endpoint for image upload`
+- `feat(inference): add beam search decoder`
+- `fix(data): correct COCO split deduplication`
+- `fix(training): stabilize loss scaling for mixed precision`
+- `docs: update stabilized training runbook`
+- `test(evaluation): add BLEU/CIDEr metric tests`
+- `refactor(models): extract encoder CNN factory`
+- `perf(inference): cache image features for batched predict`
+
+Keep subject under 72 characters. Body optional but explains *why*, not *what*.
+
+## Project Stack
+
+- **Core ML:** Python 3.10+, TensorFlow / Keras, NumPy, Pillow
+- **Model:** InceptionV3 encoder + Transformer decoder for image captioning
+- **Backend:** FastAPI app under `backend/app/` (routes, services, schemas, utils)
+- **Frontend:** React 18 + Vite (JSX) under `frontend/`, ESLint configured
+- **Config:** YAML configs under `configs/` loaded via `src/captioning/config/`
+- **Data:** MS COCO pipeline under `src/captioning/data/`
+- **Evaluation:** BLEU, CIDEr, METEOR, ROUGE under `src/captioning/evaluation/`
+- **Tooling:** `pyproject.toml`, `Makefile`, `pytest`, packaging as `captioning`
+
+## Repository Layout (authoritative)
+
+- `src/captioning/` — installable library (`config`, `data`, `models`, `preprocessing`, `training`, `inference`, `evaluation`, `utils`)
+- `backend/app/` — FastAPI service (`api/routes.py`, `services/predictor_service.py`, `schemas/`, `core/`, `utils/`)
+- `frontend/src/` — React UI (`components/`, `services/api.js`)
+- `scripts/` — CLI entrypoints (`train.py`, `evaluate.py`, `predict.py`, etc.)
+- `configs/` — YAML training/eval configs
+- `models/vX.Y.Z/` — versioned model artifacts (`model.h5`, `vocab.json`)
+- `tests/unit/` — pytest unit tests
+- `notebooks/` — exploratory notebooks (not part of runtime)
+- `docs/` — phase notes and runbooks
+
+## Code Standards
+
+- **Python:** type hints on all new/edited public functions; prefer `pathlib.Path` over string paths
+- **Imports:** absolute imports from `captioning.*`; no relative imports across top-level packages
+- **Determinism:** seed NumPy / TF / Python `random` whenever introducing stochastic code paths in training or evaluation
+- **Configs:** never hardcode hyperparameters in scripts — extend `src/captioning/config/schema.py` and update the relevant YAML in `configs/`
+- **Models / vocab:** never modify files under `models/vX.Y.Z/` in place; bump the version directory instead
+- **Backend layering:** `api/routes.py` only orchestrates; inference logic stays in `backend/app/services/` and `src/captioning/inference/`
+- **Schemas:** all FastAPI request/response bodies go through Pydantic schemas in `backend/app/schemas/`
+- **Frontend:** functional components + hooks; keep API calls inside `frontend/src/services/api.js`
+- **Tests:** new behavior gets a unit test under `tests/unit/`; keep tests CPU-only and offline (no network, no real model downloads)
+
+## Working Style
+
+- Plan before implementing for any non-trivial change (training loop, decoder, data pipeline, API contract)
+- One module at a time, with tests
+- Run `pytest` for touched areas before declaring a change done
+- After making changes, summarize what you did so the user can review and commit
+- If a change spans library + backend + frontend, list the affected files grouped by layer in the summary

backend/app/tests/conftest.py

@@ -0,0 +1,92 @@
+"""Shared fixtures for the backend test suite.
+
+These tests deliberately avoid loading TensorFlow or any real model.
+The route layer depends on ``PredictorService`` only through duck-typed
+attributes (``model_version``, ``decode_strategy``, ``max_upload_bytes``,
+``caption_image_bytes``), so a small fake stands in cleanly and keeps the
+whole suite under one second.
+
+We also bypass the FastAPI lifespan entirely. The lifespan builds a real
+``CaptionPredictor`` from disk, which requires weights, a tokenizer, and a
+TF graph build. Tests build a fresh ``FastAPI`` instance, wire the same
+router and middleware, and stash the fake service directly on
+``app.state.predictor_service`` — the exact slot the lifespan would have
+populated in production.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from app.api.routes import router
+from app.core.config import BackendSettings
+from app.core.logging import RequestContextMiddleware, configure_app_logging
+from app.utils.image import ImageDecodeError
+
+configure_app_logging()
+
+
+class FakePredictorService:
+    """Duck-typed stand-in for ``PredictorService``."""
+
+    def __init__(
+        self,
+        *,
+        caption: str = "a test caption",
+        latency_ms: float = 1.23,
+        decode_strategy: str = "greedy",
+        model_version: str = "test-v0",
+        max_upload_bytes: int = 1024,
+        raise_decode_error: bool = False,
+    ) -> None:
+        self.model_version = model_version
+        self.decode_strategy = decode_strategy
+        self.max_upload_bytes = max_upload_bytes
+        self._caption = caption
+        self._latency_ms = latency_ms
+        self._raise = raise_decode_error
+        self.calls: list[bytes] = []
+
+    async def caption_image_bytes(self, image_bytes: bytes) -> tuple[str, float]:
+        self.calls.append(image_bytes)
+        if self._raise:
+            raise ImageDecodeError("synthetic decode failure")
+        return self._caption, self._latency_ms
+
+
+def _build_app(service: FakePredictorService | None) -> FastAPI:
+    app = FastAPI()
+    app.state.backend_settings = BackendSettings()
+    app.state.predictor_service = service
+    app.add_middleware(RequestContextMiddleware)
+    app.include_router(router)
+    return app
+
+
+@pytest.fixture
+def fake_service() -> FakePredictorService:
+    return FakePredictorService()
+
+
+@pytest.fixture
+def client(fake_service: FakePredictorService) -> Iterator[TestClient]:
+    with TestClient(_build_app(fake_service)) as test_client:
+        yield test_client
+
+
+@pytest.fixture
+def client_without_service() -> Iterator[TestClient]:
+    with TestClient(_build_app(None)) as test_client:
+        yield test_client
+
+
+@pytest.fixture
+def build_client() -> Callable[[FakePredictorService | None], TestClient]:
+    def _make(service: FakePredictorService | None) -> TestClient:
+        return TestClient(_build_app(service))
+
+    return _make

backend/app/tests/test_captions.py

@@ -0,0 +1,87 @@
+"""Tests for ``POST /v1/captions``.
+
+Covers the route's status-code contract end-to-end:
+
+* 200 — happy path, typed ``CaptionResponse`` body
+* 400 — empty file upload
+* 413 — payload above ``max_upload_bytes``
+* 415 — disallowed content type
+* 422 — bytes that the predictor cannot decode (synthetic)
+* 503 — predictor not yet loaded
+"""
+
+from __future__ import annotations
+
+from fastapi.testclient import TestClient
+
+from app.tests.conftest import FakePredictorService
+
+
+def _image_field(payload: bytes, content_type: str = "image/jpeg", name: str = "a.jpg"):
+    return {"image": (name, payload, content_type)}
+
+
+def test_captions_happy_path_returns_typed_response(
+    client: TestClient, fake_service: FakePredictorService
+) -> None:
+    response = client.post("/v1/captions", files=_image_field(b"\xff\xd8stub"))
+    assert response.status_code == 200
+
+    body = response.json()
+    assert body["caption"] == "a test caption"
+    assert body["model_version"] == "test-v0"
+    assert body["decode_strategy"] == "greedy"
+    assert body["latency_ms"] == 1.23
+    assert body["request_id"]
+
+    # Service actually received the upload payload.
+    assert fake_service.calls == [b"\xff\xd8stub"]
+
+
+def test_captions_request_id_matches_response_header(client: TestClient) -> None:
+    response = client.post(
+        "/v1/captions",
+        files=_image_field(b"\xff\xd8stub"),
+        headers={"x-request-id": "trace-123"},
+    )
+    assert response.status_code == 200
+    assert response.headers.get("x-request-id") == "trace-123"
+    assert response.json()["request_id"] == "trace-123"
+
+
+def test_captions_rejects_unsupported_content_type(client: TestClient) -> None:
+    response = client.post(
+        "/v1/captions",
+        files=_image_field(b"hello", content_type="text/plain", name="a.txt"),
+    )
+    assert response.status_code == 415
+    assert "Unsupported content type" in response.json()["detail"]
+
+
+def test_captions_rejects_empty_upload(client: TestClient) -> None:
+    response = client.post("/v1/captions", files=_image_field(b""))
+    assert response.status_code == 400
+    assert "Empty" in response.json()["detail"]
+
+
+def test_captions_rejects_oversize_upload(client: TestClient) -> None:
+    # Fake service.max_upload_bytes = 1024
+    response = client.post("/v1/captions", files=_image_field(b"x" * 2048))
+    assert response.status_code == 413
+    assert "limit" in response.json()["detail"].lower()
+
+
+def test_captions_returns_422_on_decode_failure(build_client) -> None:
+    bad_service = FakePredictorService(raise_decode_error=True)
+    with build_client(bad_service) as test_client:
+        response = test_client.post("/v1/captions", files=_image_field(b"\xff\xd8junk"))
+    assert response.status_code == 422
+    assert "synthetic decode failure" in response.json()["detail"]
+
+
+def test_captions_returns_503_when_predictor_not_loaded(
+    client_without_service: TestClient,
+) -> None:
+    response = client_without_service.post("/v1/captions", files=_image_field(b"\xff\xd8stub"))
+    assert response.status_code == 503
+    assert "not ready" in response.json()["detail"].lower()

backend/app/tests/test_health.py

@@ -0,0 +1,56 @@
+"""Tests for ``GET /healthz``.
+
+The route reports liveness + readiness in the response body and always
+returns 200; readiness is conveyed by ``model_loaded``.
+"""
+
+from __future__ import annotations
+
+from fastapi.testclient import TestClient
+
+from app.tests.conftest import FakePredictorService
+
+
+def test_healthz_reports_ready_when_service_present(client: TestClient) -> None:
+    response = client.get("/healthz")
+    assert response.status_code == 200
+
+    body = response.json()
+    assert body["status"] == "ok"
+    assert body["model_loaded"] is True
+    assert body["model_version"] == "test-v0"
+    assert body["api_version"]
+    assert "timestamp" in body
+
+
+def test_healthz_reports_loading_when_service_missing(
+    client_without_service: TestClient,
+) -> None:
+    response = client_without_service.get("/healthz")
+    assert response.status_code == 200
+
+    body = response.json()
+    assert body["status"] == "loading"
+    assert body["model_loaded"] is False
+
+
+def test_healthz_echoes_request_id_header(client: TestClient) -> None:
+    response = client.get("/healthz", headers={"x-request-id": "deadbeef"})
+    assert response.status_code == 200
+    assert response.headers.get("x-request-id") == "deadbeef"
+
+
+def test_healthz_generates_request_id_when_absent(client: TestClient) -> None:
+    response = client.get("/healthz")
+    assert response.status_code == 200
+    rid = response.headers.get("x-request-id")
+    assert rid and len(rid) >= 16
+
+
+def test_healthz_uses_overridden_model_version(
+    build_client,
+) -> None:
+    service = FakePredictorService(model_version="v9.9.9")
+    with build_client(service) as test_client:
+        body = test_client.get("/healthz").json()
+        assert body["model_version"] == "v9.9.9"

pyproject.toml

@@ -211,6 +211,7 @@ ignore_missing_imports = true
 [tool.pytest.ini_options]
 minversion = "8.0"
 testpaths = ["tests", "backend/app/tests"]
+pythonpath = ["backend"]         # Lets `from app.* import ...` resolve in tests
 addopts = [
     "-ra",                       # Show short summary for non-passing tests
     "--strict-markers",