종단 테스트가 처음인 개발자를 위한 Playwright 가이드 관련

Playwright > Article(s)

---

Article(s)

• 1. 개발 프로세스와 종단 테스트의 필요성
• 2. Playwright 기반 종단 테스트
• 3. Playwright가 종단 테스트에 기여하는 4가지
  • 1. 크로스 브라우저 & 멀티 OS를 폭넓게 지원
  • 2. 자동 대기(Auto-Waiting) 및 대기 전략
  • 3. 강력한 디버깅 툴: Trace Viewer, Inspector, Codegen 등
  • 4. 병렬 실행 & 빠른 성능
• 4. 실제 사례: Playwright로 종단 테스트 수행하기
  • 1. 결제 프로세스 종단 테스트
  • 2. 사례별 상세한 디버깅 방법
• 마치며

---

종단 테스트가 처음인 개발자를 위한 Playwright 가이드

제 멘티, 유남주 님이 설레는 얼굴로 다짜고짜 프론트엔드 종단(End to End, E2E) 테스트에 대해 물어 봅니다. 의욕은 넘치는데 다소 막막했는지 질문이 중구난방입니다. 그러면서도 요즘 힙한, 많이 쓰는 기술 스택이 궁금하다고 합니다. 가볍게 차근차근 알아가는 과정이 필요하겠군요. 개발 방법론과 프로세스에서 종단 테스트가 왜 필요한지부터 시작해 보겠습니다. 그다음, 제가 추천하는 도구 Playwright가 이런 종단 테스트에서 어떤 점에 특히 기여하는지 좀 더 자세히 살펴볼까요?

취업 시장만큼이나 추운 어느 날, 유남주 님이 커피챗을 신청했습니다. 유남주 님은 이력서 멘토링 이후 저와 멘토와 멘티 인연을 맺어 간간이 멘토링을 받곤 하는 백엔드 개발자입니다. 추운 날이지만, 온라인 화상 커피챗을 하러 엉거주춤 사무실에 나갑니다.

유남주 님은 설레는 얼굴로 다짜고짜 프론트엔드 종단(End to End, E2E) 테스트에 대해 물어 봅니다.

유남주 개발자(이하 유남주): 제가 프론트엔드 개발을 시작했거든요. 같이 토이 프로젝트 만들던 동료가 취업하면서 이탈하게 되어서요. 안 그래도 풀스택 개발자가 되고 싶었던 참이라 자원했어요.

의욕은 넘치는데 다소 막막했는지 질문이 중구난방입니다. 그러면서도 요즘 힙한, 많이 쓰는 기술 스택이 궁금하다고 합니다. 가볍게 차근차근 알아가는 과정이 필요하겠군요.

한날: 개발 방법론과 프로세스에서 종단 테스트가 왜 필요한지부터 시작해야겠네요. 그다음, 제가 추천하는 도구 Playwright가 이런 종단 테스트에서 어떤 점에 특히 기여하는지 좀 더 자세히 살펴볼까요?

---

1. 개발 프로세스와 종단 테스트의 필요성

소프트웨어 개발은 일반적으로 계획(Plan) > 개발(Develop) > 테스트(Test) > 배포(Deploy) > 운영(Maintenance) 단계를 거칩니다. 이 중 테스트 단계는 제품 품질을 좌우하는 단계로, 애자일(Agile)이나 스크럼(Scrum) 같은 방법론을 적용할 때 특히 중요합니다. 빠른 스프린트 주기로 기능을 구현하고, QA나 자동화 테스트로 빠르게 피드백을 얻어야 하기 때문이지요.

애자일 개발의 경우, 사용자 스토리를 스프린트마다 구현·검증합니다. 따라서 기능 단위(단위 테스트)와 모듈 단위(통합 테스트)에서 정상 동작해도 실제 사용자 관점의 흐름을 전부 점검하기는 어렵습니다. 또, CI/CD(지속적 통합/지속적 배포)는 코드가 변경될 때마다 자동 빌드·테스트·배포 파이프라인을 거칩니다. 이 과정을 모두 통과하더라도 브라우저상 실제 상호작용, 즉, 클릭, 입력, 라우팅 등이 정상인지 보장하기 어렵습니다.

