12.4 Troubleshooting Decision Tree
Test가 timeout됐다
어디에서 timeout?
├─ locator action
│ ├─ 0개 match → accessible name/route/iframe 확인
│ ├─ 여러 match → scope, strictness 확인
│ └─ 1개 match → visible/stable/receives-events/enabled 확인
├─ assertion
│ ├─ 값이 끝내 안 바뀜 → product/network state 확인
│ └─ 잠깐 맞았다 바뀜 → race, state transition 확인
├─ navigation/event
│ ├─ event promise를 action 전에 만들었는가?
│ └─ lifecycle 대신 product readiness를 기다려야 하는가?
└─ test 전체
├─ setup/fixture가 budget을 소모했는가?
└─ 실제 performance regression인가?
Local은 통과하고 CI만 실패한다
- Playwright와 browser version 비교
- OS/font/timezone/locale 비교
- Worker 수와 shared data 충돌 확인
- Headless/headed 차이 확인
- CPU, memory 제약과 server readiness 확인
- CI trace, screenshot, video, console, server log 연결
특정 browser만 실패한다
- 제품의 browser support requirement인지 확인
- Browser engine별 native control/permission/media 차이 확인
- User agent 분기와 polyfill 확인
- Unsupported API를 conditional skip하기 전에 product fallback 확인
- Playwright release note와 known issue 확인
Network mock이 적용되지 않는다
- Glob이 전체 URL과 match하는가?
- Route를 navigation 전에 등록했는가?
- Service worker가 request를 가로채는가?
- Page route와 context route 중 올바른 scope인가?
- HAR URL/filter가 실제 query와 일치하는가?
Visual diff가 대량 발생한다
- Baseline 생성 OS와 current OS 비교
- Browser version과 font 설치 확인
- Viewport, DPR, color scheme 확인
- Animation, caret, timestamp 고정
- API data와 random order 고정
- 실제 CSS/theme change 여부 확인
Auth state가 작동하지 않는다
- State file path가 project cwd 기준으로 맞는가?
- Cookie domain, secure, sameSite가 target URL과 맞는가?
- Session이 server-side에서 만료됐는가?
- Setup project가 main project dependency인가?
- Worker가 shared account state를 서로 변경했는가?
최소 재현 만들기
- Test 하나, project 하나, worker 하나
- 외부 dependency를 하나씩 제거
- Page object를 임시로 펼쳐 raw locator 확인
- Trace on으로 최초 failure 보존
- 제품 log와 correlation ID 기록
문제를 해결한 뒤 timeout을 되돌리고 원인, 증거, 재발 방지를 runbook에 남깁니다.