콘텐츠로 이동

Playwright 셀렉터 (요소 선택)

개요

테스트 코드에서 "이 요소를 클릭해"라고 말하려면, 그 요소를 가리킬 방법이 있어야 해요. Playwright는 이때 셀렉터(selector) 를 써요. 셀렉터란 페이지 안에서 요소를 찾기 위한 문자열인데, page.click(...), page.fill(...) 같은 메서드가 첫 번째 인자로 받는 값이죠. 그런데 셀렉터를 어떻게 짜느냐에 따라 테스트가 리팩터링에 잘 견디는지, 아니면 버튼 하나 바뀔 때마다 깨지는지가 갈라져요. 이 페이지는 Playwright 공식 문서 기준으로 셀렉터의 종류와, 유지보수 잘 되는 셀렉터를 고르는 법을 풀어요.

핵심 개념

텍스트 셀렉터

사용자가 보는 텍스트로 요소를 찾는 방식이에요. text=Log in처럼 쓰는데, 기본적으로 대소문자를 무시하고 부분 문자열을 찾아요. text="Log in"처럼 따옴표로 감싸면 해당 텍스트 노드가 정확히 일치할 때만 매칭돼요. 정규식도 지원해서 text=/Log\s*in/i처럼 쓸 수 있어요.

CSS 안에서 텍스트를 쓰는 의사 클래스도 있어요. article:has-text("Playwright")는 그 요소의 자손 어딘가에 해당 텍스트를 가진 article을 찾고, #nav-bar :text("Home")은 nav-bar 안에서 텍스트가 "Home"인 가장 작은 요소를 골라요. 이때 공백은 항상 정규화돼요 — 여러 공백은 하나로, 줄바꿈은 공백으로 처리되죠.

CSS 셀렉터

일반 CSS 셀렉터도 그대로 써요. button, #nav-bar .contact-us-item처럼요. 다만 Playwright는 CSS를 두 가지로 보강해요. 하나는 open shadow DOM을 기본으로 뚫고 들어가는 점이고, 다른 하나는 :visible 같은 커스텀 의사 클래스를 제공하는 점이에요.

input:visible처럼 쓰면 보이는 요소만 골라요. display:none인 요소는 보이지 않는 것으로, 반대로 opacity:0인 요소는 보이는 것으로 취급돼요. 화면에 감춰진 버튼과 보이는 버튼이 함께 있을 때, 이걸로 구분할 수 있어요.

id, data-testid 셀렉터

id=, data-testid= 같은 속성 기반 셀렉터도 있어요. data-testid=submit처럼 쓰죠. 이건 순수 CSS 셀렉터가 아니라서 :enabled 같은 CSS 전용 기능은 못 쓰지만, 내부 구현에 붙은 마커를 간단히 찾을 때 편리해요.

셀렉터 체이닝

셀렉터는 >> 토큰으로 이어 붙일 수 있어요. css=article >> css=.bar > .baz처럼 쓰면 앞의 결과 안에서 뒤 셀렉터를 다시 찾아요. 더 좁은 범위로 내려가며 요소를 좁힐 때 유용하죠.

서드 파티 셀렉터와 레이아웃 셀렉터

React·Vue 컴포넌트 이름으로 찾는 _react=·_vue= 셀렉터는 실험 단계예요. 또 페이지 배치로 요소를 찾는 :right-of(), :left-of(), :above(), :below(), :near() 같은 레이아웃 셀렉터도 있어요. 다만 이들은 화면 배치에 의존해서 1픽셀만 바뀌어도 결과가 달라질 수 있어, 공식 문서도 예상 밖의 결과가 나올 수 있다고 경고해요.

좋은 셀렉터 고르기 (Best practices)

공식 문서는 셀렉터 선택이 곧 자동화 스크립트의 복원력(resiliency) 을 결정한다고 해요. 유지보수 부담을 줄이려면 이런 기준을 추천해요.

  • 사용자에게 보이는 속성 우선 — 텍스트 콘텐츠, input의 placeholder, 접근성 role·label처럼 사용자가 보는 속성을 먼저 써요. DOM 구조가 바뀌어도 잘 안 깨져요.
  • 명시적 계약(contract) 필요 시 data 속성 — 사용자에게 보이는 속성이 자주 바뀐다면 data-testid 같은 명시적 테스트 ID를 붙여요.
  • 구현에 묶인 셀렉터 피하기 — #tsf > div:nth-child(2) 같은 DOM 구조에 의존하는 XPath·CSS는 구조가 바뀌면 함께 깨져요. 마지막 수단으로만 써요.

실제 적용 (데이터스케쳐스)

웹빌더에서 E2E 자동화를 시작할 때 가장 먼저 정해야 할 게 요소를 어떤 기준으로 찾을지예요. 못 찾는 것보다 더 자주 깨지는 게 "찾는 기준이 잘못된" 경우죠. 예를 들어 문서 표의 경계선 검사를 재현한다면, 버튼을 클래스명 대신 "표 저장"이라는 화면 텍스트나 role로 찾으면, 스타일 리팩터링이 들어와도 테스트는 그대로 살아 있어요.

정말 자주 바뀌는 UI 컨트롤에는 data-testid를 명시적으로 넣어 두는 편이 좋아요. 캔버스에서 노드를 옮기거나 요소 순서를 바꾸는 인터랙션처럼 "사용자가 보는 기준"이 모호한 곳이 그 경우죠. 셀렉터 원칙을 세워 두면, 테스트가 리팩터링 때마다 무너지는 일을 줄일 수 있어요. 셀렉터와 함께 봐야 할 자동 대기 동작은 자동 대기에서, 모바일·네트워크 재현은 에뮬레이션에서 이어져요.

더 알아보기