test: add unit test infrastructure (Docker tester stage + CI)

- Add Dockerfile 'tester' stage (FROM builder):
  - Symlinks /usr/local/cuda/lib64/stubs/libcuda.so → libcuda.so.1
    so the test binary can satisfy the dynamic linker without a real GPU
  - Runs `cargo test --release` reusing the cached release build artifacts
    (no recompilation — tests complete in ~6s)
  - docker build --target tester . to run all 30 unit tests

- Add 'test' job to .gitea/workflows/docker-build.yml:
  - Runs before build-and-push (build-and-push needs: test)
  - Builds --target tester with registry build cache
  - Gate: build-and-push only runs when all tests pass

- Add run_tests.sh convenience script for local use:
  - Accepts optional test name filter as first argument
  - Respects CUDA_VERSION / UBUNTU_VERSION env overrides

All 30 unit tests pass:
  error::tests     — 7 tests (OOM detection, ModelNotReady HTTP shape)
  models::tests    — 17 tests (state machine, serialization, retry-after)
  worker::tests    — 6 tests (chunk ranges, silence snap/trim)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

.gitea/workflows/docker-build.yml

@@ -18,7 +18,30 @@ env:
   UBUNTU_VERSION: ${{ vars.UBUNTU_VERSION || '22.04' }}
 
 jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Run unit tests
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          target: tester
+          push: false
+          build-args: |
+            CUDA_VERSION=${{ env.CUDA_VERSION }}
+            UBUNTU_VERSION=${{ env.UBUNTU_VERSION }}
+          cache-from: type=registry,ref=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:buildcache
+
   build-and-push:
+    needs: test
     runs-on: ubuntu-latest
 
     steps:

Dockerfile

@@ -82,6 +82,27 @@ RUN --mount=type=cache,target=/usr/local/cargo/registry \
     && cp target/release/whisper-server /usr/local/bin/whisper-server
 
 
+# ╔══════════════════════════════════════════════════════════╗
+# ║  STAGE 1b — tester                                       ║
+# ║  Runs unit tests against the release build artifacts     ║
+# ║  Uses CUDA stubs so tests run without a physical GPU     ║
+# ║                                                          ║
+# ║  Usage:                                                  ║
+# ║    docker build --target tester .                        ║
+# ╚══════════════════════════════════════════════════════════╝
+FROM builder AS tester
+
+# libcuda.so.1 stub — satisfies the dynamic linker without a real driver
+RUN ln -sf /usr/local/cuda/lib64/stubs/libcuda.so \
+           /usr/local/cuda/lib64/stubs/libcuda.so.1
+
+# Reuse the same cache mounts so no recompilation is needed
+RUN --mount=type=cache,target=/usr/local/cargo/registry \
+    --mount=type=cache,target=/build/target \
+    LD_LIBRARY_PATH=/usr/local/cuda/lib64/stubs \
+    cargo test --release
+
+
 # ╔══════════════════════════════════════════════════════════╗
 # ║  STAGE 2 — runtime                                       ║
 # ║  Minimal CUDA runtime image — no build tools             ║

run_tests.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# run_tests.sh — Run the unit test suite inside Docker (no GPU required)
+#
+# Uses the `tester` Docker stage which:
+#   1. Builds the release binary (or reuses cached build)
+#   2. Symlinks the CUDA stubs so libcuda.so.1 is satisfied without a driver
+#   3. Runs `cargo test --release`
+#
+# Usage:
+#   ./run_tests.sh                  # run all unit tests
+#   ./run_tests.sh models           # run only tests matching "models"
+#   CUDA_VERSION=12.1.0 ./run_tests.sh
+
+set -euo pipefail
+
+CUDA_VERSION=${CUDA_VERSION:-12.4.1}
+UBUNTU_VERSION=${UBUNTU_VERSION:-22.04}
+TEST_FILTER=${1:-}
+
+echo "==> Building tester stage (CUDA ${CUDA_VERSION} / Ubuntu ${UBUNTU_VERSION})..."
+docker build \
+  --target tester \
+  --build-arg CUDA_VERSION="${CUDA_VERSION}" \
+  --build-arg UBUNTU_VERSION="${UBUNTU_VERSION}" \
+  --tag whisper-tester:local \
+  .
+
+if [[ -n "${TEST_FILTER}" ]]; then
+  echo "==> Running tests matching '${TEST_FILTER}'..."
+  docker run --rm \
+    -e LD_LIBRARY_PATH=/usr/local/cuda/lib64/stubs \
+    whisper-tester:local \
+    sh -c "cd /build && ln -sf /usr/local/cuda/lib64/stubs/libcuda.so /usr/local/cuda/lib64/stubs/libcuda.so.1 && LD_LIBRARY_PATH=/usr/local/cuda/lib64/stubs cargo test --release '${TEST_FILTER}'"
+else
+  echo "==> All tests ran during docker build (tester stage)."
+  echo "    Build succeeded — all tests passed."
+fi