콘텐츠로 이동

클로드 코드와 Playwright로 E2E 테스트 만들기: 세 프로젝트의 실제 구성과 Test Agents를 붙일 자리

E2E(End-to-End) 테스트는 클로드 코드(Claude Code)에게 맡기기 좋은 일처럼 보입니다. 화면을 열고, 누르고, 결과를 확인하는 코드는 모양이 단순하고 반복적이기 때문입니다. 실제로 맡겨 보면 어려운 부분은 다른 곳에 있었습니다. 무엇을 테스트할지 정하는 일과 테스트가 찾아낸 것을 어떻게 처리할지 정하는 일입니다. 이 글은 직접 운영하는 프로젝트에서 클로드 코드와 함께 만든 E2E 테스트 네 가지를 실제 설정 파일과 발견 기록으로 정리하고, Playwright가 공식으로 내놓은 Test Agents를 그 위 어디에 붙이면 좋을지 따져 본 기록입니다.

이 글의 기준

2026년 1월에 올린 같은 주제의 글은 유튜브 영상 한 편을 요약한 것이었습니다. 2026-10-24에 직접 운영 중인 프로젝트의 테스트 코드·커밋·백로그를 근거로 전면 다시 썼습니다. 아래 사례의 테스트는 Playwright Test Agents 없이 클로드 코드와 함께 작성한 것이고, Test Agents의 동작은 Playwright 공식 문서를 기준으로 설명합니다.

1. E2E가 지키는 범위: 화면과 API 사이의 약속

E2E 테스트를 언제 쓰는지부터 정리합니다. 개인 위키의 Java 실습 과제(도서 대여 서비스)에서는 테스트를 세 층으로 나눴습니다.

테스트 도구 무엇을 띄우나 무엇을 지키나 개수
API 테스트 JUnit + MockMvc Spring 컨텍스트 업무 규칙·상태 코드 11
화면 테스트 Vitest + Testing Library jsdom + 목업 화면 동작·안내 문구 9
E2E 테스트 Playwright 실제 브라우저 + 두 서버 화면과 API의 약속 3

화면 테스트는 목업이 서버와 같다고 가정하고, API 테스트는 화면이 무엇을 부르는지 모릅니다. 서버가 응답 필드 이름을 바꾸는 식의 어긋남은 E2E만 잡습니다. 그래서 E2E는 많이 쓰는 테스트가 아니라 두 층 사이의 틈을 막는 소수의 테스트입니다. 이 실습에서는 대출 → 중복 대출 409 → 반납 흐름을 테스트로 만들고, 마지막에 반납까지 해서 몇 번을 다시 돌려도 같은 결과가 나오게 했습니다.

교훈: 에이전트에게 "E2E 테스트 짜 줘"라고 하기 전에, 단위 테스트가 지키지 못하는 약속이 무엇인지 먼저 적어 줘야 합니다.

2. 사례 1 — 전 화면 순회 점검과 401 여덟 건

정책 정보 수집 서비스(on-pocket-news)에는 2026-03-20에 클로드 코드와 함께 넣은 tests/ui/inspect.spec.ts가 있습니다. 시나리오를 검증하는 테스트가 아니라 모든 화면을 한 번씩 열어 이상 신호를 모으는 점검기입니다. 메인·로그인·회원가입과 관리 화면 6개, 모두 9개 경로를 순회하며 콘솔 오류, 네트워크 오류, 빈 화면, 깨진 이미지, API 실패를 기록하고 스크린샷과 report.json, summary.md를 남깁니다. make ui-inspect 한 번이면 점검이 끝난 뒤 update-backlog.ts가 발견 이슈를 백로그에 자동으로 추가합니다.

첫 실행 결과는 HIGH 0건, MEDIUM 8건이었습니다. 여덟 건이 모두 메인 화면의 401 응답이었고, 원인은 하나였습니다. 로그인하지 않은 사용자에게도 /api/v1/auth/me와 추천 API를 호출하고 있었습니다. 같은 날 "토큰이 없으면 추천 API 호출을 건너뛴다"는 수정(커밋 2d5c685)으로 닫았습니다.

교훈: 점검기가 보고한 건수와 실제 결함 수는 다릅니다. 여덟 줄이 한 원인일 수 있으므로, 결과를 백로그에 넣기 전에 원인으로 묶는 단계가 필요합니다.

3. 사례 2 — 화면 하나를 깊게 보는 스펙

