Playwright locators란? 화면이 바뀌어도 멈추지 않는 테스트 쓰는 법

테스트가 화면에서 버튼 하나를 누르려면, 그 버튼이 어느 것인지 먼저 지목해야 합니다. 그 지목 방법을 로케이터라고 하고, Playwright locators 가 그 역할을 맡습니다. Playwright는 로케이터를 7가지 제공하고, 그중 무엇을 고르느냐에 따라 화면을 조금 고쳤을 때 테스트가 그대로 도는지, 한꺼번에 멈추는지 가 갈립니다. 이 글은 7가지를 고르는 기준과, 그럼에도 테스트가 멈추는 경우를 정리합니다.

요소를 찾는다는 것

사람에게 "로그인 버튼을 눌러 주세요"라고 하면 그냥 됩니다. 화면에서 로그인이라고 적힌 것을 찾아 누르면 되니까요.

기계에게는 그 한 줄이 통하지 않습니다. 화면은 기계 입장에서 글자와 상자가 겹겹이 쌓인 구조물이고, 그 안에서 어느 것이 로그인 버튼인지 정해 줘야 합니다. 이 지목을 담당하는 것이 로케이터입니다.

같은 버튼을 지목하는 방법은 여러 가지입니다.

• 위에서 세 번째 상자 안의 두 번째 요소
• 클래스 이름이 btn-primary인 요소
• 로그인이라고 적힌 버튼

셋 다 지금 화면에서는 같은 버튼을 가리킵니다. 그런데 화면을 고치는 순간 셋의 운명이 갈립니다. 상자를 하나 추가하면 첫 번째가 멈추고, 디자인을 손보면서 클래스 이름을 바꾸면 두 번째가 멈춥니다. 세 번째는 버튼에 적힌 글자가 그대로인 한 계속 찾아냅니다.

Playwright가 로케이터를 설계하면서 붙든 기준이 정확히 여기입니다.

지목 방식에 따라 화면을 고쳤을 때 결과가 갈립니다

Playwright locators 7가지

Playwright 공식 문서는 내장 로케이터 7가지를 안내하고, 그중 사용자에게 보이는 속성을 쓰는 쪽을 권장합니다.

앞의 6가지에는 공통점이 하나 있습니다. 사람이 화면을 볼 때 실제로 인식하는 것들입니다. 버튼에 적힌 글자, 입력칸에 붙은 라벨, 이미지 설명. 화면 구조가 아니라 화면의 의미를 기준으로 삼습니다.

Playwright 로케이터는 사람이 보는 것으로 지목하는 쪽을 먼저 권합니다

await page.getByRole('button', { name: '로그인' }).click();

이 한 줄은 버튼이 화면 어디에 있든, 어떤 상자 안에 들어 있든 상관하지 않습니다. 역할이 버튼이고 이름이 로그인이면 찾아냅니다.

getByRole을 먼저 권하는 이유

7가지 중 Playwright가 첫 번째로 권하는 것은 getByRole입니다. 역할과 이름 2가지로 지목하는 방식입니다.

역할은 그 요소가 화면에서 하는 일입니다. 버튼, 링크, 제목, 체크박스처럼 브라우저가 이미 알고 있는 분류입니다. 이름은 그 요소에 붙은 사람이 읽을 수 있는 글자입니다.

await expect(page.getByRole('heading', { name: '회원가입' })).toBeVisible();
await page.getByRole('checkbox', { name: '약관 동의' }).check();
await page.getByRole('button', { name: /제출/i }).click();

이 방식에는 부수 효과가 하나 더 있습니다. 역할과 이름은 화면 낭독기 같은 보조 기술이 화면을 읽을 때 쓰는 정보와 같습니다. 그래서 getByRole로 지목이 안 되는 요소는 대개 보조 기술로도 읽히지 않는 요소입니다. 테스트를 적다가 접근성 문제를 먼저 발견하게 되는 셈입니다.

그런데도 테스트가 멈추는 3가지 경우

로케이터를 잘 골라도 테스트가 멈추는 상황은 남습니다. 3가지가 대표적입니다.

1. 글자가 바뀐 경우. "로그인"을 "시작하기"로 바꾸면 이름으로 지목하던 로케이터는 더 이상 찾지 못합니다. 이건 테스트가 잘못된 것이 아닙니다. 화면이 실제로 바뀌었고, 테스트가 그것을 알려 준 것입니다. 다만 알려 주는 방식이 실패이기 때문에 매번 사람이 확인해야 합니다.