종단 테스트(E2E 테스트)는 이러한 문제를 해소해 줍니다. 애플리케이션의 처음부터 끝까지, 실제 브라우저 환경에서 자동화해 확인하며 사용자 입장에서 생길 법한 치명적인 결함을 빠르게 발견할 수 있습니다. 로그인이나 결제처럼 서비스의 주요 흐름은 UI가 사소하게 변해도 큰 오류로 이어질 수 있습니다. 그런 만큼 종단 테스트로 미리 대비하는 것이 중요합니다.

---

2. Playwright 기반 종단 테스트

Playwright 로고

웹 프론트엔드를 종단 테스트할 때 사용하는 몇 가지 도구가 있습니다. 각 도구마다 장단점이 있지만, 저는 Playwright을 추천합니다.

마이크로소프트가 주도적으로 개발한 오픈소스 웹 자동화 프레임워크인 Playwright는 Chromium, Firefox, WebKit 등 다양한 브라우저를 지원합니다. 또한, Windows, Linux, MacOS 등 여러 OS에서 동일한 테스트 품질을 보장하며, 모바일 웹 환경을 시뮬레이션하는 데에도 용이합니다. 이런 장점 외에도 종단 테스트에 유용한 특성이 더 있습니다.

• 자동 대기(Auto-Waiting): 웹 페이지 로딩 시점을 자동으로 감지하여 비동기 환경에서도 안정적으로 테스트를 진행합니다.
• 독립적인 브라우저 컨텍스트: 테스트 케이스별로 세션 충돌이나 데이터 간섭을 방지합니다.
• 디버깅에 유용한 개발자 도구: Trace Viewer, Inspector 등을 이용해 복합 오류를 시각적으로 추적해 디버깅 효율을 극대화합니다.
• 병렬 실행과 성능 최적화: 여러 테스트를 동시에 수행할 수 있으나, 시스템 리소스와 충돌 로그 관리를 유의해야 합니다. 특히 종단 테스트는 대개 단위 테스트보다 시간이 오래 걸리기 때문에 테스팅 속도는 중요한 요소입니다.

애초에 유남주 님은 종단 테스트 도구로 Selenium을 염두에 두고 있었다고 합니다.

유남주: Selenium은 Python으로 웹 스크래퍼 만들 때 써봐서 익숙했거든요.

한날: 물론 Selenium은 오랜 시간 많은 사람이 사용해 왔고, 브라우저 지원도 다양하며, 참고할 자료도 무척 많다는 장점이 있어요. 기능만 보면 비슷하고요. 하지만 Playwright는 속도가 빠르고, 무엇보다 자동 대기 기능이 무척 편해요.

유남주: 자동 대기 기능이 뭐예요?

한날: 실제 서비스에서는 네트워크 지연이나 비동기 로딩이 흔하잖아요. 화면에 HTML 요소(element)가 이런 비동기 상황에 표시되길 기다리는 상황이 잦은 거죠. Playwright는 로딩 완료 시점을 인식하여 테스트를 진행하므로 안정성이 크게 향상돼요. 그런 제어를 쉽고 편리하게 다룰 수 있어요.

---

3. Playwright가 종단 테스트에 기여하는 4가지

유남주: 조금 더 궁금해요. Playwright가 다른 종단 테스트 도구보다 좋은, 차별화 지점이 뭔가요?

어느 특성 하나만으로 Playwright를 쓴다고 하기는 어렵습니다. 여러 요소가 Playwright의 매력을 완성합니다. 기능만으로는 다른 종단 테스트 도구도 지원하는 경우가 많거든요.

본격적으로 Playwright의 장점을 설명하기 앞서, 주요 테스트 도구와 그 장단점을 모아봤습니다.

1. 크로스 브라우저 & 멀티 OS를 폭넓게 지원

