본문으로 건너뛰기

Testing with Fixtures ​

좋은 테스트는 assert 문 몇 줄이 아니라 fixture 경계 설계에서 갈린다. DB, FastAPI app, dependency override, TestClient, 외부 API stub을 어떻게 열고 닫는지 흐려지면 테스트는 금방 느리고 flaky하며 서로 간섭하기 시작한다.

빠른 요약: pytest에서는 `yield fixture`를 기본으로 삼고, teardown은 fixture 바로 아래에 둔다. app, DB, client, override를 분리해 fixture graph를 명확히 만들고, 테스트는 그 조합을 소비만 하게 만드는 편이 가장 오래 간다.

fixture graph를 먼저 본다 ​

테스트에서도 자원 수명주기는 의존성 그래프로 읽히는 편이 좋다. 바깥 자원이 먼저 열리고, 안쪽 fixture가 그것을 소비한 뒤 역순으로 teardown된다.

기본 규칙 ​

  • fixture는 자원을 만든다.
  • 테스트 함수는 자원을 조합해 동작을 검증한다.
  • teardown은 yield 바로 아래에 둔다.
  • global mutable state를 테스트끼리 공유하지 않는다.

가장 읽기 좋은 패턴 ​

py
from collections.abc import Generator

import pytest
from fastapi.testclient import TestClient


@pytest.fixture
def app() -> Generator[FastAPI, None, None]:
    application = create_app()
    application.dependency_overrides[get_settings] = lambda: TestSettings()
    try:
        yield application
    finally:
        application.dependency_overrides.clear()


@pytest.fixture
def client(app: FastAPI) -> Generator[TestClient, None, None]:
    with TestClient(app) as test_client:
        yield test_client

중요한 점은 teardown이 fixture 정의 바로 옆에 있다는 것이다. `dependency_overrides.clear()` 같은 정리 코드를 test body 밖으로 빼두면 누가 자원을 닫는지 읽기가 쉬워진다.

DB fixture는 격리 전략을 명시해야 한다 ​

작은 서비스 / 시작 단계 ​

  • function-scoped SQLite
  • 테스트마다 schema 생성/삭제
  • 느리더라도 단순해서 읽기 좋다

더 큰 서비스 ​

  • connection + transaction + rollback
  • 필요하면 nested SAVEPOINT
  • 테스트 속도와 격리를 동시에 노릴 수 있다

testcontainers를 쓸 때는 "container 수명"과 "테스트 격리"를 분리한다 ​

testcontainers를 쓰기 시작하면 흔히 두 가지를 한 fixture에 섞는다.

  • PostgreSQL container를 띄우는 일
  • 각 테스트가 서로 안 섞이게 DB 상태를 초기화하는 일

이 둘은 성격이 다르다.

  • container lifecycle은 보통 바깥 fixture다.
  • schema 준비, seed, rollback, truncate는 안쪽 fixture다.

권장 기본형 ​

  • container는 session scope 또는 module scope
  • engine / session factory는 그 안쪽 fixture
  • 테스트 격리는 function-scoped transaction rollback 또는 truncate/seed

컨테이너를 매 테스트마다 띄우면 격리는 단순하지만 대체로 너무 느리다. 반대로 container를 길게 공유하면서 DB reset 전략이 없으면 flaky test가 된다.

읽기 좋은 예 ​

py
from collections.abc import Generator

import pytest
from sqlalchemy import create_engine
from sqlalchemy.engine import Engine
from sqlalchemy.orm import Session, sessionmaker
from testcontainers.postgres import PostgresContainer


@pytest.fixture(scope="session")
def postgres_container() -> Generator[PostgresContainer, None, None]:
    with PostgresContainer("postgres:17") as container:
        yield container


@pytest.fixture(scope="session")
def engine(postgres_container: PostgresContainer) -> Generator[Engine, None, None]:
    test_engine = create_engine(postgres_container.get_connection_url())
    Base.metadata.create_all(test_engine)
    try:
        yield test_engine
    finally:
        Base.metadata.drop_all(test_engine)
        test_engine.dispose()


