「CI에서만 테스트가 실패하는데, 로그만으로는 원인을 알 수 없다」——Playwright에는 이런 고민을 해결해주는 강력한 기능, Trace Viewer가 있습니다. 테스트 실행 시의 조작・스크린샷・네트워크 통신・콘솔 로그를 하나의 파일에 기록해두고, 나중에 브라우저에서 trace.zip을 “재생”해서 확인할 수 있습니다. 이 글에서는 Trace Viewer의 기록 설정부터 화면 보는 법, 실전적인 디버깅 흐름까지 소개합니다.
테스트가 실패했을 때 「다시 실행해서 재현되길 기도하는」 상태에서 벗어날 수 있게 해주는 것이 Trace Viewer입니다. 사용법을 한 번 익혀두면 원인 조사에 걸리는 시간이 크게 달라집니다.
📌 이런 분께 추천합니다
- Playwright 테스트가 실패했을 때, 로그만으로 원인을 추측하느라 고생하는 분
- Trace Viewer라는 기능의 이름은 알지만 사용법을 잘 모르는 분
- CI 환경에서 실패한 테스트의 원인을, 로컬에서 재현하지 못해 곤란한 분
- Trace Viewer 화면의 각 패널이 무엇을 보여주는지 정리하고 싶은 분
✅ 이 글을 읽으면 얻을 수 있는 것
- Trace를 기록하기 위한 설정 방법과 각 옵션의 차이를 알 수 있다
- Trace Viewer의 화면 구성(Actions・Timeline・Snapshots 등)을 보는 법을 알 수 있다
- 실제로 테스트가 실패했을 때 조사를 진행하는 방법을 구체적으로 그려볼 수 있다
👤 이 글을 쓴 사람
QA 엔지니어·테스트 자동화 엔지니어로 15년 이상의 실무 경험을 가진 Yoshi가 작성했습니다. Playwright를 활용한 테스트 기반 구축·운용 과정에서 Trace Viewer를 일상적인 원인 조사 도구로 활용하고 있습니다.
📌 결론
- Trace Viewer는 테스트 실행 중의 조작・스크린샷・네트워크・콘솔을 하나의 파일에 기록해, 나중에 상세히 확인할 수 있는 기능
- 기록 설정(on/off/retain-on-failure 등)을 목적에 맞게 선택하면 필요한 정보만 효율적으로 남길 수 있다
- trace.playwright.dev를 사용하면 설치 없이 브라우저에서 trace.zip을 열어 확인할 수 있다
Playwright 테스트가 실패했을 때, 많은 경우 다음과 같은 상황에 부딪힙니다.
- 에러 메시지만으로는 실제로 화면이 어떤 상태였는지 알 수 없다
- 로컬에서는 재현되지 않고 CI 환경에서만 발생한다
- 스크린샷은 찍혀 있지만, 실패 직전의 일련의 조작 흐름이 보이지 않는다
Trace Viewer는 이런 상황을 해결하기 위해 Playwright에 내장된 기능입니다. 이 글에서는 설정 방법부터 실제 사용법까지 순서대로 살펴봅니다.
Trace Viewer란 무엇인가
Trace Viewer는 Playwright 테스트 실행 중에 발생하는 다음 정보를 하나의 ZIP 파일(trace.zip)로 정리해 기록하는 기능입니다.
- 실행된 각 액션(click・fill・goto 등)의 목록
- 각 액션 전후의 DOM 스냅샷(화면의 모습을 재현할 수 있음)
- 네트워크 요청・응답 로그
- 콘솔 로그(JS 에러 등)
- 각 액션이 호출된 테스트 코드의 줄
이러한 정보를 기록해두면, 테스트 실행 후에 브라우저에서 「무슨 일이 일어났는지」를 시간 순서에 따라 상세히 확인할 수 있습니다.
① Trace 기록하기: 설정 옵션
Trace는 항상 기록되는 것이 아니라 명시적으로 설정해야 합니다. pytest-playwright를 사용하는 경우 --tracing 옵션으로 동작을 지정합니다.
# 실패한 테스트만 Trace를 저장한다（가장 일반적인 사용법）
pytest --tracing retain-on-failure
# 모든 테스트에서 항상 Trace를 저장한다
pytest --tracing on
# Trace를 저장하지 않는다（기본값）
pytest --tracing off| 설정 | 동작 | 적합한 상황 |
|---|---|---|
off | 기록하지 않음（기본값） | 일반 실행・CI 속도를 우선하고 싶은 경우 |
retain-on-failure | 실패한 테스트만 저장하고, 성공한 테스트의 기록은 폐기 | CI 환경에서의 표준적인 운용（추천） |
on | 성공・실패 관계없이 모든 테스트를 기록 | 새로운 테스트를 작성 중이라 동작을 세밀하게 확인하고 싶을 때 |
pip install pytest-playwright）을 사용하는 경우의 예입니다. 표준 pytest 커맨드에는 --tracing 옵션이 없습니다. 지정 가능한 값이나 옵션명은 플러그인 버전에 따라 달라질 수 있으므로, 최신 정보는 공식 문서를 확인하는 것을 추천합니다.--tracing on을 CI 설정에 상시 켜두면, 테스트가 늘어남에 따라 Trace 파일의 저장 용량이 불어나 CI의 아티팩트 용량을 압박할 수 있습니다. 특별한 이유가 없다면 CI 환경에서는 retain-on-failure를 기본 설정으로 해두는 것이 무난합니다.② Trace Viewer 여는 방법
기록된 trace.zip을 여는 방법은 크게 두 가지입니다.
방법 1：커맨드라인에서 열기
playwright show-trace trace.zip이 명령을 실행하면 로컬에서 뷰어가 실행되어, 브라우저에서 Trace Viewer 화면이 열립니다.
방법 2：trace.playwright.dev에 드래그 앤 드롭하기
trace.playwright.dev는 Playwright 공식이 제공하는 온라인 Trace Viewer입니다. trace.zip 파일을 브라우저에 드래그 앤 드롭하기만 하면, 설치 없이 내용을 확인할 수 있습니다.
③ 화면 보는 법
Trace Viewer 화면은 여러 패널로 나뉘어 있습니다. 각각이 보여주는 정보를 이해해두면 조사가 원활해집니다.
| 패널 | 확인할 수 있는 내용 |
|---|---|
| Actions（왼쪽 목록） | 실행된 조작（click・fill・goto 등）이 시간 순서로 나열된 목록. 클릭하면 그 시점의 상태로 이동할 수 있다 |
| Timeline（상단） | 테스트 전체의 흐름을 시각적인 타임라인으로 표시. 특정 구간을 클릭해 그 시점으로 이동할 수 있다 |
| Snapshots（Before/Action/After） | 선택한 액션의 「실행 전」 「실행 중」 「실행 후」 화면 상태를 각각 확인할 수 있다 |
| Network | 발생한 네트워크 요청과 응답의 목록・상세 정보 |
| Console | 브라우저 콘솔에 출력된 로그・에러 |
| Source | 선택한 액션에 대응하는 테스트 코드의 해당 줄 |
| Call | 선택한 액션에 전달된 구체적인 파라미터와 실행 결과 |
④ 실전 디버깅 흐름
실제로 테스트가 실패했을 때, Trace Viewer를 사용해 어떻게 조사를 진행하는지 구체적인 절차의 예시입니다.
- Actions 목록의 맨 아래（빨갛게 표시된 실패 지점）를 확인한다——어느 액션에서 실패했는지 특정한다
- 실패한 액션의 Snapshots（Before/After）를 본다——예상했던 요소가 정말로 존재하지 않았는지, 아니면 다른 이유인지 확인한다
- Network 탭에서 직전의 API 통신을 확인한다——예상보다 응답이 느리거나, 에러 응답이 돌아오는 등 비동기 처리 문제가 없는지 본다
- Console 탭을 확인한다——JS 에러가 조작을 방해하지 않았는지 확인한다
- Source 탭에서 해당 테스트 코드를 확인한다——로케이터나 대기 조건이 애초에 적절했는지 재검토한다
⑤ CI 환경에서의 Trace 활용
CI 환경에서는 테스트가 실패해도 그 자리에서 Trace Viewer를 열 수 없습니다. Trace 파일을 아티팩트로 저장해두고 나중에 다운로드해서 확인하는 운용이 기본이 됩니다.
GitHub Actions 설정 예시
- name: Run Playwright tests
run: pytest --tracing retain-on-failure
- name: Upload trace
if: failure()
uses: actions/upload-artifact@v4
with:
name: playwright-traces
path: test-resultstest-results는 pytest-playwright의 기본 저장 경로입니다. 프로젝트에서 출력 경로를 변경한 경우, 실제로 사용 중인 디렉터리를 지정해 주세요. 이 부분이 일치하지 않으면 테스트는 실패했는데 Artifacts는 비어 있는 상태가 되어버립니다.이 설정을 통해 테스트가 실패한 경우에만 Trace가 GitHub Actions의 아티팩트로 저장됩니다. 다운로드 후에는 다음 중 하나의 방법으로 확인할 수 있습니다.
- 로컬에 다운로드해서
playwright show-trace trace.zip으로 연다 - trace.playwright.dev에 드래그 앤 드롭해서 연다（설치 불필요）
실무에서 자주 발생하는 실수
① Trace 설정을 잊어버려 실패해도 아무것도 기록되지 않는다
모처럼 CI에서 테스트가 실패해도 --tracing 옵션을 설정하지 않으면 조사 자료가 전혀 남지 않습니다. CI 설정 초기 단계부터 retain-on-failure를 포함시켜두는 것을 추천합니다.
② Actions 목록만 보고 Network・Console 탭을 확인하지 않고 끝낸다
화면의 겉모습만으로 판단하면 비동기 처리 지연이나 JS 에러가 원인인 경우를 놓치기 쉽습니다. 원인을 모를수록 Network・Console 탭까지 한 번씩 확인하는 습관을 들이세요.
③ CI 환경에서 --tracing on을 계속 사용해 아티팩트 용량을 압박한다
개발 초기 검증 목적으로 사용하던 on을 그대로 본 운용까지 가져가 버리는 경우입니다. Trace는 스크린샷과 스냅샷을 포함하므로 용량이 커지기 쉬워, CI의 아티팩트 저장 용량이나 비용에 영향을 줄 수 있습니다. 운용이 안정되면 retain-on-failure로 전환하는 것을 추천합니다.
④ 로컬에서 재현되지 않는다는 이유로 Trace 조사를 미룬다
「로컬에서 재현이 안 되니까 나중에 봐도 되겠지」라며 CI 실패를 방치하면 원인이 쌓여갑니다. Trace가 있으면 로컬에서 재현되지 않아도 실제로 일어난 상황을 확인할 수 있으므로, 미루지 말고 그 자리에서 조사하는 습관을 들이면 원인 파악이 빨라집니다.
📖 관련 글
FAQ
Q. Trace 파일은 어느 정도 용량이 되나요？
테스트의 길이나 페이지의 복잡도에 따라 크게 달라집니다. 스크린샷과 DOM 스냅샷을 다수 포함하므로 몇 MB에서 수십 MB 정도가 될 수 있습니다. 용량이 걱정된다면 retain-on-failure를 사용해 실패 시에만 저장하는 운용으로 억제할 수 있습니다.
Q. Trace Viewer와 Playwright Inspector（디버그 모드）는 무엇이 다른가요？
Playwright Inspector는 테스트 실행 중에 실시간으로 단계별 실행을 하며 디버깅하기 위한 도구입니다. 반면 Trace Viewer는 이미 완료된 테스트 실행 기록을 나중에 돌아보며 확인하기 위한 도구라는 차이가 있습니다. 목적에 따라 구분해서 사용합니다.
Q. 성공한 테스트의 Trace도 볼 의미가 있나요？
있습니다. 새로운 테스트를 작성하고 있을 때, 예상대로 조작이 이루어지고 있는지 확인하는 용도로 유용합니다. 다만 상시 기록하면 용량이 늘어나므로, 테스트 작성 중에는 on, 안정적으로 운용된 후에는 retain-on-failure처럼 구분해서 사용하는 것이 좋습니다.
Q. trace.playwright.dev에 업로드한 파일은 외부로 전송되나요？
trace.playwright.dev는 브라우저 안에서 파일을 처리하는 방식을 채택하고 있습니다. 다만 민감한 데이터를 다루는 경우, 만약을 위해 공식 문서에서 구체적인 처리 방식을 확인하고, 필요하다면 로컬의 playwright show-trace 명령을 사용하는 편이 안심할 수 있습니다.
Q. retain-on-failure와 retain-on-first-failure는 무엇이 다른가요？
retain-on-failure는 재시도를 포함해 최종적으로 실패한 테스트의 Trace를 저장합니다. 반면 retain-on-first-failure는 재시도 설정이 있는 경우 「최초로 실패한 시점」의 Trace만 저장하는 동작입니다. 재시도 후 성공한 테스트라도 처음에 왜 실패했는지 확인하고 싶을 때 구분해서 사용합니다. 구체적인 동작은 버전에 따라 달라질 수 있으므로 사용 전에 공식 문서에서 확인하는 것을 추천합니다.
Q. Selenium에도 Trace Viewer 같은 기능이 있나요？
Selenium에는 Playwright의 Trace Viewer에 해당하는 표준 기능이 없습니다. Selenium에서의 원인 조사는 스크린샷 수동 취득이나 브라우저 로그 확인, 외부 도구와의 조합이 중심이 됩니다. 이 차이도 Playwright와 Selenium을 비교할 때 자주 언급되는 포인트 중 하나입니다.
📋 정리
- Trace Viewer는 조작・스크린샷・네트워크・콘솔을 하나의 파일에 기록해, 나중에 상세히 확인할 수 있는 기능
- CI 환경에서는 retain-on-failure를 기본으로 해서 실패 시에만 기록함으로써 용량과의 균형을 잡는다
- 조사의 기본은 Actions 목록에서 실패 지점 특정 → 전후의 Snapshots 비교 → Network/Console도 확인하는 흐름
- trace.playwright.dev를 사용하면 설치 없이 팀원과도 쉽게 공유・확인할 수 있다
Trace Viewer는 사용법을 한 번 익혀두면 「테스트가 왜 실패했는지 모르겠다」는 상황에 걸리는 시간을 크게 줄여주는 도구입니다. 먼저 CI 설정에 --tracing retain-on-failure를 추가하는 것부터 시작해보세요.
