Python pytest 완전 가이드｜fixture·parametrize·conftest.py를 실무 수준으로 해설

pytest는 Python에서 가장 널리 사용되는 테스트 프레임워크로, 심플한 문법과 강력한 fixture 기능으로 QA 엔지니어의 테스트 자동화를 극적으로 효율화합니다.

테스트 자동화 학습 로드맵에서 pytest는 Python과 함께 가장 먼저 습득해야 할 프레임워크입니다. Playwright·Selenium 등의 자동화 도구와 조합하여 사용하는 경우가 대부분이며, 테스트 실행·관리·리포트 출력까지 한 손에 담당합니다. 이 글에서는 설치부터 실무에서 사용할 수 있는 수준까지 단계별로 상세히 해설합니다.

pytest란？unittest와의 차이

pytest는 Python용 오픈소스 테스트 프레임워크입니다. 표준 라이브러리의 unittest에 비해 코드 작성량이 적고, 에러 메시지가 읽기 쉬우며, 풍부한 플러그인 생태계를 갖추고 있습니다.

① 설치·환경 구축

먼저 pytest를 설치합니다. Python 3.8 이상이 필요합니다.

# pytest 설치
pip install pytest

# 버전 확인
pytest --version

# 자주 사용하는 플러그인을 한 번에 설치
pip install pytest pytest-html pytest-xdist

프로젝트 구성 예시：

my_project/
├── src/
│   └── calculator.py       # 테스트 대상 코드
├── tests/
│   ├── conftest.py         # 공통 픽스처 보관소
│   ├── test_calculator.py  # 테스트 파일
│   └── test_api.py
└── pytest.ini              # pytest 설정 파일

② 기본 테스트 작성법

먼저 테스트 대상이 될 간단한 함수를 준비합니다.

# src/calculator.py

def add(a, b):
    return a + b

def subtract(a, b):
    return a - b

def divide(a, b):
    if b == 0:
        raise ValueError("0으로 나눌 수 없습니다")
    return a / b

다음으로 대응하는 테스트를 작성합니다：

# tests/test_calculator.py
import pytest
from src.calculator import add, subtract, divide

# ✅ 기본 테스트 함수（함수명은 test_로 시작）
def test_add_정상():
    result = add(3, 5)
    assert result == 8

def test_subtract_정상():
    result = subtract(10, 4)
    assert result == 6

def test_divide_정상():
    result = divide(10, 2)
    assert result == 5.0

# ✅ 예외가 발생하는 것을 테스트하기
def test_divide_제로_나눗셈():
    with pytest.raises(ValueError) as exc_info:
        divide(10, 0)
    assert "0으로 나눌 수 없습니다" in str(exc_info.value)

테스트 실행

# 모든 테스트 실행
pytest

# 특정 파일만 실행
pytest tests/test_calculator.py

# 상세 표시（-v）
pytest -v

# 테스트명으로 필터링（-k）
pytest -k "divide"

# 첫 번째 실패에서 중지（-x）
pytest -x

실행 결과 샘플

========================= test session starts ==========================
platform win32 -- Python 3.11.0, pytest-7.4.0
collected 4 items

tests/test_calculator.py::test_add_정상        PASSED  [ 25%]
tests/test_calculator.py::test_subtract_정상   PASSED  [ 50%]
tests/test_calculator.py::test_divide_정상     PASSED  [ 75%]
tests/test_calculator.py::test_divide_제로_나눗셈  PASSED  [100%]

========================== 4 passed in 0.12s ===========================

③ fixture（픽스처）사용법

fixture는 테스트의 전처리·후처리·공유 데이터를 관리하는 pytest의 핵심 기능입니다. 매번 동일한 설정 코드를 작성할 필요가 없어지며, 테스트 코드가 깔끔해집니다.

# tests/test_user.py
import pytest

# --- fixture 정의 ---
@pytest.fixture
def sample_user():
    """테스트용 사용자 데이터를 반환하는 fixture"""
    return {
        "id": 1,
        "name": "테스트 사용자",
        "email": "test@example.com",
        "role": "admin"
    }

@pytest.fixture
def empty_list():
    return []

# --- fixture를 사용한 테스트 ---
def test_user_name(sample_user):
    assert sample_user["name"] == "테스트 사용자"

def test_user_role(sample_user):
    assert sample_user["role"] == "admin"

def test_empty_list_is_empty(empty_list):
    assert len(empty_list) == 0

setup / teardown（전처리·후처리）

yield를 사용하면 테스트 전후 처리를 하나의 fixture에 통합할 수 있습니다：

@pytest.fixture
def db_connection():
    # --- 전처리（테스트 시작 전） ---
    print("\n[SETUP] DB에 연결 중...")
    connection = {"status": "connected", "db": "test_db"}

    yield connection  # ← 여기서 테스트에 전달

    # --- 후처리（테스트 종료 후） ---
    print("\n[TEARDOWN] DB 연결을 닫았습니다")
    connection["status"] = "disconnected"

def test_db_is_connected(db_connection):
    assert db_connection["status"] == "connected"

fixture의 스코프（scope）

# 세션 전체에서 한 번만 브라우저를 기동하는 예（Playwright 연동）
@pytest.fixture(scope="session")
def browser():
    from playwright.sync_api import sync_playwright
    with sync_playwright() as p:
        browser = p.chromium.launch()
        yield browser
        browser.close()

④ parametrize（파라미터화 테스트）

@pytest.mark.parametrize를 사용하면 동일한 테스트 로직을 복수의 패턴으로 실행할 수 있습니다. 경계값 테스트나 정상계·비정상계 망라에 매우 유효합니다.

import pytest
from src.calculator import add, divide

# ✅ 기본 파라미터화
@pytest.mark.parametrize("a, b, expected", [
    (1, 2, 3),      # 양의 정수
    (-1, -2, -3),   # 음의 정수
    (0, 5, 5),      # 0 포함
    (100, 200, 300) # 큰 수
])
def test_add_파라미터화(a, b, expected):
    assert add(a, b) == expected

# ✅ 복수의 비정상계를 한 번에 테스트
@pytest.mark.parametrize("a, b", [
    (10, 0),
    (0, 0),
    (-5, 0),
])
def test_divide_제로_나눗셈_파라미터화(a, b):
    with pytest.raises(ValueError):
        divide(a, b)

실행하면 파라미터마다 독립된 테스트로 표시됩니다：

tests/test_calculator.py::test_add_파라미터화[1-2-3]        PASSED
tests/test_calculator.py::test_add_파라미터화[-1--2--3]     PASSED
tests/test_calculator.py::test_add_파라미터화[0-5-5]        PASSED
tests/test_calculator.py::test_add_파라미터화[100-200-300]  PASSED

⑤ conftest.py 활용

conftest.py는 복수의 테스트 파일에서 fixture를 공유하기 위한 특별한 파일입니다. 여기에 작성한 fixture는 import 없이 모든 테스트에서 참조할 수 있습니다.

# tests/conftest.py

import pytest

@pytest.fixture(scope="session")
def base_url():
    """모든 테스트에서 공유하는 베이스 URL"""
    # 실제 코드에서는 http:// 를 붙여주세요（예："http://localhost:8080"）
    return "localhost:8080"

@pytest.fixture
def test_user_credentials():
    """테스트용 로그인 정보"""
    return {
        "username": "standard_user",
        "password": "secret_sauce"
    }

@pytest.fixture(scope="session")
def api_headers():
    """API 테스트용 공통 헤더"""
    return {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }

# tests/test_login.py
# ← conftest.py의 fixture는 import 없이 그대로 사용 가능！

def test_login_with_valid_credentials(test_user_credentials, base_url):
    username = test_user_credentials["username"]
    password = test_user_credentials["password"]
    # ... 테스트 로직

⑥ 마크（mark）활용

pytest의 마크 기능을 사용하면 테스트 스킵이나 조건부 실행을 간단하게 할 수 있습니다.

import pytest
import sys

# ✅ 테스트 스킵
@pytest.mark.skip(reason="미구현으로 인해 임시 스킵")
def test_미구현_기능():
    assert some_future_function() == True

# ✅ 조건부 스킵（Windows에서만 스킵하는 등 OS 의존 테스트에 유효）
@pytest.mark.skipif(sys.platform == "win32", reason="Windows 미지원")
def test_linux_only():
    assert True

# ✅ 기존 버그（실패가 예상되는 테스트）
@pytest.mark.xfail(reason="버그 수정 대기 중: issue #123")
def test_known_bug():
    assert 1 + 1 == 3  # 의도적으로 실패