@pytest.fixture
def db_session(engine: Engine) -> Generator[Session, None, None]:
    connection = engine.connect()
    transaction = connection.begin()
    testing_session = sessionmaker(
        bind=connection,
        class_=Session,
        autoflush=False,
        expire_on_commit=False,
    )()

    try:
        yield testing_session
    finally:
        testing_session.close()
        transaction.rollback()
        connection.close()

포인트는 container가 가장 바깥 수명주기를 소유하고, function-scoped `db_session`이 각 테스트의 격리를 책임진다는 점이다. startup cost와 isolation concern을 한 fixture에 섞지 않는다.

FastAPI까지 붙이면 보통 이렇게 간다 ​

  1. postgres_container가 실제 Postgres를 띄운다.
  2. engine fixture가 schema 또는 migration을 준비한다.
  3. db_session fixture가 테스트 단위 rollback 경계를 잡는다.
  4. app fixture가 dependency_overrides로 그 세션 또는 session factory를 주입한다.
  5. client fixture가 TestClient를 열고 닫는다.

언제 migration을 실제로 태우나 ​

  • repository/ORM query shape만 검증하면 metadata.create_all()로도 충분할 수 있다.
  • Alembic revision, index, constraint, DB-specific DDL까지 확인하고 싶다면 container 위에서 실제 migration을 올리는 편이 맞다.

즉, "실제 Postgres를 쓴다"와 "실제 migration 경로를 검증한다"도 별도 결정이다.

실무 팁 ​

  • container는 너무 안쪽 scope로 두지 않는다.
  • 대신 테스트 격리는 transaction rollback, truncate, seed fixture에서 만든다.
  • app override cleanup은 여전히 yield 아래에서 정리한다.
  • startup이 무거운 container는 테스트 세트 전체에서 공유하고, 함수 단위 자원은 그 안에서 짧게 만든다.
  • 비동기 스택이라면 async engine/session fixture를 따로 두고, container fixture만 공용으로 두는 편이 읽기 쉽다.

yield fixture가 기본인 이유 ​

pytest 공식 문서도 teardown/finalization 기본 패턴으로 yield fixture를 먼저 권장한다. addfinalizer()는 teardown 대상을 동적으로 등록해야 할 때 유용하지만, 일상적인 서비스 테스트에서는 yield가 더 읽기 쉽고 안전하다.

ABC + Fake UoW 단위 테스트 패턴은 ABC + Fake UoW Testing에서 별도로 더 깊게 다룬다.

하지 않는 편이 좋은 것 ​

  • giant autouse fixture 하나에 모든 setup을 몰아넣는다.
  • 테스트 함수 안에서 dependency_overrides를 직접 만지고 정리하지 않는다.
  • session이나 client를 모듈 전역으로 재사용한다.
  • fixture가 무엇을 cleanup하는지 숨긴다.
  • 외부 API stub과 DB seed를 하나의 fixture에 섞는다.
  • container startup과 test-level DB reset을 하나의 giant fixture에 욱여넣는다.

실전 테스트 레이아웃 예 ​

text
tests/
  conftest.py
  integration/
    test_users_api.py
  unit/
    test_user_service.py
  • conftest.py: 공용 fixture
  • integration/: HTTP contract, DB, serialization
  • unit/: 순수 service/domain logic

이 저장소의 예제 ​

이 저장소에는 tests/test_fastapi_fixtures_and_teardown.py 파일을 추가했다. 다음 패턴을 보여준다.

  • engine fixture 생성과 teardown
  • seed fixture
  • dependency_overrides 설치와 cleanup
  • TestClient context manager teardown

실전 체크리스트 ​

fixture가 자원 소유권을 가진다

누가 열고 누가 닫는지 fixture만 봐도 읽혀야 한다.

override cleanup이 있다

FastAPI dependency override는 반드시 fixture teardown에서 정리한다.

DB 격리 전략이 명시적이다

schema recreate인지 rollback인지 팀 기준이 있어야 flaky test가 줄어든다.

container scope와 reset 전략이 분리돼 있다

`testcontainers`를 쓴다면 container lifetime과 test-level isolation을 별도 fixture로 나눈다.

autouse는 최소화한다

숨은 fixture는 테스트 읽기를 어렵게 하므로 공통 인프라에만 제한적으로 쓴다.

공식 자료 ​

VitePress로 빌드한 Python 3.14 핸드북