같은 날 회원가입 화면만 깊게 보는 signup-deep.spec.ts도 만들었습니다. 입력 필드 목록을 뽑고, required 속성 유무를 세고, 빈 폼을 제출해 보고, 그동안 오간 API 호출을 모두 기록합니다. 이 스펙이 남긴 기록으로 백로그에 회원가입 개선 항목 여섯 개가 올라갔습니다. 주요 항목은 다음과 같습니다.

발견 처리
자녀를 한 명만 입력할 수 있음 자녀 목록 모델로 확장(커밋 8aa3e3c)
제출 후 이동도 안내도 없음 성공 시 로그인 화면 이동, 실패 시 오류 표시
입력 필드 13개 모두 required 없음 성명·이메일·비밀번호에 적용
비밀번호 확인 필드·이메일 중복 확인 없음 백로그에서 "이미 적용됨"으로 닫힘

마지막 줄처럼 일부 항목은 고치러 갔을 때 이미 반영되어 있었습니다. 자동 점검의 지적은 할 일 목록의 초안이지 확정된 결함 목록이 아닙니다.

교훈: 넓게 훑는 스펙과 깊게 보는 스펙은 역할이 다릅니다. 넓은 스펙으로 어디가 아픈지 찾고, 깊은 스펙으로 그 화면의 결함을 구체화합니다.

4. 사례 3 — 로그인 없이 확인할 수 있는 것부터

블로그 자동화 도구(blogger-daemon)의 E2E는 작습니다. 테스트 파일 하나에 테스트 두 개입니다. 로그인하지 않은 사용자가 모바일 발행 화면에 들어가면 로그인 화면으로 보내지는지, 그리고 로그인 화면이 iPhone 13 폭에서 입력란과 버튼을 모두 보여 주는지만 확인합니다. 설정에서 눈여겨볼 부분은 테스트가 개발 서버를 직접 띄운다는 점입니다.

// blogger-daemon/playwright.config.ts (요약)
export default defineConfig({
  testDir: './e2e',
  fullyParallel: false,
  use: { baseURL: 'http://127.0.0.1:4173' },
  webServer: {
    command: 'pnpm vite --host 127.0.0.1 --port 4173',
    url: 'http://127.0.0.1:4173',
    reuseExistingServer: true,
  },
  projects: [{ name: 'mobile-chromium', use: { browserName: 'chromium', ...devices['iPhone 13'] } }],
});

webServer가 있으면 에이전트가 "서버를 먼저 띄워야 하나?"를 판단할 필요가 없습니다. test:e2e 스크립트(playwright test) 하나가 서버 기동과 테스트를 함께 책임집니다.

교훈: 에이전트에게 맡길 테스트일수록 실행 전제(서버, 포트, 기기 크기)를 설정 파일에 넣어 두면 판정이 명령 하나로 끝납니다.

5. 사례 4 — 테스트가 다 통과했는데 화면은 밀려 있었다

운동 기록 앱(workout-history)은 Flutter라 Playwright 대신 integration_test와 위젯 테스트를 씁니다. 도구는 다르지만 자동 테스트의 한계를 가장 분명하게 보여 준 사례라 함께 적습니다. 2026-09-25, 실기기에서 첫 실행 위저드의 "텍스트 밀림"이 보였다는 보고를 받고 점검했습니다. 화면 폭 3종 × 글자 배율 2종 × 언어 2종을 조합한 52가지 경우를 위젯 테스트로 훑었고, 레이아웃 오버플로 예외는 0건이었습니다.

그런데 각 단계의 스크롤 여지를 측정하자 다른 사실이 나왔습니다. 분할 루틴과 유산소를 함께 켠 미리보기는 스크롤 힌트 없이 최대 화면 높이만큼의 내용을 숨기고 있었습니다. 예외는 나지 않지만 사용자에게는 내용이 잘린 것처럼 보이는 결함입니다. 시뮬레이터로 화면을 캡처해 눈으로 확인하는 단계는 그 세션 환경에서 네이티브 권한 대화상자가 앱 화면을 가려 완료하지 못했고, 원인과 재시도 방법만 문서로 남겼습니다.

교훈: "예외 없음"과 "사용자에게 문제없음"은 다른 판정입니다. 시각 결함은 측정값(스크롤 여지)이나 캡처처럼 다른 신호로 따로 확인해야 합니다.

6. Playwright Test Agents는 어디에 붙나

Playwright는 1.56부터 Test Agents라는 세 가지 에이전트 정의를 제공합니다. npx playwright init-agents --loop=claude로 클로드 코드용 정의를 프로젝트에 추가하며, --loop에는 vscode, codex, opencode도 쓸 수 있습니다. Playwright를 업데이트할 때마다 정의를 다시 생성하라는 안내도 있습니다.

에이전트 공식 문서의 역할 산출물 위 사례에서 맡을 만한 자리
Planner 앱을 탐색해 시나리오와 사용자 흐름의 테스트 계획 작성 specs/의 Markdown 계획 사례 1의 경로 목록, 사례 2의 점검 항목 정하기
Generator 계획을 테스트 파일로 바꾸며 선택자·단언을 실제 화면에서 확인 tests/의 테스트 파일 사례 3처럼 작은 스펙을 계획대로 늘리기
Healer 테스트를 실행해 실패를 고치고, 기능이 망가졌다고 판단하면 건너뜀 처리 통과하거나 건너뛴 테스트 문구·구조 변경으로 깨진 선택자 복구

Planner는 seed.spec.ts라는 시드 테스트를 먼저 실행해 사전 준비를 하고, 그 파일을 생성 테스트의 본보기로 씁니다. 사례 3처럼 로그인 뒤 화면을 다루지 못하던 스펙이라면 시드 테스트에 인증 준비를 넣는 것이 출발점이 됩니다.

조심할 곳은 Healer입니다. 사례 1의 401은 테스트가 아니라 앱이 틀린 경우였습니다. Healer가 그런 실패를 만나면 테스트를 건너뜀으로 바꿀 수 있습니다. 결과에서 건너뛴 테스트를 사람이 다시 확인하지 않으면, 결함을 알려 주던 테스트가 조용히 사라집니다.

교훈: Healer가 고치는 대상은 테스트이고, 앱의 결함은 사람이 판단해야 합니다. 건너뜀으로 바뀐 테스트는 통과가 아니라 보고로 읽어야 합니다.

7. 병렬 실행은 공유 상태가 정한다

에이전트 여러 개로 테스트를 동시에 돌리면 빨라진다는 이야기를 자주 듣습니다. 실제 설정을 보면 세 곳 모두 병렬을 끄거나 줄였습니다. 위키 실습은 세 테스트가 같은 H2 DB를 쓰기 때문에 workers: 1, on-pocket-news 점검기도 workers: 1, blogger-daemon은 fullyParallel: false입니다. Playwright의 기본 동작은 테스트 파일끼리만 병렬로 돌리고, 한 파일 안의 테스트는 순서대로 실행합니다. fullyParallel: true로 파일 안까지 병렬로 바꿀 수 있지만, 테스트끼리 DB나 로그인 상태를 공유하면 실행 순서에 따라 결과가 달라집니다.

교훈: 병렬 실행의 상한은 에이전트 수가 아니라 테스트가 공유하는 상태가 정합니다. 데이터를 되돌려 놓는 테스트가 먼저이고, 병렬은 그다음입니다.

💡 원스의 인사이트: E2E는 판정 도구보다 탐지 도구로 먼저 쓴다

네 사례를 돌아보면 E2E가 가장 쓸모 있었던 순간은 "통과"를 확인할 때가 아니라 몰랐던 문제를 찾아냈을 때였습니다. 401 여덟 건, 회원가입 개선 항목, 숨은 스크롤 영역이 그렇게 나왔습니다.

그래서 클로드 코드에게 E2E를 맡길 때 순서를 이렇게 잡습니다. 먼저 화면을 넓게 훑어 이상 신호를 모으는 점검 스펙을 만들고, 결과를 원인별로 묶어 백로그에 올립니다. 그다음 고친 흐름만 시나리오 테스트로 고정합니다. Test Agents를 붙인다면 Planner와 Generator는 이 두 번째 단계를 빠르게 해 줄 것이고, Healer는 화면이 바뀔 때 깨진 선택자를 정리해 줄 것입니다. 무엇이 결함인지 정하는 일은 어느 단계에서도 사람에게 남겨 둡니다.

체크리스트 — 에이전트에게 E2E를 맡기기 전에

  • [ ] 단위·화면 테스트가 지키지 못하는 약속(경로·응답 모양·오류 코드)을 적었다
  • [ ] 서버 기동과 기기 크기가 playwright.config.ts의 webServer·projects에 들어 있다
  • [ ] 테스트가 바꾼 데이터를 스스로 되돌려 다시 실행해도 결과가 같다
  • [ ] 점검 결과를 원인별로 묶은 뒤 백로그에 올린다
  • [ ] Healer 같은 자동 수리가 건너뜀으로 바꾼 테스트를 사람이 확인한다
  • [ ] 예외가 나지 않는 시각 결함은 캡처나 측정값으로 따로 본다

참고 자료 및 출처