Add docker and snapshot checks

Author: Boyeep

.github/workflows/template-ci.yml

@@ -131,3 +131,16 @@ jobs:
 
       - name: Run root verification
         run: npm run check
+
+  docker-images:
+    name: Docker Images
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build backend image
+        run: docker build --target runner --tag cv-kit-backend:ci ./backend
+
+      - name: Build frontend image
+        run: docker build --target runner --tag cv-kit-frontend:ci ./frontend

CONTRIBUTING.md

@@ -63,6 +63,12 @@ What they cover:
 - `check:contract`: regenerates frontend API types and fails if generated files drift from `docs/openapi.yaml`
 - `check`: frontend lint, frontend typecheck, frontend production build, backend Ruff lint, backend tests, backend bytecode compile
 
+If Docker is available locally, you can also verify the production-style images:
+
+```bash
+npm run check:images
+```
+
 ## Changing the API Contract
 
 If you modify request or response shapes:

README.md

@@ -93,6 +93,7 @@ npm run dev
 npm run dev:down
 npm run api:types
 npm run check:contract
+npm run check:images
 npm run check
 ```
 
@@ -107,6 +108,8 @@ The root check runs:
 - backend `pytest`
 - backend `compileall`
 
+`check:images` is separate and intended for environments where a Docker daemon is available.
+
 ## Contract Notes
 
 - `docs/openapi.yaml` is the source of truth for the HTTP contract.

backend/.dockerignore

@@ -0,0 +1,6 @@
+.venv/
+.pytest_cache/
+__pycache__/
+tests/
+*.pyc
+*.pyo

backend/Dockerfile

@@ -0,0 +1,33 @@
+FROM python:3.12-slim AS base
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+
+RUN apt-get update \
+    && apt-get install --yes --no-install-recommends libglib2.0-0 libgl1 \
+    && rm -rf /var/lib/apt/lists/*
+
+FROM base AS dev
+
+COPY pyproject.toml README.md ./
+COPY app ./app
+
+RUN python -m pip install --upgrade pip \
+    && python -m pip install -e ".[dev]"
+
+CMD ["python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]
+
+FROM base AS runner
+
+COPY pyproject.toml README.md ./
+COPY app ./app
+
+RUN python -m pip install --upgrade pip \
+    && python -m pip install .
+
+EXPOSE 8000
+
+CMD ["python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

backend/README.md

@@ -29,3 +29,6 @@ python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
 python -m ruff check .
 python -m pytest
 ```
+
+The backend test suite now includes committed image fixtures and snapshot-backed API
+regression checks for the starter inference routes.

backend/tests/helpers.py

@@ -1,6 +1,8 @@
+import json
 from pathlib import Path
 
 FIXTURE_DIR = Path(__file__).parent / "fixtures"
+SNAPSHOT_DIR = Path(__file__).parent / "snapshots"
 
 
 def fixture_path(name: str) -> Path:
@@ -9,3 +11,14 @@ def fixture_path(name: str) -> Path:
 
 def fixture_bytes(name: str) -> bytes:
     return fixture_path(name).read_bytes()
+
+
+def snapshot_json(name: str) -> dict:
+    return json.loads((SNAPSHOT_DIR / name).read_text(encoding="utf-8"))
+
+
+def normalize_analysis_payload(payload: dict) -> dict:
+    normalized = json.loads(json.dumps(payload))
+    normalized["analysis_id"] = "<analysis-id>"
+    normalized["generated_at"] = "<generated-at>"
+    return normalized

backend/tests/snapshots/foreground-segmentation-response.json

