Selenium·Playwright 로케이터 입문 | CSS 선택자·XPath·data-testid 사용법 완벽 가이드

Selenium·Playwright로 브라우저 자동화를 할 때 첫 번째 난관은 “요소를 어떻게 특정하는가”입니다. CSS 셀렉터와 XPath의 작성법을 이해하면 테스트 코드의 안정성이 크게 달라집니다. 이 글에서는 로케이터의 기초부터 깨지지 않는 작성법의 노하우까지 해설합니다.

📌 이 글의 대상 독자

📖 이 글을 읽으면 할 수 있는 것

필자는 여러 프로젝트에서 Selenium·Playwright를 사용한 브라우저 자동화 테스트를 실천해 왔습니다.
로케이터가 원인이 되어 E2E 테스트가 불안정해지는 경우는 매우 많으며, 이 글은 그 경험을 바탕으로 실무에서 사용할 수 있는 작성법에 집중해서 해설합니다.

로케이터란 무엇인가

로케이터(Locator)란 웹 페이지 상의 특정 요소(버튼·텍스트박스·링크 등)를 찾기 위한 지정 방법입니다.

Selenium이나 Playwright가 브라우저를 조작할 때, “어떤 요소를 클릭할 것인가”, “어떤 텍스트박스에 문자를 입력할 것인가”를 로케이터로 지정합니다.

# 로케이터 예시 (Selenium)
driver.find_element(By.ID, "login-btn")                               # ID로 탐색
driver.find_element(By.CSS_SELECTOR, "#form input[type='email']")     # CSS로 탐색
driver.find_element(By.XPATH, "//button[@type='submit']")             # XPath로 탐색

로케이터가 깨진다 = 테스트가 실패한다는 직접적인 관계가 있으므로, 깨지기 어려운 로케이터를 선택하는 것이 테스트 안정성을 크게 좌우합니다.

로케이터의 종류와 사용 구분

CSS 셀렉터 작성법

CSS 셀렉터는 HTML 구조를 사용해 요소를 특정하는 방식입니다. 프런트엔드 개발자에게는 익숙하며, Selenium·Playwright 양쪽에서 사용할 수 있습니다.

기본 작성법

# HTML 예시:
# <input id="email" class="form-input" type="email" name="email" />

# ID로 지정 (# 붙이기)
"#email"

# 클래스로 지정 (. 붙이기)
".form-input"

# 속성으로 지정 ([ ]로 감싸기)
"[type='email']"
"[name='email']"

# 태그 + 클래스 조합
"input.form-input"

# 부모자식 관계 (스페이스 구분: 간접 자손)
".login-form input"

# 직접 자식 요소 (> 구분)
".login-form > input"

로케이터 선택 흐름

헷갈릴 때는 “사용자가 인식할 수 있는 요소”를 우선하는 생각이 Playwright에서는 권장됩니다. 화면을 보고 사용자가 “로그인 버튼”으로 인식한다면 get_by_role("button", name="로그인"), “이메일 주소 칸”으로 인식한다면 get_by_label("이메일 주소")가 자연스러운 선택입니다.

실무에서 자주 쓰는 패턴

# data-testid (가장 안정적)
"[data-testid='login-button']"

# 폼 입력 필드
"input[type='email']"
"input[type='password']"
"input[placeholder='이메일 주소']"

# 버튼
"button[type='submit']"
"button.btn-primary"

# 링크
"a[href='/dashboard']"

# 부분 일치 (^=시작, $=끝, *=포함)
"[data-testid^='item-']"    # data-testid가 "item-"으로 시작하는 요소
"[class*='active']"          # class에 "active"를 포함하는 요소

XPath 작성법

XPath는 XML·HTML 문서를 탐색하기 위한 쿼리 언어입니다. CSS 셀렉터보다 표현력이 높고, 텍스트 내용이나 요소의 형제 관계 등 CSS에서는 어려운 조건도 작성할 수 있습니다.

기본 작성법

# //태그[@속성='값']  ← 가장 기본적인 상대 XPath
"//button[@type='submit']"
"//input[@id='email']"

# 텍스트 내용으로 지정 (다국어 서비스에서는 주의)
"//button[text()='로그인']"
"//button[contains(text(),'로그')]"   # 부분 일치