Playwright는 단일 API로 Chromium(Chrome/Edge), Firefox, WebKit(Safari)를 모두 테스트할 수 있으며, Windows·Linux·MacOS에서 동일하게 작동합니다.

반면, Puppeteer는 Chromium 기반 브라우저만 지원합니다. Cypress 역시 최근 크로스 브라우저 지원을 늘리고 있으나, Safari(WebKit) 같은 일부 브라우저는 여전히 지원이 제한적입니다.

Playwright는 Firefox와 WebKit도 공식 지원하므로, 다양한 사용자 환경에서 실제 호환성을 보장하는 데 유리합니다.

2. 자동 대기(Auto-Waiting) 및 대기 전략

네트워크 지연, 비동기 요청, 이미지·폰트 로딩 등으로 인해 요소가 늦게 나타날 때, Playwright는 이러한 요소가 나타날 때까지 자동으로 기다려주는 메커니즘을 탑재하고 있습니다. 이 자동 대기 기능이 많은 사람이 애호하는 특장점이지요.

물론 Selenium이나 다른 툴에서도 ‘waitFor’ 함수를 사용할 수 있지만, Playwright는 기본적으로 모든 액션에 대기 로직이 내장되어 있습니다. 그 때문에 스크립트가 간결해지고 오류가 줄어듭니다.

3. 강력한 디버깅 툴: Trace Viewer, Inspector, Codegen 등

Playwright로 테스트를 진행하며 찍은 스크린샷

Playwright는 디버깅을 위한 강력한 도구 활용도 지원합니다.

Trace Viewer는 테스트 실행 전 과정을 기록하며, 이벤트, 스크린샷, 네트워크 요청 타임라인을 재생할 수 있습니다.

Playwright Inspector는 실행하다 일시정지하고 DOM 상태를 확인하거나, 단계별로 진행하는 데 도움을 줍니다. 이를 활용하면 어느 순간 에러가 발생했는지 정확히 파악할 수 있습니다. 이벤트가 빠르거나 순서가 일관적이지 않은 상황에서 매우 유용합니다.

마지막으로 Codegen은 브라우저에서 실제로 클릭, 입력 등을 수행하면 그에 대응하는 테스트 코드를 자동으로 생성해 줍니다. 초기 스크립트를 작성하기 쉽고 편하죠. 종단 테스트에서는 반복되는 사용자 동작 코드를 작성합니다. 다만 렌더링된 UI 상으로 파악되는 UI 요소를 선택하는 경우, AI의 도움을 받기 어려운 경우가 많아 용이합니다.

4. 병렬 실행 & 빠른 성능

종단 테스트는 단위 테스트보다 실행 시간이 길 수밖에 없지만, Playwright는 병렬 실행으로 여러 테스트 케이스를 동시에 돌릴 수 있습니다. 그래서 테스트가 많아질수록 속도 면에서 보는 이득이 커집니다.

특히 소요 시간이 짧으면 짧을수록 좋은 CI/CD 파이프라인에서 스레드나 워커를 늘려 테스트 시간을 크게 단축할 수 있습니다. 그러면서 브라우저 컨텍스트를 분리해 서로 영향을 주지 않도록 설계했다는 점이 장점입니다.

물론 Cypress나 Selenium Grid도 병렬화를 지원하지만, 설정이 복잡하거나 브라우저별 세팅이 달라지는 경우가 있고, 유료 결제가 필요하기도 합니다. 반면 Playwright는 구성 파일(‘playwright.config.js’)에서 간결하게 제어가 가능합니다.

---

4. 실제 사례: Playwright로 종단 테스트 수행하기

한날: UI가 잘 바뀌지 않지만, 서비스에 있어 아주 중요해 문제가 생기면 치명적인 부분은 무엇이 있을까요?

유남주: 회원가입이요! 잘 안 바뀌니 문제를 놓치기 쉬울 것 같아요.

