pytest 마킹으로 테스트에 메타데이터 달기

테스트가 많아지면 "이건 느려서 자주 돌리기 싫다", "이건 특정 환경에서만 돌고 싶다" 같은 분류가 필요해져요. pytest의 마커(marker) 는 테스트 함수에 메타데이터를 붙이는 기능이라, 이런 태깅과 선택적 실행을 손쉽게 만들어 줘요. 여기서는 내장 마커를 쓰는 법, 커스텀 마커를 등록하는 법, 그리고 잘못 쓴 마커 이름이 조용히 무시되지 않게 검증하는 법을 살펴볼게요.

출처: pytest 공식 문서 - How to mark test functions with attributes

pytest.mark로 테스트에 속성 붙이기

pytest.mark 헬퍼를 쓰면 테스트 함수에 메타데이터를 쉽게 달 수 있어요. 내장 마커의 전체 목록은 API 레퍼런스에서 확인할 수 있고, CLI로 pytest --markers를 실행하면 내장·커스텀 마커를 모두 나열해 줘요.

대표적인 내장 마커들은 이렇습니다.

usefixtures — 테스트 함수나 클래스에 픽스처 적용
filterwarnings — 테스트 함수의 특정 경고 필터링
skip — 테스트를 항상 스킵
skipif — 특정 조건을 만족하면 스킵
xfail — 특정 조건에서 "기대된 실패(expected failure)"를 띄움
parametrize — 같은 테스트 함수를 여러 번 호출

커스텀 마커를 만들고 클래스나 모듈 단위로 적용하는 것도 쉬워요. 이 마커들은 플러그인이 사용할 수도 있고, -m 옵션으로 커맨드라인에서 테스트를 선택하는 데도 자주 쓰여요.

한 가지 짚고 넘어갈 점은, 마커는 테스트에만 적용할 수 있고 픽스처에는 아무 효과가 없다는 거예요.

커스텀 마커 등록하기

커스텀 마커를 설정 파일에 등록하면 pytest의 도움말 등에 반영되고 경고도 나지 않아요. toml 설정과 ini 설정 모두 지원해요.

[pytest]
markers = [
    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
    "serial",
]

[pytest]
markers =
    slow: marks tests as slow (deselect with '-m "not slow"')
    serial

마커 이름 뒤의 : 이후는 선택 설명이에요. 특히 서드파티 플러그인은 자신의 마커를 항상 등록하는 게 권장돼요.

프로그래밍 방식으로도 pytest_configure 훅에서 config.addinivalue_line()으로 마커를 등록할 수 있어요.

def pytest_configure(config):
    config.addinivalue_line(
        "markers", "env(name): mark test to run only on named environment"
    )

등록되지 않은 마커는 경고·오류로 잡기

@pytest.mark.이름 형태로 붙인 마커가 등록되어 있지 않으면, pytest는 오타로 인한 조용한 실패를 막기 위해 항상 경고를 냅니다. 이 경고를 없애려면 앞서 본 대로 설정 파일이나 pytest_configure 훅으로 마커를 등록하면 돼요.

더 엄격하게 검증하고 싶다면 strict_markers 설정을 켜면, 등록되지 않은 마커가 오류가 돼요. toml 설정에서는 addopts로 --strict-markers를 넣는 방식으로 켭니다.

[pytest]
addopts = ["--strict-markers"]
markers = [
    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
    "serial",
]

[pytest]
strict_markers = true
markers =
    slow: marks tests as slow (deselect with '-m "not slow"')
    serial

이렇게 해 두면 마커 이름을 잘못 적었을 때 테스트가 조용히 넘어가지 않고 바로 오류로 드러나서, 정확한 테스트 선택을 지킬 수 있어요.

pytest 마킹으로 테스트에 메타데이터 달기