# 복수 조건 (and로 연결)
"//input[@type='text' and @name='username']"

# 부모 요소에서 지정 (./)
"//form[@id='login-form']//button[@type='submit']"

# 절대 XPath (비권장: HTML 구조가 바뀌면 바로 깨진다)
# /html/body/div[1]/main/form/button[2]  ← 이것은 사용 금지

CSS vs XPath 사용 구분

Selenium에서의 로케이터 사용법

Selenium 4.x에서는 By 클래스를 사용해 요소를 지정합니다.

from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

driver = webdriver.Chrome()
driver.get("https://example.com/login")  # 샘플 URL

# 요소를 취득해서 조작
email_input = driver.find_element(By.ID, "email")
email_input.send_keys("user@example.com")              # 텍스트 입력

password_input = driver.find_element(By.CSS_SELECTOR, "input[type='password']")
password_input.send_keys("password123")                # 텍스트 입력

submit_btn = driver.find_element(By.CSS_SELECTOR, "[data-testid='login-button']")
submit_btn.click()                                     # 클릭

# 요소가 표시될 때까지 대기한 후 취득·조작 (권장)
wait = WebDriverWait(driver, 10)
error_msg = wait.until(
    EC.presence_of_element_located((By.CSS_SELECTOR, "[data-testid='error-message']"))
)
assert "비밀번호가 올바르지 않습니다" in error_msg.text

Selenium vs Playwright: 대기 전략의 차이

Playwright에서의 로케이터 사용법

Playwright는 Selenium보다 새로운 로케이터 API를 가지고 있어, 의미 있는(시맨틱한) 로케이터를 사용할 수 있습니다. HTML 구조가 아닌 “역할”이나 “텍스트”로 지정하므로 디자인 변경에 강한 것이 특징입니다.

Selenium vs Playwright: 로케이터 기능 비교

권장되는 로케이터

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    page.goto("https://example.com/login")  # 샘플 URL

    # data-testid로 지정 (가장 안정적)
    page.get_by_test_id("login-button").click()

    # role + name으로 지정 (ARIA 역할 활용)
    page.get_by_role("button", name="로그인").click()
    page.get_by_role("textbox", name="이메일 주소").fill("user@example.com")

    # 텍스트 내용으로 지정
    page.get_by_text("로그인").click()                  # 완전 일치
    page.get_by_text("로그", exact=False).click()       # 부분 일치

    # label 텍스트로 폼 요소 지정
    page.get_by_label("이메일 주소").fill("user@example.com")

    # 플레이스홀더로 지정
    page.get_by_placeholder("example@email.com").fill("user@example.com")

    # CSS 셀렉터로 지정 (기존 방식도 사용 가능)
    page.locator("[data-testid='login-button']").click()
    page.locator("input[type='password']").fill("password123")

    browser.close()

Playwright 로케이터 우선순위

data-testid로 깨지지 않는 테스트 만들기

data-testid 속성은 테스트 전용 식별자로, 디자인 변경이나 리팩터링의 영향을 받지 않습니다. 개발팀과 협력해서 테스트 대상 요소에 부여함으로써 유지보수 비용을 크게 줄일 수 있습니다.

<!-- HTML 쪽에 data-testid 부여 -->
<button type="submit" data-testid="login-submit-btn">
  로그인
</button>

<input type="email"
       data-testid="login-email-input"
       placeholder="이메일 주소" />

# Selenium에서 사용
driver.find_element(By.CSS_SELECTOR, "[data-testid='login-submit-btn']").click()

# Playwright에서 사용
page.get_by_test_id("login-submit-btn").click()
page.get_by_test_id("login-email-input").fill("user@example.com")

로케이터에서 막히기 쉬운 포인트 7가지

자주 묻는 질문 (FAQ)

정리

로케이터 선택법을 개선하는 것만으로도 테스트의 안정성은 크게 달라집니다.
우선 현재 보유한 테스트 코드에서 절대 XPath나 동적 클래스명을 사용하고 있는 로케이터를 찾아 data-testid나 속성 기반의 로케이터로 바꾸는 것부터 시작해 보세요.

로케이터가 안정되면 다음 단계로 Page Object Model(POM)을 사용한 테스트 코드 정리에 임하면 더욱 유지보수하기 쉬워집니다.