npx playwright test --ui 가 브라우저 윈도우 안에 데스크탑 앱 같은 대시보드 열어. 왼쪽 패널이 suite 의 모든 테스트 나열; 하나 클릭하면 돌고, 작은 임베디드 브라우저에서 실행되는 거 라이브로 보고, 액션 타임라인 스크럽하고, 어느 순간이든 DOM inspect. 라이브 디버깅 루프의 코드화.
설치 값어치하는 기능들:
Watch 모드 — UI 모드가 소스 파일 바뀌면 테스트 자동 re-run. Spec 편집, save, 새 run 즉시 봐.
Pick locator — 임베디드 프리뷰의 어느 DOM element 든 hover, 추천 Playwright selector 얻기.
Time-travel 스크러빙 — 테스트 액션 타임라인 슬라이드; 프리뷰가 그 순간의 DOM 보여주고, 네트워크 패널이 진행 중 요청 보여주고, 콘솔이 로그 보여줘.
상태 필터 — 실패 / flaky / 통과만 보기, project 나 tag 별 필터.
Trace Viewer — 포렌식 도구
테스트 실패하면 Playwright (trace 활성화돼 있으면) 모든 거 기록: 모든 액션, before/after DOM 스냅샷, 네트워크 요청, 콘솔 메시지, 스크린샷, 테스트 소스 라인, 에러 스택 트레이스. 패키지는 test-results/ 안 .zip. npx playwright show-trace path/to/trace.zip — 또는 trace.playwright.dev 에 떨궈 — 로 열어, 그럼 Live 모드와 같은 UI 얻는데 과거 run 에 대해.
킬러 use case 는 CI 실패. 테스트가 CI 에서 실패, 터미널이 "Locator expected to be visible, was hidden" 하고, 로컬에서 재현 못 해. CI run 에서 trace artifact 다운로드, 열고, 실패로 스크럽, 그 정확한 순간의 실제 DOM 봐 — 보통 즉시 뭐가 달랐는지 말해줘 (안 닫힌 모달, 타이밍 이슈, i18n 때문에 다른 카피).
항상 first retry 에 trace 활성화. Config 의 `use: { trace: 'on-first-retry' }` 가 이유 있는 default — 성공엔 오버헤드 zero, 실패엔 풀 포렌식. 사소한 디스크 공간 비용은 그게 절약하는 디버깅 시간에 비하면 아무것도 아냐.
Trace 가 보여주는 것
액션 타임라인 — 모든 클릭, fill, 대기, 타이밍과.
DOM 스냅샷 — 각 액션의 before/after, 인터랙티브 (단지 보는 게 아니라 inspect 가능).
네트워크 패널 — 모든 요청, 메서드, status, response. 실패로 필터.
콘솔 패널 — 페이지의 모든 console.log/warn/error.
소스 패널 — 현재 라인 하이라이트된 너의 테스트 코드.
에러 — 풀 스택 트레이스와 함께 실패.
Trace 공유
.zip 은 self-contained. CI artifact 로 업로드, 버그 리포트에 첨부, 팀원에게 보내 — 같은 도구로 열면 네가 본 거 정확히 봐. 'works on my machine' 논쟁 없음.
스크린샷과 비디오 — 선택적 더 가벼운 기록
Trace 는 무거워 (실패당 multi-MB). 더 가벼운 실패 기록엔 use 에 screenshot: 'only-on-failure' 와 video: 'retain-on-failure' 활성화. 각각 final-state 스크린샷과 run 의 비디오 제공. Trace 보다 detail 적지만, 파일 더 작고 흘끔 보기 더 빠름.
Code
UI 모드 + trace viewer 명령·bash
# UI mode — the local dashboard
npx playwright test --ui
# Open a trace file you already have
npx playwright show-trace test-results/<test-name>/trace.zip
# Open a trace file from a downloaded CI artifact
npx playwright show-trace ~/Downloads/playwright-report/data/<hash>.zip
Trace config — default, always-on, 수동·typescript
// Capture-on-first-retry — the default sweet spot
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
trace: 'on-first-retry', // capture once on retry, never on success
screenshot: 'only-on-failure', // final-state screenshot on failure
video: 'retain-on-failure', // video of the failed run
},
});
// Always-on tracing (for hard-to-reproduce flakes — disable after diagnosis)
export default defineConfig({
use: {
trace: 'on', // overhead, but every run has a trace
},
});
// Per-test trace forcing (when you only need it for one diagnostic run)
import { test } from '@playwright/test';
test('flaky integration test', async ({ page }) => {
await page.context().tracing.start({ screenshots: true, snapshots: true });
// ... test body
await page.context().tracing.stop({ path: 'manual-trace.zip' });
});
CI trace artifact — 업로드 + 회수·yaml
# CI — upload trace artifacts so you can open them after a failure
- uses: actions/upload-artifact@v4
if: ${{ !cancelled() }}
with:
name: playwright-report
path: playwright-report/
retention-days: 30
# Download from CI:
# 1. Open the failed run in Actions
# 2. Scroll to 'Artifacts' at the bottom
# 3. Download playwright-report.zip
# 4. Unzip, find trace.zip inside
# 5. npx playwright show-trace <path>
Trace viewer 레이아웃 모양·text
Trace viewer panels — what each shows:
┌──────────────────────────────────────────────────────┐
│ Timeline (top) │
│ ●──●──●──●──●──❌ ← scrub between actions │
│ │
│ ┌─────────────────────┐ ┌──────────────────────┐ │
│ │ DOM Preview (left) │ │ Source (right) │ │
│ │ Interactive snapshot │ │ Your test code │ │
│ │ at the selected time │ │ Current line highlight│ │
│ └─────────────────────┘ └──────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Tabs: Actions | Console | Network | Errors │ │
│ │ │ │
│ │ Network: GET /api/users 200 (124ms) │ │
│ │ POST /api/login 503 ← cause of failure │ │
│ └─────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘
테스트 suite 를 UI 모드 (npx playwright test --ui) 로 돌려. 테스트 리스트에 클릭, 하나 돌리고, 실행 보기. 이제 일부러 테스트 깨 (단언에서 틀린 텍스트), 다시 돌리고, 타임라인 스크러버로 현실이 기대에서 발산한 정확한 액션 찾기. test-results/ 의 .zip 에 trace viewer 별도로 열어서 같은 포렌식 뷰 얻는지 확인.
Hint
UI 모드가 'No tests found' 보이면 testDir 설정이 실제 테스트 사는 곳과 매칭 안 되는 거. npx playwright test --list 의 터미널 출력이 resolved 테스트 path 보여줘 — 빠른 sanity 체크.
Progress
Progress is local-only — sign in to sync across devices.