살아 있음과 준비됨을
서로 다른 질문으로 고정한다

전체 코드

from fastapi.testclient import TestClient

from app.core.config import Settings
from app.api.dependencies import get_inference_engine
from app.engines.base import InferenceError, ModelInfo
from app.main import create_app


def make_test_client() -> TestClient:
    settings = Settings(
        service_name="local-moe-backend-test",
        service_version="test-version",
        environment="test",
        log_level="WARNING",
    )
    return TestClient(create_app(settings))


def test_healthcheck_returns_stable_liveness_contract() -> None:
    with make_test_client() as client:
        response = client.get("/healthz")

    assert response.status_code == 200
    assert response.headers["cache-control"] == "no-store"
    assert response.json() == {
        "status": "ok",
        "service": "local-moe-backend-test",
        "version": "test-version",
        "environment": "test",
    }


def test_unknown_route_is_not_disguised_as_healthy() -> None:
    with make_test_client() as client:
        response = client.get("/")

    assert response.status_code == 404


def test_openapi_contains_healthcheck_contract() -> None:
    with make_test_client() as client:
        document = client.get("/openapi.json").json()

    assert "/healthz" in document["paths"]
    schema = document["components"]["schemas"]["HealthResponse"]
    assert set(schema["required"]) == {"status", "service", "version", "environment"}


class ReadyEngine:
    async def check_ready(self) -> ModelInfo:
        return ModelInfo(id="gemma-4-26b-a4b-it")


class UnavailableEngine:
    async def check_ready(self) -> ModelInfo:
        raise InferenceError("unavailable")


def test_readiness_returns_200_when_inference_is_reachable() -> None:
    application = create_app(Settings(environment="test", log_level="WARNING"))
    application.dependency_overrides[get_inference_engine] = lambda: ReadyEngine()

    with TestClient(application) as client:
        response = client.get("/readyz")

    assert response.status_code == 200
    assert response.headers["cache-control"] == "no-store"
    assert response.json() == {
        "status": "ready", "dependency": "inference", "error_code": None,
    }


def test_readiness_returns_503_but_liveness_stays_200() -> None:
    application = create_app(Settings(environment="test", log_level="WARNING"))
    application.dependency_overrides[get_inference_engine] = lambda: UnavailableEngine()

    with TestClient(application) as client:
        readiness_response = client.get("/readyz")
        liveness_response = client.get("/healthz")

    assert readiness_response.status_code == 503
    assert readiness_response.json() == {
        "status": "not_ready",
        "dependency": "inference",
        "error_code": "unavailable",
    }
    assert liveness_response.status_code == 200

import 해설

make_test_client — 왜 설정을 직접 만드는가

def make_test_client() -> TestClient:
    settings = Settings(
        service_name="local-moe-backend-test",
        service_version="test-version",
        environment="test",
        log_level="WARNING",
    )
    return TestClient(create_app(settings))

create_app(settings)에 설정을 인수로 밀어 넣는다. 이것이 application factory를 쓰는 이유다. 환경변수나 .env 파일을 건드리지 않으므로, 개발자의 로컬 환경이 어떻든 테스트 결과가 같다.

값을 일부러 눈에 띄게 지었다. "test-version"이 응답에 그대로 보이면 설정이 실제로 응답까지 흘러갔다는 증거가 된다. "0.1.0"처럼 실제 기본값과 같은 값을 쓰면 주입이 동작하지 않아도 테스트가 통과해 버린다.

테스트 1~3 — liveness 계약

가짜 engine 두 개 — 추론 서버 없이 시험하기

class ReadyEngine:
    async def check_ready(self) -> ModelInfo:
        return ModelInfo(id="gemma-4-26b-a4b-it")


class UnavailableEngine:
    async def check_ready(self) -> ModelInfo:
        raise InferenceError("unavailable")

InferenceEngine을 상속하지 않는다. engines/base.py의 계약이 Protocol이기 때문이다. Protocol은 “이 method를 가지고 있으면 그것으로 충분하다”는 구조적 판정이라, 상속 선언 없이도 같은 자리에 쓸 수 있다.

두 class는 check_ready 하나만 구현한다. generate는 없다. /readyz가 그것만 호출하기 때문이다. 테스트용 대역은 실제로 쓰이는 만큼만 만들면 된다.

테스트 4~5 — readiness와 의존성 교체

application = create_app(Settings(environment="test", log_level="WARNING"))
application.dependency_overrides[get_inference_engine] = lambda: ReadyEngine()

with TestClient(application) as client:
    response = client.get("/readyz")

자주 발생하는 오류

설계 선택과 대안

이전 단계와 다음 파일

여기서 검증한 응답 형태의 정의는 schemas/system.py, 구현은 routes/system.py에 있다. 설정이 잘못된 값을 거부하는지 보는 테스트는 test_config.py, 실제 TCP를 쓰는 회귀 테스트는 test_readiness_isolation.py로 이어진다.