한날: 좋아요. 또 결제 페이지가 있죠. 종단 테스트는 손이 많이 드는, 즉, 비용이 많이 드는 테스트에요. 하지만 회원가입이나 결제 페이지는 기꺼이 비용을 감수하면서도 테스트해야 하는 곳이죠.

이처럼 종단 테스트는 비용을 감수하더라도 대가보다 가치가 훨씬 큰 곳에 적용하면 좋습니다.

1. 결제 프로세스 종단 테스트

그럼 결제 과정에 종단 테스트를 적용하는 예를 살펴보겠습니다.

A. 사용자 시나리오 구성하기

사용자는 장바구니에 상품을 담고, 결제 정보를 입력한 뒤, 결제 완료 페이지에서 주문 번호를 확인할 수 있어야 한다.

B. Playwright 테스트 시나리오 구성하기

• 홈 화면 접속 > 상품 클릭
• 장바구니 담기 버튼 클릭
• 장바구니 페이지에서 상품이 추가되었는지 확인
• 결제하기 버튼을 눌러 배송·카드 정보를 입력
• 결제 완료 페이지로 이동하고 주문 번호가 보이는지 검사

import { test, expect } from '@playwright/test';

test('e커머스 결제 프로세스 종단 테스트', async ({ page }) => {
  // 홈 화면 접근
  await page.goto('https://puddingcamp.com/commerce');

  // 상품 클릭
  await page.getByText('신제품 커피머신').click();

  // 장바구니 담기
  await page.getByRole('button', { name: '장바구니 담기' }).click();

  // 장바구니 페이지로 이동
  await page.goto('https://puddingcamp.com/cart');
  await expect(page.getByText('신제품 커피머신')).toBeVisible();

  // 결제 진행
  await page.getByRole('button', { name: '결제하기' }).click();
  await page.getByLabel('주소').fill('서울시 종로구 1');
  await page.getByLabel('카드번호').fill('1234 5678 9012 3456');
  await page.getByRole('button', { name: '결제 완료' }).click();

  // 결제 완료 페이지 확인
  await expect(page).toHaveURL(/checkout\/complete/);
  await expect(page.getByText('주문 번호')).toBeVisible();
});

Note

코드의 page 객체를 비롯한 자세한 API 활용법은 직접 공식 문서를 보고 확인하는 편이 좋아요. 아니면, 제가 뉴스레터에 발행한 Playwright를 활용한 종단 테스트 맛보기 글을 읽어 보세요.

이 테스트가 성공하면, 핵심 사용자 흐름, 그러니까 장바구니 > 결제 > 완료 과정이 정상임을 보장받을 수 있습니다. 만약 실패했다면, CI/CD 파이프라인에서 배포를 차단해 치명적 결함을 사전에 해결해야 합니다.

2. 사례별 상세한 디버깅 방법

유남주: 테스트 코드 설명 글만 봐서는 실제 코드 짜는 것이 무척 막막했는데, 실제로 테스트 코드를 작성해 보니 비로소 이해할 수 있었어요. 이제 디버깅은 어떻게 하는지도 궁금해요.

한날: 사용 방법보다 더 까다로운 걸 요구하며 지식을 뽑아내려 하는군요. 훌륭한 자세입니다. 몇 가지 문제 현상과 원인, 그 해결 절차를 알려 드릴게요.

A. 결제 완료 페이지 로딩 지연

• 현상: 결제 버튼을 눌렀으나, 페이지가 뜨지 않고 타임아웃이 발생
• 원인: 서버 지연, 네트워크 이슈, 결제 API 오류 등
• 해결 절차:

1. 트레이스(Trace) 기능으로 전체 과정을 기록
2. Trace Viewer에서 클릭해 HTTP 요청/응답 상태를 상세히 살핌
3. 응답 코드(200/500 등)에 따라 서버 로그나 APM 모니터링 결과를 확인
4. 타임아웃 옵션 확대, 혹은 API 개선을 통해 로딩 시간을 단축

B. 장바구니 담기 버튼 미작동