@@ -0,0 +1,134 @@
+{
+  "analysis_id": "<analysis-id>",
+  "pipeline": {
+    "id": "foreground-segmentation",
+    "name": "Foreground Segmentation",
+    "summary": "Segmentation extension pipeline that returns region polygons plus detection-style boxes.",
+    "tags": [
+      "segmentation",
+      "extension",
+      "cpu"
+    ],
+    "runtime": "opencv-cpu",
+    "sample_outputs": [
+      "region polygons",
+      "mask coverage",
+      "derived boxes"
+    ]
+  },
+  "image": {
+    "filename": "segmentation-scene.png",
+    "content_type": "image/png",
+    "width": 320,
+    "height": 240
+  },
+  "detections": [
+    {
+      "label": "segment-region",
+      "confidence": 0.734,
+      "box": {
+        "x": 51,
+        "y": 71,
+        "width": 107,
+        "height": 107
+      },
+      "area_ratio": 0.117
+    },
+    {
+      "label": "segment-region",
+      "confidence": 0.651,
+      "box": {
+        "x": 197,
+        "y": 74,
+        "width": 87,
+        "height": 130
+      },
+      "area_ratio": 0.0753
+    }
+  ],
+  "segmentations": [
+    {
+      "label": "segment-region",
+      "confidence": 0.734,
+      "polygon": [
+        {
+          "x": 94,
+          "y": 71
+        },
+        {
+          "x": 60,
+          "y": 93
+        },
+        {
+          "x": 51,
+          "y": 134
+        },
+        {
+          "x": 73,
+          "y": 168
+        },
+        {
+          "x": 114,
+          "y": 177
+        },
+        {
+          "x": 148,
+          "y": 155
+        },
+        {
+          "x": 157,
+          "y": 114
+        },
+        {
+          "x": 135,
+          "y": 80
+        }
+      ],
+      "box": {
+        "x": 51,
+        "y": 71,
+        "width": 107,
+        "height": 107
+      },
+      "area_ratio": 0.117
+    },
+    {
+      "label": "segment-region",
+      "confidence": 0.651,
+      "polygon": [
+        {
+          "x": 212,
+          "y": 74
+        },
+        {
+          "x": 197,
+          "y": 203
+        },
+        {
+          "x": 283,
+          "y": 156
+        }
+      ],
+      "box": {
+        "x": 197,
+        "y": 74,
+        "width": 87,
+        "height": 130
+      },
+      "area_ratio": 0.0753
+    }
+  ],
+  "metrics": [
+    {
+      "name": "segmented_regions",
+      "value": 2,
+      "unit": null
+    },
+    {
+      "name": "segmented_coverage",
+      "value": 0.1923,
+      "unit": null
+    }
+  ],
+  "generated_at": "<generated-at>"
+}

backend/tests/snapshots/starter-detection-response.json

@@ -0,0 +1,68 @@
+{
+  "analysis_id": "<analysis-id>",
+  "pipeline": {
+    "id": "starter-detection",
+    "name": "Starter Detection",
+    "summary": "Detection-first sample pipeline that returns object-style boxes and confidence scores.",
+    "tags": [
+      "detection",
+      "default",
+      "cpu"
+    ],
+    "runtime": "opencv-cpu",
+    "sample_outputs": [
+      "object boxes",
+      "confidence scores",
+      "coverage metrics"
+    ]
+  },
+  "image": {
+    "filename": "detection-scene.png",
+    "content_type": "image/png",
+    "width": 320,
+    "height": 240
+  },
+  "detections": [
+    {
+      "label": "primary-object",
+      "confidence": 0.98,
+      "box": {
+        "x": 27,
+        "y": 33,
+        "width": 188,
+        "height": 150
+      },
+      "area_ratio": 0.3672
+    },
+    {
+      "label": "object-candidate",
+      "confidence": 0.614,
+      "box": {
+        "x": 222,
+        "y": 134,
+        "width": 73,
+        "height": 73
+      },
+      "area_ratio": 0.0694
+    }
+  ],
+  "segmentations": [],
+  "metrics": [
+    {
+      "name": "edge_density",
+      "value": 0.012,
+      "unit": null
+    },
+    {
+      "name": "object_candidates",
+      "value": 2,
+      "unit": null
+    },
+    {
+      "name": "largest_detection_ratio",
+      "value": 0.3672,
+      "unit": null
+    }
+  ],
+  "generated_at": "<generated-at>"
+}

backend/tests/test_inference_route.py

@@ -1,12 +1,12 @@
 from fastapi.testclient import TestClient
 
 from app.main import app
-from tests.helpers import fixture_bytes
+from tests.helpers import fixture_bytes, normalize_analysis_payload, snapshot_json
 
 client = TestClient(app)
 
 
-def test_analyze_route_accepts_fixture_upload() -> None:
+def test_analyze_route_matches_starter_detection_snapshot() -> None:
     response = client.post(
         "/api/v1/analyze",
         data={"pipeline_id": "starter-detection"},
@@ -20,10 +20,28 @@ def test_analyze_route_accepts_fixture_upload() -> None:
     )
 
     assert response.status_code == 200
-    payload = response.json()
-    assert payload["pipeline"]["id"] == "starter-detection"
-    assert payload["image"]["filename"] == "detection-scene.png"
-    assert len(payload["detections"]) >= 2
+    assert normalize_analysis_payload(response.json()) == snapshot_json(
+        "starter-detection-response.json"
+    )
+
+
+def test_analyze_route_matches_segmentation_snapshot() -> None:
+    response = client.post(
+        "/api/v1/analyze",
+        data={"pipeline_id": "foreground-segmentation"},
+        files={
+            "file": (
+                "segmentation-scene.png",
+                fixture_bytes("segmentation-scene.png"),
+                "image/png",
+            )
+        },
+    )
+
+    assert response.status_code == 200
+    assert normalize_analysis_payload(response.json()) == snapshot_json(
+        "foreground-segmentation-response.json"
+    )
 
 
 def test_analyze_route_rejects_non_image_upload() -> None: