Playwright + pytest-bdd에서 POM 적용기

들어가며

안녕하세요, 노머스 QA팀의 박온유 입니다.
저희 팀은 Playwright + Python + pytest-bdd 환경에서 E2E 테스트 자동화를 진행하고 있습니다. 테스트 코드가 점점 늘어나면서 매번 UI가 수정될 때마다 테스트가 깨졌고, 로케이터가 여기저기 흩어져 있어서 수정하는 것도 일이었습니다.

이 문제를 해결하기 위해 POM 패턴을 도입했고, 이 글에서는 POM 패턴이 무엇인지, 장단점은 무엇인지, 그리고 저희 팀이 어떻게 전환했는지 공유하고자 합니다.

---

1. Page Object Model(POM)이란?

Page Object Model은 웹 페이지를 객체로 추상화하는 패턴입니다.
각 페이지(또는 컴포넌트)를 클래스로 만들고, 해당 페이지의 요소(로케이터)와 동작(메서드)을 한곳에 모아 관리합니다.

원칙은 다음과 같습니다:

• 단일 책임: 각 Page 클래스는 해당 페이지의 동작만 담당
• 관심사 분리: 로케이터와 상호작용 로직을 Page 클래스에서 관리하여 테스트 코드와 분리
• 재사용성: 동일한 페이지 동작을 여러 테스트에서 재사용

---

2. POM의 장단점

장점

항목	설명
유지보수 용이	UI 변경 시 해당 Page 클래스만 수정하면 됨
코드 재사용	동일한 페이지 동작을 여러 테스트에서 재사용 가능
가독성 향상	테스트 코드에서 로케이터가 사라지고 의도가 명확해짐
디버깅 용이	실패 지점을 Page 단위로 빠르게 파악 가능

단점

항목	설명
초기 구축 비용	클래스 구조를 설계하고 만드는 데 시간이 필요
과도한 추상화 위험	단순한 테스트에도 불필요한 클래스를 만들 수 있음

POM이 적합한 경우

• 테스트 케이스가 계속 늘어나는 프로젝트
• 여러 테스트에서 동일한 페이지/컴포넌트 사용
• UI 변경이 잦은 서비스
• 팀 단위로 테스트 코드 작성

POM이 과한 경우

• 일회성 테스트
• 로케이터가 적은 단순한 테스트
• 프로토타입/PoC 단계

---

3. 기존 방식에서 POM으로 전환

3-1. 기존 방식의 문제점

Fromm/web/store/steps/
├── login.py           # 로그인 관련 스텝
└── ...

@when('Store [로그인] 버튼 클릭')
def click_login_btn(store_page: Page):
    store_page.get_by_text('로그인', exact=True).click()
    
@then('Store [로그인] 버튼 활성화')
def expect_login_btn_enabled(store_page: Page):
    expect(store_page.get_by_text('로그인', exact=True)).to_be_enabled()

문제점:

• 로케이터가 여러 파일에 하드코딩되어 중복 발생
• UI 변경 시 모든 파일을 수정해야 함

3-2. POM 적용 후 구조

Fromm/web/
├── common/
│   ├── base.py           # ActionBase, ExpectBase를 조합하는 기반 클래스
│   ├── action_base.py    # 액션 메서드 (click, fill 등)
│   └── expect_base.py    # 검증 메서드 (expect 등)
└── store/
    ├── pages/
    │   ├── login_page.py
    │   ├── goods_page.py
    │   └── ...
    ├── steps/
    │   ├── login_steps.py
    │   └── ...
    └── components/
        ├── header.py
        └── menu.py

3-3. Base 클래스 설계

액션과 검증 책임을 분리하여 Base 클래스로 조합했습니다.
모든 Page 클래스는 이 Base를 상속받아 공통 메서드를 사용합니다.

class Base(ActionBase, ExpectBase, LogMixin):
    def __init__(self, page: Page):
        self.page = page
    ...

이렇게 분리한 이유는, Page 클래스에서 Playwright API를 직접 호출하지 않기 위해서입니다.
만약 Base 없이 Page 클래스마다 self.page.locator(selector).click() 같은 코드를 직접 작성하면, Playwright API가 변경될 때 모든 Page 클래스를 수정해야 합니다.
Base에서 한 번만 감싸두면 수정 포인트가 한 곳으로 줄어듭니다.

ActionBase는 click, fill 등 화면 조작 메서드를 제공합니다.

class ActionBase:
    def click(self, target: str | Locator, **kwargs) -> None:
        if isinstance(target, Locator):
            target.click()
        else:
            self.page.locator(target, **kwargs).click()

    def fill(self, target: str | Locator, value: str, **kwargs) -> None:
        if isinstance(target, Locator):
            target.fill(value)
        else:
            self.page.locator(target, **kwargs).fill(value)

또한 이렇게 래핑해두면 공통 동작을 한 곳에서 제어할 수 있습니다.
예를 들어, 사용자 인터랙션 시 불규칙하게 나타나는 팝업(공지, 알림 등)이 있다면, ActionBase의 click 메서드에 “팝업이 떠 있으면 닫기” 로직을 추가하는 것만으로 모든 Page 클래스에 일괄 적용할 수 있습니다.

ExpectBase는 expect_visible, expect_enabled 등 검증 메서드를 제공합니다.

class ExpectBase:
    def expect_visible(self, selector: str, **kwargs) -> None:
        expect(self.page.locator(selector, **kwargs)).to_be_visible()

    def expect_enabled(self, selector: str, **kwargs) -> None:
        expect(self.page.locator(selector, **kwargs)).to_be_enabled()