• 현상: 버튼 클릭 후 아무 반응이 없거나 실패 알림 발생
• 원인: 클릭 이벤트 미설정, CSS나 DOM 구조 변경으로 인한 셀렉터 불일치
• 해결 절차:

1. Playwiright의 debug 명령으로 Inspector 활성화, 단계별 실행 확인
2. 요소가 존재하지 않거나 ‘element is not attached to the DOM’ 에러 확인
3. 시맨틱 셀렉터(‘getByRole’, ‘getByText’)를 사용해 변경에 견고하도록 코드 리팩터링

C. 환경 차이로 인한 실패 (로컬 vs CI)

• 현상: 로컬에선 통과하지만 CI에서만 실패
• 원인: 브라우저 버전, 폰트, 환경 변수 등이 달라 리소스를 찾지 못함
• 해결 절차:

1. pnpx playwright show-report 등으로 CI 리포트를 확인
2. Docker 컨테이너 등으로 브라우저/OS 버전을 표준화
3. console.log나 스크린샷 옵션으로 UI를 비교, 환경 설정 파일 동기화

D. UI 개편으로 인한 셀렉터 붕괴

• 현상: 디자이너가 CSS 클래스나 레이아웃을 변경한 뒤, 기존 테스트가 무더기로 실패
• 원인: 하드코딩한 CSS 셀렉터가 달라져 버튼을 못 찾음
• 해결 절차:

1. 실패 시점의 스크린샷이나 DOM 구조 확인
2. getByText(‘장바구니 담기’) 등 ARIA 기반 테스트로 변경
3. 디자이너와 협의해 ARIA 라벨, 고유 텍스트 유지 정책 수립

---

마치며

현대 소프트웨어 개발에서 종단 테스트는 사용자 관점으로 애플리케이션을 철저히 검증하는 중요한 단계입니다. 특히 애자일과 CI/CD가 강조되는 환경에서, 핵심 사용자 흐름이 깨지는지 조기에 확인해 주는 종단 테스트는 필수적이라 할 수 있습니다. 개발 프로세스에 미치는 영향이 정말 크지요.

물론 한계도 있습니다. 종단 테스트가 지나치게 많으면 유지보수가 어렵습니다. 단순 UI 스타일이 아니라 UX나 UI 구조가 바뀌면 테스트에 실패할 가능성이 크지요. 게다가 단위 테스트나 통합 테스트에 비해 속도도 느립니다. 서버와 협업해야 하는 부분도 여럿 있고요.

그래도 Playwright를 활용하면, 편의성과 속도, 만족스러운 기능을 제공해 이러한 종단 테스트의 한계와 단점을 극복하는 데 도움을 줍니다.

---

유남주: 종단 테스트가 정말 막막했는데, 꼭 해봐야겠어요. 감사합니다. 그런데 결국 종단 테스트 과정은 PM, 디자이너와 협업할 때도 꼭 필요한 과정 같아요. 혹시 사례나 경험이 있으신가요? 아니면 아이디어를 떠올릴 영감이나 키워드도 좋고요!

훌륭합니다. 다음 글에서는 다른 직군과 협업하거나 종단 테스트를 다른 방법으로 응용하는 이야기를 나눠야겠습니다.

종단 테스트가 처음인 개발자를 위한 Playwright 가이드

---

제 멘티, 유남주 님이 설레는 얼굴로 다짜고짜 프론트엔드 종단(End to End, E2E) 테스트에 대해 물어 봅니다. 의욕은 넘치는데 다소 막막했는지 질문이 중구난방입니다. 그러면서도 요즘 힙한, 많이 쓰는 기술 스택이 궁금하다고 합니다. 가볍게 차근차근 알아가는 과정이 필요하겠군요. 개발 방법론과 프로세스에서 종단 테스트가 왜 필요한지부터 시작해 보겠습니다. 그다음, 제가 추천하는 도구 Playwright가 이런 종단 테스트에서 어떤 점에 특히 기여하는지 좀 더 자세히 살펴볼까요?