2. 같은 이름이 여러 개인 경우. 목록에 "삭제" 버튼이 10개 있으면 이름만으로는 어느 것인지 정할 수 없습니다. 이때는 범위를 좁혀서 지목합니다.

await page.getByRole('listitem')
  .filter({ hasText: '주문 번호 1024' })
  .getByRole('button', { name: '삭제' })
  .click();

3. 화면이 아직 준비되지 않은 경우. 데이터를 불러오는 동안에는 버튼이 없다가 나중에 생깁니다. Playwright는 이 경우 요소가 나타날 때까지 기다리도록 만들어져 있어서, 대부분은 따로 처리하지 않아도 됩니다. 다만 화면이 여러 단계로 나뉘어 나타나는 구조라면 무엇을 기준으로 기다릴지 정해 줘야 합니다.

오래 가는 테스트 코드를 적는 4가지 기준

정리하면 이렇게 됩니다.

1. 사람이 보는 것으로 지목합니다. 글자, 라벨, 역할. 화면 구조나 클래스 이름은 마지막 수단입니다.
2. 한 번에 하나만 가리키게 합니다. 여러 개가 걸리면 범위를 좁혀 지목합니다.
3. 표식은 필요할 때만 심습니다. getByTestId는 앞의 6가지로 안 될 때 쓰는 것이고, 처음부터 모든 요소에 표식을 다는 방식은 화면과 테스트를 둘 다 무겁게 만듭니다.
4. 테스트가 멈추면 먼저 화면을 봅니다. 테스트를 고치기 전에 화면이 의도대로 바뀐 것인지 확인해야 합니다. 순서를 반대로 하면 테스트는 통과하는데 화면은 잘못된 상태가 됩니다.

이건 Playwright의 문제가 아닙니다

여기까지 읽으면 로케이터가 유지보수의 원인처럼 보일 수 있습니다. 그렇지 않습니다.

요소를 지목하는 방식을 사용자가 보는 기준으로 끌어올린 것은 Playwright가 특히 잘 만든 부분입니다. 화면 구조에 기대던 예전 방식과 비교하면 테스트가 멈추는 빈도가 크게 줄었습니다. 기다림을 기본 동작으로 넣은 것도 같은 맥락입니다.

남은 일은 도구가 풀 수 있는 종류가 아닙니다. 화면이 바뀌었을 때 그것이 의도한 변경인지 아닌지 판단하는 일입니다. 이 판단에는 무엇이 맞는 상태인지에 대한 기준이 필요하고, 그 기준은 코드 안에 없습니다.

이어서 읽기Playwright MCP란? 강점 7가지와 상황별 선택 3가지playwright mcpplaywright9분

조작을 그대로 코드로 받아 적는 codegen 편에서도 결국 같은 자리에 닿았습니다. 테스트를 오래 유지하는 팀은 로케이터를 잘 적는 데서 끝내지 않습니다. 화면이 바뀔 때마다 무엇이 바뀌었는지 먼저 확인하고, 바뀐 범위를 다시 정한 다음 테스트를 손봅니다. 순서가 이렇게 되어야 테스트가 통과만 하는 상태로 흘러가지 않습니다.

이어서 읽기Playwright codegen이란? 테스트 코드를 대신 만드는 2가지 방법playwright codegenplaywright8분

Specnote는 이 순서를 제품으로 만들었습니다

Specnote는 코드를 읽지 못하는 사람도 이 순서를 밟을 수 있게 만든 도구입니다. AI가 무엇을 만들었는지 목록으로 정리해 보여 주고, 사람이 그 목록을 확인해 승인하면, 승인된 범위만 실제 브라우저에서 확인합니다. 로케이터를 직접 적지 않아도 됩니다.

다만 코드를 읽고 고칠 수 있다면 Playwright로 직접 적는 편이 더 정밀합니다. 이 글에 적은 기준대로 로케이터를 고르면 대부분의 유지보수는 줄어듭니다. 저희가 겨냥한 자리는 그 일을 할 시간이나 사람이 없는 쪽입니다.

이 글의 기술 내용은 Playwright 공식 문서 · Locators를 기준으로 2026년 8월 21일에 확인했습니다.