Playwright을 찾는 분이 가장 먼저 구분해야 할 기준부터 실제 순서까지 정리했습니다. Playwright 테스트는 한 번 통과했다는 결과보다 사용자가 보는 요소를 안정적으로 찾고, 실패 시 어떤 동작과 네트워크 요청에서 달라졌는지 재현할 수 있어야 가치가 있습니다. 셀렉터, 대기 조건, 테스트 데이터, 실행 환경을 분리해 확인하세요.
읽는 시간 약 7분 · 가이드: 판단 기준 · 실행 순서 · 구매와 보관
Playwright 문제 정의: 먼저 기준을 세워야 하는 이유
Playwright 테스트는 한 번 통과했다는 결과보다 사용자가 보는 요소를 안정적으로 찾고, 실패 시 어떤 동작과 네트워크 요청에서 달라졌는지 재현할 수 있어야 가치가 있습니다. 셀렉터, 대기 조건, 테스트 데이터, 실행 환경을 분리해 확인하세요.
불안정한 테스트에서 고정 시간 대기와 재시도 횟수만 늘리면 원인이 가려집니다. 사용자 관점의 locator를 우선하고 실패한 첫 실행의 trace를 남긴 뒤, 단일 테스트를 같은 환경에서 재현해야 고칠 지점을 분리할 수 있습니다.
| 첫 확인 | strict 충돌 0 |
|---|
현실 차이: 겉으로 비슷해도 결과가 달라지는 지점
보이는 요소와 안정적인 locator의 차이
화면에서 같은 버튼처럼 보여도 접근성 역할과 이름이 달라지면 테스트가 다른 요소를 찾거나 여러 요소와 충돌할 수 있습니다.
Playwright 테스트의 보이는 요소와 안정적인 locator의 차이 단계에서는 getByRole과 사용자에게 보이는 이름을 우선해 대상이 하나인지 확인하세요. 이때 다른 조건은 유지해야 보이는 요소와 안정적인 locator의 차이에서 생긴 차이를 분리해 확인할 수 있습니다.
현실 관점의 판정 신호는 locator 1개 일치입니다. 보이는 요소와 안정적인 locator의 차이의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
보이는 요소와 안정적인 locator의 차이 확인은 getByRole과 사용자에게 보이는 이름을 우선해 대상이 하나인지 확인하세요. 이후 locator 1개 일치 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 보이는 요소와 안정적인 locator의 차이 결과가 한 번 더 재현되는지 확인하세요.
| 현실 확인 | locator 1개 일치 |
|---|
자동 대기와 고정 시간 대기의 차이
고정된 timeout은 느린 환경에서 부족하고 빠른 환경에서는 불필요하게 실행 시간을 늘립니다.
이 항목의 자동 대기와 고정 시간 대기의 차이 단계에서는 요소의 visible, enabled 같은 실제 준비 상태를 assertion으로 기다리세요. 이때 다른 조건은 유지해야 자동 대기와 고정 시간 대기의 차이에서 생긴 차이를 분리해 확인할 수 있습니다.
현실 관점의 판정 신호는 상태 기반 대기입니다. 자동 대기와 고정 시간 대기의 차이의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
자동 대기와 고정 시간 대기의 차이 확인은 요소의 visible, enabled 같은 실제 준비 상태를 assertion으로 기다리세요. 이후 상태 기반 대기 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 자동 대기와 고정 시간 대기의 차이 결과가 한 번 더 재현되는지 확인하세요.
| 현실 확인 | 상태 기반 대기 |
|---|
로컬 통과와 CI 재현의 차이
브라우저 버전, 테스트 데이터, 병렬 실행, 네트워크 지연이 다르면 로컬 성공이 CI 성공을 보장하지 않습니다.
이 항목의 로컬 통과와 CI 재현의 차이 단계에서는 실패한 CI 실행의 trace와 프로젝트 설정을 함께 보존하세요. 이때 다른 조건은 유지해야 로컬 통과와 CI 재현의 차이에서 생긴 차이를 분리해 확인할 수 있습니다.
현실 관점의 판정 신호는 CI trace 확보입니다. 로컬 통과와 CI 재현의 차이의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
로컬 통과와 CI 재현의 차이 확인은 실패한 CI 실행의 trace와 프로젝트 설정을 함께 보존하세요. 이후 CI trace 확보 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 로컬 통과와 CI 재현의 차이 결과가 한 번 더 재현되는지 확인하세요.
| 현실 확인 | CI trace 확보 |
|---|
Playwright 판단 기준 3가지
기준 1 · locator 고유성
한 요소 동작은 대상이 하나로 식별되어야 하며 DOM 위치에 강하게 묶인 긴 CSS 경로는 화면 변경에 취약합니다.
Playwright 테스트의 기준 1 · locator 고유성 단계에서는 role, label, text, test id 순서로 사용자 계약에 가까운 기준을 선택하세요. 이때 다른 조건은 유지해야 기준 1 · locator 고유성에서 생긴 차이를 분리해 확인할 수 있습니다.
판단 관점의 판정 신호는 strict 충돌 0입니다. 기준 1 · locator 고유성의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
기준 1 · locator 고유성 확인은 role, label, text, test id 순서로 사용자 계약에 가까운 기준을 선택하세요. 이후 strict 충돌 0 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 기준 1 · locator 고유성 결과가 한 번 더 재현되는지 확인하세요.
| 판단 확인 | strict 충돌 0 |
|---|
기준 2 · trace 증거
실패 순간의 DOM snapshot, action log, network 요청을 함께 볼 수 있어야 추측 없이 원인을 좁힐 수 있습니다.
이 항목의 기준 2 · trace 증거 단계에서는 CI에서는 첫 재시도에 trace를 남기고 실패 실행과 연결하세요. 이때 다른 조건은 유지해야 기준 2 · trace 증거에서 생긴 차이를 분리해 확인할 수 있습니다.
판단 관점의 판정 신호는 실패 trace 연결입니다. 기준 2 · trace 증거의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
기준 2 · trace 증거 확인은 CI에서는 첫 재시도에 trace를 남기고 실패 실행과 연결하세요. 이후 실패 trace 연결 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 기준 2 · trace 증거 결과가 한 번 더 재현되는지 확인하세요.
| 판단 확인 | 실패 trace 연결 |
|---|
기준 3 · 재시도 분류
첫 실행 실패 후 재시도 통과는 정상 통과가 아니라 flaky 신호이므로 원인 후보로 남겨야 합니다.
이 항목의 기준 3 · 재시도 분류 단계에서는 passed, flaky, failed를 분리해 최근 반복 빈도를 확인하세요. 이때 다른 조건은 유지해야 기준 3 · 재시도 분류에서 생긴 차이를 분리해 확인할 수 있습니다.
판단 관점의 판정 신호는 flaky 별도 기록입니다. 기준 3 · 재시도 분류의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
기준 3 · 재시도 분류 확인은 passed, flaky, failed를 분리해 최근 반복 빈도를 확인하세요. 이후 flaky 별도 기록 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 기준 3 · 재시도 분류 결과가 한 번 더 재현되는지 확인하세요.
| 판단 확인 | flaky 별도 기록 |
|---|
| 확인 항목 | 권장 신호 | 피할 신호 |
|---|---|---|
| 기준 1 · locator 고유성 | strict 충돌 0 | 한 요소 동작은 대상이 하나로 식별되어야 하며 DOM 위치에 강하게 묶인 긴 CSS 경로는 화면 변경에 취약합니다. |
| 기준 2 · trace 증거 | 실패 trace 연결 | 실패 순간의 DOM snapshot, action log, network 요청을 함께 볼 수 있어야 추측 없이 원인을 좁힐 수 있습니다. |
| 기준 3 · 재시도 분류 | flaky 별도 기록 | 첫 실행 실패 후 재시도 통과는 정상 통과가 아니라 flaky 신호이므로 원인 후보로 남겨야 합니다. |
Playwright 실행법 3단계
1단계 · 테스트 계약 고정
검증할 사용자 행동, 시작 URL, 계정 상태, 기대 결과를 한 테스트에 하나씩 명확하게 적습니다.
Playwright 테스트의 1단계 · 테스트 계약 고정 단계에서는 실패 재현에 필요한 데이터와 브라우저 프로젝트를 함께 고정하세요. 이때 다른 조건은 유지해야 1단계 · 테스트 계약 고정에서 생긴 차이를 분리해 확인할 수 있습니다.
실행 관점의 판정 신호는 입력 조건 고정입니다. 1단계 · 테스트 계약 고정의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
1단계 · 테스트 계약 고정 확인은 실패 재현에 필요한 데이터와 브라우저 프로젝트를 함께 고정하세요. 이후 입력 조건 고정 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 1단계 · 테스트 계약 고정 결과가 한 번 더 재현되는지 확인하세요.
| 실행 확인 | 입력 조건 고정 |
|---|
2단계 · locator와 assertion 점검
실패한 동작의 locator가 사용자에게 보이는 속성을 쓰는지, 대상이 하나인지, 준비 상태를 assertion으로 기다리는지 확인합니다.
이 항목의 2단계 · locator와 assertion 점검 단계에서는 고정 대기를 추가하기 전에 locator 한 변수만 수정하세요. 이때 다른 조건은 유지해야 2단계 · locator와 assertion 점검에서 생긴 차이를 분리해 확인할 수 있습니다.
실행 관점의 판정 신호는 대상·상태 일치입니다. 2단계 · locator와 assertion 점검의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
2단계 · locator와 assertion 점검 확인은 고정 대기를 추가하기 전에 locator 한 변수만 수정하세요. 이후 대상·상태 일치 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 2단계 · locator와 assertion 점검 결과가 한 번 더 재현되는지 확인하세요.
| 실행 확인 | 대상·상태 일치 |
|---|
3단계 · trace로 readback
실패 trace에서 actions, DOM snapshot, console, network 순서로 최초 차이를 찾고 같은 테스트를 다시 실행합니다.
이 항목의 3단계 · trace로 readback 단계에서는 재시도 통과도 flaky로 기록하고 다음 실행에서 재발 여부를 확인하세요. 이때 다른 조건은 유지해야 3단계 · trace로 readback에서 생긴 차이를 분리해 확인할 수 있습니다.
실행 관점의 판정 신호는 원인과 재현 기록입니다. 3단계 · trace로 readback의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
3단계 · trace로 readback 확인은 재시도 통과도 flaky로 기록하고 다음 실행에서 재발 여부를 확인하세요. 이후 원인과 재현 기록 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 3단계 · trace로 readback 결과가 한 번 더 재현되는지 확인하세요.
| 실행 확인 | 원인과 재현 기록 |
|---|
주의점: 잘못 적용하기 쉬운 부분
Playwright 적용 전 확인과 실행 중 확인을 분리해서 보세요. 아래 항목이 맞지 않으면 범위나 재시도 횟수를 늘리지 마세요.
- 긴 CSS·XPath 경로 고정DOM 구조가 조금만 바뀌어도 다른 요소를 찾거나 테스트가 깨질 수 있습니다.
- waitForTimeout으로 증상 가리기실제 준비 상태가 아닌 시간에 의존하면 환경 속도에 따라 다시 실패합니다.
- 재시도 통과를 정상 처리첫 실행 실패 원인이 남아 있으므로 flaky 추세와 trace를 별도로 관리해야 합니다.
- 실패 후 trace 없이 재실행두 번째 실행이 통과하면 최초 오류 지점을 다시 확인할 증거가 사라집니다.
- 여러 테스트 동시 수정공용 fixture와 locator를 같이 바꾸면 어떤 변경이 안정성을 높였는지 알기 어렵습니다.
상황별 적용: 같은 기준을 다르게 쓰는 법
버튼 문구가 자주 바뀌는 경우
사용자에게 보이는 이름이 제품 계약이면 role과 name을 쓰고, 번역별 문구가 다르면 합의된 test id를 검토합니다.
Playwright 테스트의 버튼 문구가 자주 바뀌는 경우 단계에서는 팀에서 유지할 locator 계약을 하나로 정하세요. 이때 다른 조건은 유지해야 버튼 문구가 자주 바뀌는 경우에서 생긴 차이를 분리해 확인할 수 있습니다.
상황 관점의 판정 신호는 locator 계약입니다. 버튼 문구가 자주 바뀌는 경우의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
버튼 문구가 자주 바뀌는 경우 확인은 팀에서 유지할 locator 계약을 하나로 정하세요. 이후 locator 계약 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 버튼 문구가 자주 바뀌는 경우 결과가 한 번 더 재현되는지 확인하세요.
| 상황 확인 | locator 계약 |
|---|
동적 목록을 검사하는 경우
데이터 로딩이 끝나기 전에 locator.all을 읽으면 시점에 따라 다른 목록을 얻을 수 있습니다.
이 항목의 동적 목록을 검사하는 경우 단계에서는 목록이 안정되는 조건을 먼저 확인한 뒤 개수와 내용을 검증하세요. 이때 다른 조건은 유지해야 동적 목록을 검사하는 경우에서 생긴 차이를 분리해 확인할 수 있습니다.
상황 관점의 판정 신호는 목록 안정 상태입니다. 동적 목록을 검사하는 경우의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
동적 목록을 검사하는 경우 확인은 목록이 안정되는 조건을 먼저 확인한 뒤 개수와 내용을 검증하세요. 이후 목록 안정 상태 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 동적 목록을 검사하는 경우 결과가 한 번 더 재현되는지 확인하세요.
| 상황 확인 | 목록 안정 상태 |
|---|
CI에서만 실패하는 경우
해당 CI 브라우저와 프로젝트 설정, 병렬도, 테스트 데이터를 고정하고 첫 실패 trace를 로컬 결과와 비교해야 합니다.
이 항목의 CI에서만 실패하는 경우 단계에서는 환경 차이를 한 항목씩 제거하세요. 이때 다른 조건은 유지해야 CI에서만 실패하는 경우에서 생긴 차이를 분리해 확인할 수 있습니다.
상황 관점의 판정 신호는 CI 차이 분리입니다. CI에서만 실패하는 경우의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
CI에서만 실패하는 경우 확인은 환경 차이를 한 항목씩 제거하세요. 이후 CI 차이 분리 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 CI에서만 실패하는 경우 결과가 한 번 더 재현되는지 확인하세요.
| 상황 확인 | CI 차이 분리 |
|---|
근거를 읽는 방법과 확인 순서
Playwright 공식 문서는 사용자 관점의 locator와 자동 대기를 권장하고, CI 실패 분석에는 trace viewer를 사용하도록 안내합니다. 재시도 결과도 passed, flaky, failed로 구분되므로 재시도 통과를 정상 성공과 섞지 않는 것이 중요합니다.
Playwright 근거는 수치 하나를 떼어 보기보다 측정 조건, 비교 대상, 적용 범위를 함께 읽어야 합니다. 짧은 소개 문구보다 공식 문서와 실제 실행 로그를 우선하면 판단 오류를 줄일 수 있습니다.
- Playwright Locators – 사용자 관점 locator와 strict 동작 확인
- Playwright Trace Viewer – 실패 동작, DOM snapshot, network 기록 확인
Playwright locator는 어떤 순서로 선택해야 하나요?
사용자가 인식하는 role과 name을 우선하고, label과 text를 검토한 뒤 명시적 계약이 필요할 때 test id를 사용하세요.
고정 시간 대기를 넣으면 flaky가 사라지나요?
일시적으로 줄어들 수 있지만 실제 준비 상태를 보장하지 않으므로 locator의 자동 대기와 web-first assertion을 우선하세요.
trace는 모든 테스트에서 항상 켜야 하나요?
CI 비용과 저장량을 고려해 공식 권장처럼 첫 재시도나 실패 보존 조건으로 시작하고 필요한 범위만 확대하세요.
재시도에서 통과하면 배포를 진행해도 되나요?
flaky 원인을 기록하지 않은 채 정상 성공으로 간주하면 재발할 수 있으므로 핵심 경로는 원인 확인 뒤 승격하세요.
locator가 여러 요소와 일치하면 first를 써도 되나요?
목표가 정말 첫 요소인 경우가 아니라면 고유한 role, name, container 조건으로 대상을 좁히는 편이 안전합니다.
마무리: 오늘 바로 적용할 순서
Playwright 테스트 품질은 재시도 횟수보다 locator 고유성, 상태 기반 대기, 실패 trace, 환경 재현으로 높아집니다. 오늘은 흔들리는 테스트 한 건을 골라 고정 대기를 제거하고 사용자 관점 locator로 바꾼 뒤 첫 실패 trace와 재실행 결과를 함께 남기세요. 원인이 설명되고 다시 통과할 때 다음 테스트로 확장할 수 있습니다.
Playwright은 한 문장으로 단정하기보다 확인할 항목을 순서대로 나누는 것이 핵심입니다. 첫 기록을 남기고 다음번 결과와 비교하면 구매, 사용, 보관에서 같은 실수를 반복할 가능성이 낮아집니다.