Playwright + pytest 테스트 구성 베스트 프랙티스｜폴더 설계·fixture·mark 운용을 실무 수준으로 해설

Playwright와 pytest를 단순히 연결하는 것에 그치지 않고, 폴더 구성·fixture 설계·mark 운용을 처음부터 올바르게 설계하면 장기적으로 유지보수할 수 있는 테스트 자동화 기반을 구축할 수 있습니다.

Playwright와 Python을 조합하면 간단하게 E2E 테스트를 작성할 수 있습니다. 하지만 테스트가 늘어나면 다음과 같은 문제에 부딪히는 경우가 많습니다.

• fixture가 늘어나서 어디에 작성해야 할지 모르게 된다
• 셀렉터가 테스트 코드 곳곳에 흩어진다
• CI/CD에서 어떤 테스트를 언제 실행할지 관리할 수 없게 된다

이 글에서는 이러한 문제를 방지하기 위한 Playwright × pytest 베스트 프랙티스 구성을 폴더 설계부터 fixture·conftest.py·pytest.ini까지 한 번에 해설합니다.

① 권장 폴더 구성

먼저 전체 폴더 구성을 확인합니다. 소규모 프로젝트용 심플 버전과 중~대규모용 확장 버전의 2가지 패턴을 소개합니다.

심플 버전（소규모·학습용）

my_project/
├── pages/                    # Page Object Model（페이지 조작 클래스）
│   ├── __init__.py
│   ├── login_page.py
│   └── inventory_page.py
├── tests/                    # 테스트 파일
│   ├── conftest.py           # 공통 fixture
│   ├── test_login.py
│   └── test_inventory.py
├── pytest.ini                # pytest 설정
└── requirements.txt

확장 버전（중~대규모·팀 운용용）

my_project/
├── pages/                    # Page Object Model
│   ├── __init__.py
│   ├── base_page.py          # 전체 페이지 공통 기저 클래스
│   ├── login_page.py
│   └── inventory_page.py
├── tests/                    # 테스트 파일
│   ├── conftest.py           # 세션·브라우저 계 fixture
│   ├── e2e/                  # E2E 테스트（플로우 전체）
│   │   ├── conftest.py       # E2E 전용 fixture
│   │   └── test_purchase_flow.py
│   ├── smoke/                # 스모크 테스트（최소한의 동작 확인）
│   │   └── test_login_smoke.py
│   └── regression/           # 회귀 테스트
│       └── test_cart.py
├── utils/                    # 헬퍼 함수·상수
│   ├── __init__.py
│   └── constants.py          # URL·테스트 데이터 상수
├── reports/                  # 테스트 리포트 출력처
├── pytest.ini
└── requirements.txt

② pytest.ini 완성형

프로젝트 루트에 두는 pytest.ini입니다. 이것만 있으면 팀 전원이 같은 설정으로 테스트를 실행할 수 있습니다.

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

# 기본 옵션
addopts =
    -v
    --tb=short
    --html=reports/report.html
    --self-contained-html

# 커스텀 마크 등록（미등록 시 경고가 출력됨）
markers =
    smoke: 스모크 테스트（최소한의 동작 확인·매번 실행）
    regression: 회귀 테스트（릴리스 전에 실행）
    e2e: E2E 테스트（플로우 전체·시간이 걸림）
    slow: 실행 시간이 긴 테스트

# 로그 설정
log_cli = true
log_cli_level = INFO
log_format = %(asctime)s %(levelname)s %(message)s
log_date_format = %Y-%m-%d %H:%M:%S

③ conftest.py 계층 설계

conftest.py는 「어떤 스코프의 fixture인가」에 따라 배치 장소를 나누는 것이 베스트 프랙티스입니다.

tests/conftest.py（프로젝트 전체에서 공유）

# tests/conftest.py
import pytest
from playwright.sync_api import sync_playwright

# ============================================================
# 브라우저·페이지 계 fixture（세션 스코프）
# ============================================================

@pytest.fixture(scope="session")
def browser_instance():
    """테스트 전체에서 하나의 브라우저 인스턴스를 공유한다"""
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=True)
        yield browser
        browser.close()

@pytest.fixture(scope="function")
def page(browser_instance):
    """테스트마다 새로운 페이지（탭）를 생성한다"""
    context = browser_instance.new_context(
        viewport={"width": 1280, "height": 720}
    )
    page = context.new_page()
    yield page
    context.close()  # 테스트 종료 후 컨텍스트를 닫는다