이렇게 래핑해두면 검증 방식의 일관성도 확보할 수 있습니다.
예를 들어, 버튼이 활성화 상태인지 검증할 때 누군가는 to_be_enabled()를 쓰고, 누군가는 not_to_be_disabled()를 쓸 수 있는데, expect_enabled로 통일해두면 이런 걱정 없이 코드가 일관성 있게 작성됩니다.

덕분에 Page 클래스에서는 self.click(selector), self.expect_visible(selector) 처럼 간결하게 호출할 수 있고, Playwright의 세부 구현을 알 필요가 없습니다.

3-4. Page 클래스 작성

class LoginPage(Base):
    @property
    def LOGIN_BTN(self):
        return self.page.get_by_text('로그인', exact=True)

    def click_login_btn(self) -> None:
        self.click(self.LOGIN_BTN)

    def expect_login_btn_enabled(self) -> None:
        self.expect_enabled(self.LOGIN_BTN)

3-5. Step 정의

Step 함수는 “무엇을 하는지”만 표현하고, “어떻게 하는지”는 Page 클래스가 담당합니다.

@when('Store [로그인] 버튼 클릭')
def click_login_btn(store_page: Page):
    LoginPage(store_page).click_login_btn()

@then('Store [로그인] 버튼 활성화')
def expect_login_btn_enabled(store_page: Page):
    LoginPage(store_page).expect_login_btn_enabled()

---

4. pytest-bdd 환경에서의 POM 적용 포인트

일반적인 POM 예제는 하나의 테스트 함수 안에서 Page 객체를 생성하고 사용합니다.
하지만 pytest-bdd에서는 Step 함수가 각각 분리되어 있기 때문에, POM을 적용할 때 추가적인 고려가 필요합니다.

4-1. Feature → Step → Page Object 구조

pytest-bdd를 사용하면 일반적인 POM보다 레이어가 하나 더 생깁니다.

여기서 Step과 Page의 역할 경계를 명확히 하는 것이 중요합니다.

• Page: 화면 조작, 로케이터 관리, 값 생성 및 return
• Step: Page 호출, 결과를 공유 fixture에 저장, 테스트 환경 정보(파일 경로 등) 전달

4-2. Page 객체를 fixture로 주입받는 구조

pytest-bdd의 Step 함수는 pytest fixture를 통해 브라우저 Page를 주입받습니다.
Step에서 직접 Page를 생성하는 것이 아니라, conftest.py에서 설정한 fixture를 받아서 Page Object에 넘기는 구조입니다.

# conftest.py
@pytest.fixture
def store_page(browser) -> Page:
    context = browser.new_context()
    page = context.new_page()
    page.goto('https://example.com/store')
    return page

# step 함수에서 fixture를 받아 Page Object에 전달
@when('Store [로그인] 버튼 클릭')
def click_login_btn(store_page: Page):
    LoginPage(store_page).click_login_btn()

4-3. Step 간 데이터 공유

pytest-bdd에서 가장 큰 차이점은 Step 함수가 각각 독립적이라는 것입니다.
일반 pytest에서는 하나의 테스트 함수 안에서 변수를 자유롭게 공유할 수 있지만, pytest-bdd에서는 Step A에서 만든 값을 Step B에서 사용하려면 공유 fixture가 필요합니다.

# conftest.py - 값을 공유할 저장소 fixture
@pytest.fixture
def shared_values():
    random_text = uuid4().hex[:6]
    return {'random_text': random_text}

# Step A: Page가 만든 값을 공유 저장소에 저장
@when('Store 회원가입 시 닉네임 입력')
def input_nickname(store_page: Page, shared_values):
    shared_values['nickname'] = SignupPage(store_page).input_nickname(
        shared_values['random_text']
    )

# Step B: 저장소에서 꺼내서 사용
@then('Store 마이페이지에서 닉네임 확인')
def check_nickname(store_page: Page, shared_values):
    nickname = shared_values['nickname']
    MyPage(store_page).expect_nickname(nickname)

이 패턴에서 Page 클래스는 값을 생성하고 return하는 역할만 하고, Step이 그 값을 공유 저장소에 저장하는 역할을 담당합니다. 이렇게 하면 Page 클래스는 pytest-bdd의 fixture 구조를 알 필요 없이 순수하게 화면 조작에만 집중할 수 있습니다.

---

마무리하며

POM 패턴을 도입한 후 다음과 같은 효과를 체감할 수 있었습니다.

• 로케이터 변경 시 영향 범위를 명확히 파악 가능
• 공통 메서드에 재시도 로직, 대기 로직 등을 일괄 적용 가능
• 테스트 코드와 페이지 상호작용 로직이 분리되어 관심사가 명확해짐

물론 전환 과정이 순탄하지만은 않았습니다. 처음에는 기존 Step 파일에 로케이터와 로직이 뒤섞여 있어서, 어디까지를 Page 클래스로 옮기고 어디까지를 Step에 남길지 경계를 잡는 게 어려웠습니다.
또한 기존 테스트를 유지하면서 점진적으로 전환해야 했기 때문에, 저희 팀은 한 페이지부터 전환하고, 패턴이 익숙해지면 다음 페이지로 넘어가는 방식을 택했고, 이 방식이 훨씬 효과적이었습니다.

긴 글 읽어주셔서 감사합니다. 비슷한 고민을 하고 계신 분들께 조금이나마 도움이 되었으면 합니다.