AI 에이전트의 프론트엔드 검증: Playwright 스크린샷으로 눈을 달아준 과정

서버 환경에서 코드를 직접 고치고 빌드하는 AI 에이전트에게 화면 개발을 맡기다 보면 묘한 장벽을 만납니다. 타입 검사도 통과하고 빌드도 성공했는데, 브라우저에서 화면을 열어보면 글자가 겹쳐 있거나 버튼이 화면 밖으로 밀려나 있는 식입니다. 사람 개발자라면 개발 서버를 띄우고 크롬 창을 옆에 둔 채 눈으로 확인하며 고치겠지만, 터미널 속 AI 에이전트에게는 모니터도 눈도 없습니다.

모니터 없는 서버 환경에서 마주친 검증 한계

제가 작업하는 개발 서버는 모니터가 연결되지 않은 리눅스 환경입니다. 웹 서비스를 수정할 때마다 코드를 커밋하고 사람이 직접 브라우저로 들어가 16개나 되는 라우트를 일일이 눌러보는 방식은 금방 지쳤습니다. 에이전트가 "개발을 마쳤습니다"라고 보고해도, 실제로는 특정 팝업이 안 열리거나 지도 컴포넌트가 깨져 있는 일이 잦았습니다.

코드가 에러 없이 돌아간다는 사실과 화면이 제대로 렌더링된다는 사실은 전혀 다른 문제입니다. 에이전트가 자기 작업물을 스스로 검수하려면 브라우저를 직접 띄워서 렌더링 결과를 사진으로 찍어 보여줄 방법이 필요했습니다.

playwright-core와 컨테이너 브라우저의 조합

처음에는 일반적인 Playwright 패키지를 그대로 설치하려 했습니다. 그런데 매번 수백 메가바이트에 달하는 크로미움 바이너리를 새로 내려받느라 설치 시간도 길어지고 디스크도 낭비되었습니다.

해결책은 컨테이너 환경의 분리였습니다. 브라우저 엔진이 이미 내장된 공식 Playwright 이미지를 컨테이너 베이스로 두고, 프로젝트의 개발 의존성에는 playwright-core만 가볍게 넣었습니다. 이렇게 구성하니 무거운 바이너리 다운로드 과정 없이 컨테이너 내부의 브라우저를 그대로 재사용하면서도 가볍게 구동할 수 있었습니다.

16개 화면을 전수 캡처하는 스크립트 작성

다음으로 서비스의 주소 체계를 정리해 16개 핵심 라우트를 순회하는 screen-check.mjs 검사 스크립트를 작성했습니다. 단순히 페이지를 열고 닫는 것이 아니라, 각 화면을 가상 브라우저로 렌더링한 뒤 .screen-check/ 디렉터리에 번호와 이름을 붙여 PNG 스크린샷으로 저장하도록 했습니다.

// scripts/screen-check.mjs 발췌
const routes = [
  { name: '01-대시보드', path: '/' },
  { name: '02-메뉴관리', path: '/menu' },
  { name: '03-일정', path: '/schedule' },
  // ... 16개 라우트
];

for (const route of routes) {
  const page = await context.newPage();
  await page.goto(`http://127.0.0.1:3000${route.path}`, { waitUntil: 'networkidle' });
  await page.screenshot({ path: `.screen-check/${route.name}.png`, fullPage: true });
  await page.close();
}

스크린샷을 읽고 스스로 결함을 찾아낸 에이전트

스크립트를 실행하자 순식간에 16장의 화면 캡처가 생성되었습니다. 이 작업의 핵심은 그 다음 단계였습니다. AI 에이전트에게 파일 읽기 도구로 캡처된 이미지 파일(03-일정.png)을 직접 열어보게 했습니다.

에이전트는 터미널 로그만 보던 상태에서 벗어나 실제 화면 이미지를 분석했습니다. 그리고 곧바로 두 가지 문제를 스스로 지적했습니다. 일정 화면에서 특정 설정 단추가 정상적으로 눌리지 않는 상태라는 점과, 지도 화면에서 참조할 지도 데이터 파일이 준비되지 않았다는 점이었습니다. 사람이 지적하기 전에 이미지가 깨진 원인을 스스로 찾아내 코드를 수정하기 시작했습니다.

테스트 러너가 에이전트의 시각 기관이 되는 경험

사람에게 Playwright나 Cypress 같은 E2E 도구는 주로 배포 전 회귀 버그를 잡는 자동화 파이프라인의 일부입니다. 하지만 자율적으로 코드를 짜는 AI 에이전트에게 이 도구는 단순한 검사기를 넘어 화면을 인지하는 '시각 기관' 역할을 합니다.

브라우저를 띄워 스크린샷을 찍고, 그 사진을 멀티모달 모델이 읽어 레이아웃 결함을 스스로 판단하는 루프가 갖춰지면 프론트엔드 작업의 자율성이 완전히 달라집니다. 모니터 없는 헤드리스 서버에서도 에이전트에게 눈을 달아줄 수 있다는 점을 확인한 작업이었습니다.