# ============================================================
# 인증 계 fixture
# ============================================================

@pytest.fixture(scope="session")
def base_url():
    """테스트 대상의 베이스 URL을 반환한다"""
    # 실제 코드에서는 https:// 를 붙여주세요（예："https://www.saucedemo.com"）
    return "www.saucedemo.com"

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

@pytest.fixture
def locked_out_credentials():
    """잠긴 사용자의 로그인 정보（비정상계 테스트용）"""
    return {
        "username": "locked_out_user",
        "password": "secret_sauce"
    }

# ============================================================
# 로그인 완료 페이지 fixture（자주 사용하므로 공통화）
# ============================================================

@pytest.fixture
def logged_in_page(page, base_url, valid_credentials):
    """로그인 완료 상태에서 page를 반환하는 fixture"""
    page.goto(f"https://{base_url}/")
    page.fill("#user-name", valid_credentials["username"])
    page.fill("#password", valid_credentials["password"])
    page.click("#login-button")
    page.wait_for_url("**/inventory.html")
    return page

tests/e2e/conftest.py（E2E 테스트 전용）

# tests/e2e/conftest.py
import pytest

@pytest.fixture
def cart_items():
    """E2E 테스트용 카트 아이템 테스트 데이터"""
    return ["Sauce Labs Backpack", "Sauce Labs Bike Light"]

@pytest.fixture
def shipping_info():
    """E2E 테스트용 배송 정보"""
    return {
        "first_name": "테스트",
        "last_name": "사용자",
        "postal_code": "06000"
    }

④ Page Object Model 구현

pytest와 조합하는 Page Object Model의 구현 예시입니다. 기저 클래스에 공통 처리를 모으는 것이 포인트입니다.

pages/base_page.py（기저 클래스）

# pages/base_page.py
from playwright.sync_api import Page

class BasePage:
    """전체 페이지 공통 조작을 모은 기저 클래스"""

    def __init__(self, page: Page):
        self.page = page

    def navigate(self, url: str):
        """지정한 URL로 이동한다"""
        self.page.goto(url)

    def get_title(self) -> str:
        """페이지 타이틀을 반환한다"""
        return self.page.title()

    def take_screenshot(self, name: str):
        """스크린샷을 저장한다"""
        self.page.screenshot(path=f"reports/{name}.png")

pages/login_page.py

# pages/login_page.py
from pages.base_page import BasePage

class LoginPage(BasePage):
    """로그인 페이지의 조작 클래스"""

    # 로케이터 상수（셀렉터를 한 곳에서 관리）
    USERNAME_INPUT = "#user-name"
    PASSWORD_INPUT = "#password"
    LOGIN_BUTTON   = "#login-button"
    ERROR_MESSAGE  = ".error-message-container h3"

    def login(self, username: str, password: str):
        """로그인을 실행한다"""
        self.page.fill(self.USERNAME_INPUT, username)
        self.page.fill(self.PASSWORD_INPUT, password)
        self.page.click(self.LOGIN_BUTTON)

    def get_error_message(self) -> str:
        """에러 메시지 텍스트를 반환한다"""
        return self.page.locator(self.ERROR_MESSAGE).text_content()

⑤ 테스트 파일 구현

fixture와 Page Object를 조합한 테스트 파일의 완성형입니다.

tests/smoke/test_login_smoke.py

# tests/smoke/test_login_smoke.py
import pytest
from pages.login_page import LoginPage

@pytest.mark.smoke
def test_로그인_정상(page, base_url, valid_credentials):
    """스모크：정상 로그인이 성공하는 것을 확인"""
    login_page = LoginPage(page)
    login_page.navigate(f"https://{base_url}/")
    login_page.login(
        valid_credentials["username"],
        valid_credentials["password"]
    )
    assert page.url.endswith("/inventory.html"), \
        f"로그인 후 URL이 기대값과 다릅니다: {page.url}"

@pytest.mark.smoke
def test_로그인_비밀번호_오류(page, base_url):
    """스모크：잘못된 비밀번호로 에러 메시지가 표시되는 것을 확인"""
    login_page = LoginPage(page)
    login_page.navigate(f"https://{base_url}/")
    login_page.login("standard_user", "wrong_password")
    error = login_page.get_error_message()
    assert "Epic sadface" in error