# ✅ 커스텀 마크（그룹화하여 선택 실행 가능）
@pytest.mark.smoke
def test_로그인_스모크테스트():
    assert True

@pytest.mark.regression
def test_결제_플로우_회귀테스트():
    assert True

# 스모크 테스트만 실행
pytest -m smoke

# 회귀 테스트만 실행
pytest -m regression

# 커스텀 마크는 pytest.ini에 등록 필요
# pytest.ini:
# [pytest]
# markers =
#     smoke: 스모크 테스트
#     regression: 회귀 테스트

⑦ pytest.ini 설정

프로젝트 루트에 pytest.ini를 두면 pytest 전체 동작을 커스터마이즈할 수 있습니다：

# pytest.ini
[pytest]
# 테스트 파일 검색 경로
testpaths = tests

# 기본 옵션（매번 -v --tb=short --html=... 를 붙이는 것과 동일）
addopts = -v --tb=short --html=reports/report.html --self-contained-html

# 커스텀 마크 등록（경고를 없애기 위해 필요）
markers =
    smoke: 스모크 테스트（최소한의 동작 확인）
    regression: 회귀 테스트
    slow: 실행 시간이 긴 테스트

# 로그 출력 설정
log_cli = true
log_cli_level = INFO

⑧ HTML 리포트 출력

pytest-html 플러그인을 사용하면 테스트 결과를 HTML 파일로 출력할 수 있습니다. CI/CD에서의 결과 공유나 QA 리포트로서 매우 편리합니다.

# 설치
pip install pytest-html

# HTML 리포트 출력
pytest --html=reports/report.html --self-contained-html

# pytest.ini에 추가하면 매번 자동 생성
# addopts = -v --html=reports/report.html --self-contained-html

생성된 리포트는 reports/report.html을 브라우저에서 열면 확인할 수 있습니다. 테스트명·합격 여부·실행 시간·에러 상세가 일람 표시됩니다.

⑨ Playwright × pytest 조합 예시

pytest는 Playwright와 조합함으로써 E2E 테스트를 보다 정리된 형태로 관리할 수 있습니다. pytest-playwright 플러그인을 사용하는 것이 가장 간단합니다.

# 설치
pip install pytest-playwright
playwright install chromium

# tests/test_saucedemo.py
import pytest
from playwright.sync_api import Page

# pytest-playwright가 제공하는 page fixture를 인자로 받기만 하면 OK
# 실제 코드에서는 page.goto()의 인자에 http:// 를 붙여주세요（예：http://localhost:8080/）
def test_로그인_정상(page: Page):
    page.goto("localhost:8080/")
    page.fill("#user-name", "standard_user")
    page.fill("#password", "secret_sauce")
    page.click("#login-button")
    assert page.url.endswith("/inventory.html")

def test_로그인_비밀번호_오류(page: Page):
    page.goto("localhost:8080/")
    page.fill("#user-name", "standard_user")
    page.fill("#password", "wrong_password")
    page.click("#login-button")
    error_msg = page.locator(".error-message-container").text_content()
    assert "Epic sadface" in error_msg

# 헤드리스 모드로 실행（기본값）
pytest tests/test_saucedemo.py -v

# 브라우저를 표시하여 실행（디버그 시 편리）
pytest tests/test_saucedemo.py --headed

# 브라우저 지정
pytest tests/test_saucedemo.py --browser firefox

⑩ 자주 사용하는 커맨드 정리

FAQ

⚠️ pytest에서 자주 발생하는 함정 7선

실무에서 pytest를 사용하기 시작할 때 많은 사람이 걸려드는 포인트를 정리했습니다. 미리 파악해 두면 불필요한 디버깅 시간을 대폭 줄일 수 있습니다.

project/
├── src/
└── tests/
    ├── conftest.py   ← 여기에 둔다（tests/ 바로 아래）
    └── test_api.py

# ❌ NG：tests 폴더 안에서 실행
cd tests
pytest

# ✅ 권장：프로젝트 루트에서 실행
cd my_project
pytest

📋 이 글의 정리

pytest를 마스터하면 Playwright나 Selenium과의 조합으로 본격적인 테스트 자동화 기반을 구축할 수 있습니다. 먼저 심플한 함수 테스트부터 시작하여 fixture·parametrize·conftest.py를 단계적으로 익혀나가세요.