feat(api): 100% line coverage gate and PLAN §3.6

- Add pytest-cov with fail-under=100; omit generated OpenAPI models from coverage
- Exclude Protocol ellipsis stubs from coverage report; pragma on codegen __main__
- Add codegen tests and repository edge-case tests for full measured coverage
- Document testing and coverage in apps/api README; tick PLAN §3.6
- Ignore .coverage/htmlcov; clarify CI test step for coverage gate

Made-with: Cursor

Author: mcalthrop

.github/workflows/ci.yml

@@ -37,7 +37,7 @@ jobs:
       - name: Lint
         run: pnpm lint
 
-      - name: Test
+      - name: Test (API 100% line coverage gate)
         run: pnpm test
 
       - name: Generate OpenAPI code

.gitignore

@@ -16,6 +16,9 @@ venv/
 __pycache__/
 *.py[cod]
 .pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
 .mypy_cache/
 .ruff_cache/
 *.egg-info/

PLAN.md

@@ -20,7 +20,7 @@ Tasks and subtasks for building the bread-recipes app (SolidJS + Python REST + O
 - [x] **3.3** Wire FastAPI/OpenAPI **`info`** (title, version, description) from **`packages/openapi/openapi.yaml`** so the running app matches the committed spec and those values are not duplicated in code (e.g. `main.py`).
 - [x] **3.4** Implement REST handlers to match the OpenAPI spec (response shapes and status codes); keep behaviour aligned with the spec.
 - [x] **3.5** Generate Pydantic models from **`packages/openapi/openapi.yaml`** (e.g. **datamodel-code-generator**), commit generated output, and add CI that fails when the spec changes without regenerating (drift check).
-- [ ] **3.6** Tests with 100% coverage and a coverage gate in CI for the API package; add `README.md` for install, run, and test commands.
+- [x] **3.6** Tests with 100% coverage and a coverage gate in CI for the API package; add `README.md` for install, run, and test commands.
 - [ ] **3.7** Select and configure a Python import-ordering tool (PEP 8–aligned; e.g. **Ruff**’s isort rules or **isort**), apply it across **`apps/api`**, and document how to run it (CI enforcement can align with §3.6 / §6.1).
 
 ## 4. SolidJS front end

apps/api/README.md

@@ -1,6 +1,6 @@
 # Bread Recipes API (Python)
 
-FastAPI ASGI service: **`GET /health`**, **`GET /recipes`**, and **`GET /recipes/{recipe_id}`**; further PLAN work covers coverage and tooling.
+FastAPI ASGI service: **`GET /health`**, **`GET /recipes`**, and **`GET /recipes/{recipe_id}`**.
 
 ### Package layout
 
@@ -32,6 +32,22 @@ source .venv/bin/activate
 pip install -e ".[dev]"
 ```
 
+## Testing
+
+From **`apps/api`** with dev dependencies installed (**`pip install -e ".[dev]"`**):
+
+```bash
+pnpm test
+```
+
+This runs **`pytest`** with **line coverage** for the **`app`** package, **fails under 100%**, and **omits** generated **`app/openapi/generated/`** (codegen output). To run tests without coverage (faster iteration):
+
+```bash
+.venv/bin/python -m pytest --no-cov
+```
+
+Configuration lives in **`pyproject.toml`** (**`[tool.pytest.ini_options]`**, **`[tool.coverage.*]`**).
+
 ## Run (development)
 
 ```bash
@@ -84,4 +100,4 @@ These editors use the **Python** extension (Cursor ships with equivalent behavio
 
 If analysis still looks wrong, reload the window (**Developer: Reload Window** from the Command Palette) after changing the interpreter.
 
-**Why this path:** analysis runs with `sys.path` set for that interpreter; the editable install of **`recipes-api`** is only guaranteed for the venv you created with **`pip install -e ".[dev]"`**.
+**Why this path:** analysis runs with `sys.path` set for that interpreter; the editable install of the **`recipes-api`** package (**`app`**) is only guaranteed for the venv you created with **`pip install -e ".[dev]"`**.

apps/api/app/openapi/codegen.py

@@ -32,5 +32,5 @@ def main() -> None:
     )
 
 
-if __name__ == "__main__":
+if __name__ == "__main__":  # pragma: no cover
     main()

apps/api/app/openapi/codegen_test.py

@@ -0,0 +1,45 @@
+"""Tests for OpenAPI Pydantic codegen CLI."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+
+from app.openapi import codegen
+
+
+def test_main_exits_when_openapi_file_missing(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    missing = tmp_path / "missing.yaml"
+    monkeypatch.setattr(
+        "app.openapi.codegen.resolve_openapi_spec_path",
+        lambda: missing,
+    )
+    with pytest.raises(SystemExit) as exc_info:
+        codegen.main()
+    assert exc_info.value.code == 1
+
+
+def test_main_invokes_datamodel_generate(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    spec = tmp_path / "openapi.yaml"
+    spec.write_text(
+        'openapi: "3.1.0"\n'
+        "info:\n"
+        '  title: "T"\n'
+        '  version: "1"\n'
+        '  description: "D"\n'
+        "paths: {}\n",
+        encoding="utf-8",
+    )
+    out = tmp_path / "gen" / "openapi_models.py"
+    monkeypatch.setattr("app.openapi.codegen.resolve_openapi_spec_path", lambda: spec)
+    monkeypatch.setattr("app.openapi.codegen._OUTPUT", out)
+    mock_generate = MagicMock()
+    monkeypatch.setattr("app.openapi.codegen.generate", mock_generate)
+    codegen.main()
+    mock_generate.assert_called_once()
+    assert out.parent.is_dir()

apps/api/app/routers/recipes/repository_test.py

@@ -90,6 +90,29 @@ def test_invalid_file_raises(tmp_path: Path, bad_payload: str) -> None:
         StaticRecipeRepository(data_path=path)
 
 
+def test_array_entry_must_be_object(tmp_path: Path) -> None:
+    path = tmp_path / "bad.json"
+    path.write_text(json.dumps(["not-an-object"]), encoding="utf-8")
+    with pytest.raises(ValueError, match=r"recipes\.json\[0\] must be an object"):
+        StaticRecipeRepository(data_path=path)
+
+
+def test_ingredients_and_steps_must_be_arrays(tmp_path: Path) -> None:
+    row: dict[str, Any] = {
+        "id": "a",
+        "title": "T",
+        "summary": "S",
+        "imageUrl": "https://example.com/1.jpg",
+        "imageUrlLarge": "https://example.com/2.jpg",
+        "ingredients": "not-a-list",
+        "steps": ["mix"],
+    }
+    path = tmp_path / "bad.json"
+    path.write_text(json.dumps([row]), encoding="utf-8")
+    with pytest.raises(ValueError, match="ingredients and steps must be arrays"):
+        StaticRecipeRepository(data_path=path)
+
+
 def test_duplicate_ids_raise(tmp_path: Path) -> None:
     recipes_with_duplicate_ids: list[dict[str, Any]] = [
         {

apps/api/pyproject.toml

@@ -19,6 +19,7 @@ dependencies = [
 dev = [
   "httpx==0.28.1",
   "pytest==8.3.5",
+  "pytest-cov==6.0.0",
 ]
 
 [tool.hatch.build.targets.wheel]
@@ -29,4 +30,16 @@ exclude = ["**/app/**/*_test.py"]
 testpaths = ["app"]
 pythonpath = ["."]
 python_files = ["*_test.py"]
-addopts = "-q"
+addopts = "-q --cov=app --cov-report=term-missing --cov-fail-under=100"
+
+[tool.coverage.run]
+source = ["app"]
+omit = ["app/openapi/generated/*"]
+
+[tool.coverage.report]
+fail_under = 100
+exclude_lines = [
+  "pragma: no cover",
+  "if TYPE_CHECKING:",
+  "^ *\\.\\.\\.$",
+]