@pytest.mark.smoke
def test_로그인_잠긴_사용자(page, base_url, locked_out_credentials):
    """스모크：잠긴 사용자에게 에러가 표시되는 것을 확인"""
    login_page = LoginPage(page)
    login_page.navigate(f"https://{base_url}/")
    login_page.login(
        locked_out_credentials["username"],
        locked_out_credentials["password"]
    )
    error = login_page.get_error_message()
    assert "locked out" in error

tests/e2e/test_purchase_flow.py

# tests/e2e/test_purchase_flow.py
import pytest

@pytest.mark.e2e
@pytest.mark.slow
def test_구매_플로우_정상(logged_in_page, cart_items, shipping_info):
    """E2E：로그인~구매 완료까지의 플로우를 테스트"""
    page = logged_in_page

    # 상품을 카트에 추가
    page.click("[data-test='add-to-cart-sauce-labs-backpack']")
    page.click("[data-test='add-to-cart-sauce-labs-bike-light']")

    # 카트로 이동
    page.click(".shopping_cart_link")
    assert page.url.endswith("/cart.html")

    # 체크아웃 시작
    page.click("[data-test='checkout']")
    page.fill("[data-test='firstName']", shipping_info["first_name"])
    page.fill("[data-test='lastName']", shipping_info["last_name"])
    page.fill("[data-test='postalCode']", shipping_info["postal_code"])
    page.click("[data-test='continue']")

    # 주문 확인·완료
    page.click("[data-test='finish']")
    success_msg = page.locator(".complete-header").text_content()
    assert "Thank you" in success_msg

⑥ mark를 사용한 테스트 실행 제어

mark를 설정해 두면 CI/CD의 페이즈에 맞게 실행할 테스트 세트를 유연하게 전환할 수 있습니다.

# 스모크 테스트만 실행（PR·push마다）
pytest -m smoke

# 스모크·회귀 테스트 실행（main 머지 전）
pytest -m "smoke or regression"

# E2E를 제외한 전체 테스트（빠르게 확인하고 싶을 때）
pytest -m "not e2e"

# slow를 제외한 전체 테스트
pytest -m "not slow"

# 전체 테스트 실행（야간 스케줄）
pytest

⑦ GitHub Actions 연계

mark와 GitHub Actions를 조합하면 페이즈에 따라 실행할 테스트를 자동으로 전환할 수 있습니다.

# .github/workflows/playwright.yml（발췌）

jobs:
  smoke:
    name: 스모크 테스트（PR·push）
    runs-on: ubuntu-latest
    steps:
      # ... 설정 생략 ...
      - name: 스모크 테스트 실행
        run: pytest -m smoke

  regression:
    name: 회귀 테스트（main으로 머지 후）
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      # ... 설정 생략 ...
      - name: 회귀 테스트 실행
        run: pytest -m "smoke or regression"

  nightly:
    name: 야간 전체 테스트
    runs-on: ubuntu-latest
    if: github.event_name == 'schedule'
    steps:
      # ... 설정 생략 ...
      - name: 전체 테스트 실행
        run: pytest

⑧ 실행 결과 샘플

$ pytest -m smoke -v

========================= test session starts ==========================
platform linux -- Python 3.11.0, pytest-7.4.0
collected 8 items / 5 deselected / 3 selected

tests/smoke/test_login_smoke.py::test_로그인_정상          PASSED  [ 33%]
tests/smoke/test_login_smoke.py::test_로그인_비밀번호_오류   PASSED  [ 66%]
tests/smoke/test_login_smoke.py::test_로그인_잠긴_사용자    PASSED  [100%]

========================== 3 passed in 5.21s ===========================

FAQ

⚠️ Playwright + pytest 구성에서 자주 발생하는 함정 7선

올바른 구성을 갖추고 있어도 빠지기 쉬운 함정이 있습니다. 미리 파악해 두면 불필요한 디버깅 시간을 줄일 수 있습니다.

# ❌ NG
cd tests
pytest

# ✅ 권장
cd my_project    # pytest.ini가 있는 곳
pytest

📋 이 글의 정리

처음부터 완벽한 구성을 목표로 할 필요는 없습니다. 먼저 심플 버전의 폴더 구성에서 시작하여 테스트가 늘어난 타이밍에 조금씩 확장 버전에 가까워져 가는 것이 실무적인 접근법입니다.