깨지지 않는 로케이터 설계하기: 사용자 관점으로 요소 찾기

개념

로케이터(Locator)란

레슨 2에서 요소를 찾는 여러 방법을 봤다 — 이 "요소를 찾는 방법"을 로케이터라 부른다. 같은 버튼을 찾더라도 로케이터를 어떻게 짜느냐에 따라, 그 테스트가 디자인 변경에 얼마나 잘 버티는지가 완전히 달라진다.

로케이터의 안정성 등급

모듈 10(레슨 6)에서 배운 "구현 세부사항 vs 사용자 관점" 원칙을, 로케이터 선택에 구체적으로 적용하면 다음과 같은 우선순위가 나온다.

1순위 — 역할·라벨 기반 (가장 안정적)
   getByRole("button", { name: "구매하기" })
   getByLabel("이메일")
 
2순위 — 테스트 전용 속성
   getByTestId("submit-button")
 
3순위 — 화면에 보이는 텍스트
   getByText("구매하기")
 
4순위 — CSS 클래스, XPath (가장 불안정, 지양)
   page.locator(".btn-primary-lg-v2")

왜 CSS 클래스가 가장 불안정한가

CSS 클래스 이름은 디자인 시스템이나 스타일링 라이브러리가 바뀌면 가장 먼저 바뀌는 부분이다. .btn-primary-lg-v2처럼 스타일링 목적으로 붙은 클래스는, 개발자가 "이 버튼을 좀 더 눈에 띄게 하자"고 리팩터링만 해도 깨질 수 있다 — 정작 버튼의 기능(구매하기)은 전혀 안 바뀌었는데도 테스트가 실패한다.

역할·라벨 기반이 왜 가장 안정적인가

page.getByRole("button", { name: "구매하기" })

이 로케이터는 "구매하기라는 이름의 버튼"을 찾는다 — 이건 스크린 리더 사용자가 이 요소를 인식하는 방식과 정확히 같다. 디자인이나 CSS가 어떻게 바뀌든, 버튼이라는 역할과 "구매하기"라는 목적이 유지되는 한 이 로케이터는 계속 작동한다. 이건 접근성(웹 콘텐츠를 장애가 있는 사용자도 이용할 수 있게 만드는 것, 모듈 16에서 다룬다)을 잘 지킨 화면일수록 로케이터도 안정적으로 짜기 쉽다는 뜻이기도 하다.

테스트 전용 속성(`data-testid`)을 쓰는 경우

역할이나 텍스트만으로 요소를 특정하기 애매한 경우(예: 텍스트 없는 아이콘 버튼, 같은 이름의 요소가 여러 개)에는, 개발자와 협의해서 테스트 전용 속성을 추가하기도 한다.

<button data-testid="cart-icon">🛒</button>

page.getByTestId("cart-icon")

이 속성은 오직 테스트를 위해 존재하므로, 디자인이 바뀌어도 안 바뀔 가능성이 높다 — 다만 개발자가 이 속성을 실수로 지우면 안 된다는 새로운 의존성이 생긴다는 점은 감안해야 한다.

로케이터가 여러 개를 찾을 때

// 나쁜 예 — "삭제" 버튼이 여러 개면 어느 것인지 모호함
page.getByRole("button", { name: "삭제" })
 
// 좋은 예 — 특정 영역(스코프) 안에서만 찾기
page.getByRole("listitem", { name: "상품 A" })
    .getByRole("button", { name: "삭제" })

모호한 로케이터는 "여러 요소가 발견됨" 에러로 테스트를 실패시킨다 — 범위를 좁혀서 정확히 하나의 요소만 가리키도록 설계해야 한다.

실무에서 왜 필요한가

"디자인 팀이 버튼 스타일을 살짝 바꿨을 뿐인데 자동화 테스트 30개가 깨졌다"는 사고는 CSS 클래스 기반 로케이터의 전형적인 실패 사례다(모듈 11 레슨 4의 자동화 부채와 직결된다). 역할·라벨 기반 로케이터를 우선하는 습관은, 자동화 테스트를 디자인 변경에 훨씬 강하게 만들어 유지보수 비용을 크게 줄인다.

실습 과제

과제 1 — 로케이터 등급 매기기 (10분)

다음 세 로케이터를 안정성 등급(1~4순위) 순으로 정렬하고 이유를 설명한다.

page.locator("#submit-btn-2024")
page.getByRole("button", { name: "제출" })
page.getByText("제출")

과제 2 — 모호한 로케이터 고치기 (15분)

"상품 목록에서 각 상품 카드마다 '장바구니 담기' 버튼이 있다"는 화면에서, 특정 상품(예: "무선 이어폰")의 버튼만 정확히 찾는 로케이터를 이 레슨의 스코프 좁히기 예시를 참고해 작성한다.

자가 체크리스트

로케이터의 안정성 등급(역할·라벨 > 테스트 속성 > 텍스트 > CSS/XPath)을 설명할 수 있다
CSS 클래스 기반 로케이터가 왜 쉽게 깨지는지 설명할 수 있다
역할·라벨 기반 로케이터가 접근성과 어떻게 연결되는지 설명할 수 있다
모호한 로케이터를 스코프를 좁혀 명확하게 만들 수 있다

흔한 실수

CSS 클래스나 XPath를 기본 선택지로 습관적으로 쓴다. 역할·라벨 기반을 먼저 시도하는 습관이 장기적으로 훨씬 적은 유지보수 비용으로 이어진다.
텍스트가 같은 요소가 여러 개 있는데 스코프를 좁히지 않는다. "여러 요소가 발견됨" 에러로 테스트가 예측 불가능하게 실패한다.
data-testid를 모든 요소에 남발한다. 역할·라벨로 충분히 특정 가능한 요소까지 테스트 전용 속성에 의존하면, 실제 접근성 개선 유인이 줄어들 수 있다.

참고 자료

Playwright 공식 문서 — Locators, Best Practices — 로케이터 우선순위의 공식 권장 사항
Testing Library — Priority 가이드 — 역할·라벨 우선 원칙의 공식 설명(모듈 10 레슨 6과 동일한 철학)

개념