테스트가 초록불이다. 그런데 사용자는 버튼을 누를 수 없다. 이 문장이 모순처럼 들린다면, 아직 AI 에이전트가 Playwright 테스트를 작성할 때 어떤 시각으로 화면을 '보는지' 제대로 생각해보지 않은 것이다.
테스트가 통과해도 버튼은 닿지 않는다
await expect(page.locator('.checkout-button')).toBeVisible() — 이 코드는 항상 통과한다. 하지만 실제로 그 버튼이 375px 모바일 뷰포트 기준 y: 1450px 위치에 있다면? DOM에는 분명히 존재하고, visibility: visible이며, opacity: 1이다. 접근성 트리에도 멀쩡하게 잡힌다. 그러나 쿠키 배너가 버튼 면적의 61%를 덮고 있고, 사용자는 세 화면을 스크롤해야 겨우 닿을 수 있다. AI 에이전트는 이것을 버그라고 보고하지 않는다. 그냥 통과시킨다.
이게 단순한 테스트 도구의 한계가 아니라는 점이 중요하다. AI 에이전트가 Playwright 실패를 분석하거나 새 테스트를 작성할 때 기본적으로 접근하는 데이터는 역할(role), 레이블, 텍스트 콘텐츠, ARIA 속성이다. 기능 테스트에는 최적의 추상화다. 하지만 레이아웃 버그는 DOM이 아니라 렌더 엔진의 출력에 산다. 좌표, z-index, 바운딩 박스, 교차 비율 — 이 데이터들은 접근성 트리 어디에도 없다. AI 에이전트는 구조를 읽지만, 화면을 보지 못한다.
기존 도구가 채우지 못한 공백
이 문제를 해결하려는 시도가 없던 건 아니다. 픽셀 diff 기반 시각 회귀 테스트(Percy, Chromatic 류)는 안티앨리어싱 노이즈에 취약하고, 환경 차이로 인한 오탐이 많다. Applitools 같은 AI 기반 시각 검증 도구는 엔터프라이즈 라이선스 뒤에 잠겨 있다. AI 에이전트에게 구조화된 기하학적 데이터를 실시간으로 넘겨줄 수 있는 오픈소스 도구는 사실상 없었다. dev.to에 공개된 playwright-spatial-layout-mcp는 바로 그 공백을 겨냥한다.
MCP 서버가 에이전트에게 '눈'을 달아주는 방식
이 도구는 MCP(Model Context Protocol) 서버로 동작한다. 헤드리스 Chromium을 띄우고, getBoundingClientRect()와 getComputedStyle()을 단일 page.evaluate() 호출로 묶어 기하학적 데이터를 추출한다. 네트워크 왕복을 최소화하는 설계다. 핵심 기능은 네 가지다.
extract_bounding_boxes — 지정한 셀렉터들의 위치, 크기, z-index, 뷰포트 내 가시 여부를 반환한다. 체크아웃 버튼이 375px 뷰포트에서 is_in_viewport: false로 나온다면, 에이전트는 비로소 이것을 '존재하지만 닿을 수 없는 버튼'으로 인식할 수 있다.
detect_visual_occlusion — 두 요소의 바운딩 박스 교차 비율을 계산한다. 쿠키 배너가 버튼 면적의 61%를 덮고 있다는 사실을 intersection_ratio: 0.61로 돌려준다. 이제 에이전트는 이것을 통과가 아닌 버그로 보고할 수 있다.
verify_spatial_relationships — left_of, right_of, above, below, contains, not_overlapping 여섯 가지 규칙 타입으로 레이아웃 명세를 코드로 표현하고 통과/실패 여부를 반환한다. 디자인 제약 조건을 기능 테스트처럼 단언할 수 있다는 발상이 흥미롭다. 사이드바와 메인 콘텐츠가 12% 겹친다면, 룰 기반으로 즉시 잡아낸다.
compute_viewport_reflow — 여러 브레이크포인트를 병렬로 처리해 요소의 위치·크기 변화를 추적한다. CTA가 모바일-데스크톱 사이에서 수평 442px, 수직 318px 이동했다면, 어떤 요소가 반응형 전환에서 가장 불안정한지 에이전트가 수치로 파악할 수 있다.
'존재하는가'에서 '닿을 수 있는가'로
이 도구가 흥미로운 건 단순히 레이아웃 버그를 잡는 기능 때문이 아니다. 에이전트가 던지는 질문의 틀 자체를 바꾸기 때문이다. 기존 질문은 "이 요소가 DOM에 존재하는가"였다. 새 질문은 "실제 사용자가 이 기기에서 이 요소에 닿을 수 있는가"다. 이 전환은 프론트엔드 품질 검증이 오랫동안 외면해온 진짜 사용자 경험의 물리적 현실을 테스트 레이어로 끌어올린다.
Claude Desktop 설정에 MCP 서버를 등록하면, 에이전트에게 자연어로 물을 수 있다. "375px 뷰포트에서 쿠키 배너가 체크아웃 버튼을 가리고 있는지 확인해줘." "nav가 히어로 섹션 위에 있고 사이드바가 메인 콘텐츠와 겹치지 않는지 검증해줘." "데스크톱에서 모바일로 리사이즈할 때 가장 많이 움직이는 요소가 뭐야." 에이전트는 이제 이 질문들에 구체적인 수치로 답할 수 있다.
실무에서 즉시 유효한 세 가지 시나리오
프로토타이핑-검증 흐름에서 이 도구가 가장 빛나는 순간을 짚어보면 세 가지다. 첫째, CSS 리팩토링 후 시각 회귀 diff 없이 레이아웃 명세를 코드로 검증할 때. 픽셀 diff가 아니라 공간 관계 규칙으로 검증하기 때문에 환경 노이즈에 흔들리지 않는다. 둘째, 반응형 구현 직후 모바일 뷰포트에서 오프스크린 요소를 선제적으로 색출할 때. 테스트 스위트가 돌기 전에 이미 알 수 있다. 셋째, 머지 후 z-index 충돌이 조용히 발생했을 때. 한 컴포넌트가 다른 컴포넌트 밑으로 슬며시 밀려나는 현상을 에이전트가 수치로 포착한다.
더 큰 생태계의 맥락
playwright-spatial-layout-mcp는 독립 도구가 아니다. 동일 저자가 만든 Playwright/TypeScript 테스트 생태계 MCP 시리즈의 다섯 번째 작업이다. Playwright 트레이스 파일에서 근본 원인을 분석하는 playwright-trace-decoder-mcp, 플레이키 테스트 패턴을 지식 그래프로 관리하는 flakiness-knowledge-graph-mcp, TypeScript AST 기반 테스트 영향 분석 ast-impact-mapper-mcp, Zod 스키마에서 결정론적 목 데이터를 생성하는 zod-contract-mock-forge-mcp가 앞서 있다. 각각이 에이전트가 구조화된 도구 접근 없이는 추론할 수 없는 특정 맹점 하나씩을 겨냥한다. 공간 레이아웃은 그중 가장 가시적인 맹점이었다.
간극을 인식하는 것이 먼저다
AI 에이전트가 테스트를 작성하고 버그를 분석하는 속도는 이미 인간을 압도한다. 하지만 에이전트가 보지 못하는 것이 무엇인지를 팀이 명확히 알지 못하면, 속도는 오히려 위험이 된다. 초록불 테스트 뒤에 숨은 레이아웃 버그가 그 전형이다. DOM과 렌더링 사이의 간극 — 이 틈을 구조화된 기하학적 데이터로 메우는 시도는, 에이전트를 더 빠른 타이피스트가 아니라 실제로 보고 판단하는 협력자로 만들려는 방향의 작은 한 걸음이다. 그리고 그 한 걸음이, 지금 프론트엔드 테스트 자동화가 가장 필요로 하는 곳에 정확히 놓여 있다.