지니로그

단독 개발 · 개인 프로젝트

유닛 테스트 1,090개가 전부 통과하는데 컴포넌트의 4분의 1은 렌더되지 않았다

기간
2026.07
역할
단독 개발 · 개인 프로젝트
사용 기술
TypeScriptts-morphesbuildpnpm workspaceTurborepopostcssVitestMCP
관련 링크

Component Explorer의 유닛 테스트 1,090개가 전부 통과하는 상태에서 실제 1,133개 컴포넌트 대상 프로젝트를 전수 조사했더니 75.3%만 실제로 디자인을 보여줬다. 조사 도구 자체를 커밋해 재현 가능한 게이트로 만들고 4일간 루프를 돌려 91.8%까지 올렸다. 읽기 전용 원칙은 문서가 아니라 타입으로 강제했다.

무엇을 만들었나

기존 React + TypeScript 프로젝트를 읽기 전용으로 스캔해 UI 컴포넌트를 자동 분류하고, 격리 환경에서 실제로 렌더링해 확인한 뒤, 이식 가능한 코드로 추출하고 디자인 토큰을 실시간 재테마하는 개발 도구다. Storybook 과 코드 하베스터를 합친 개념에 가깝다.

패키지 4개로 나눴다. 엔진(core)은 프레임워크·런타임과 무관한 순수 Node 계층이고, host 는 엔진을 감싸는 로컬 서버 겸 번들러, web 은 host 와 JSON API로만 통신하는 갤러리, mcp 는 같은 엔진을 AI 에이전트에게 노출하는 서버다.

이 도구를 만들면서, 테스트가 다 통과하는데도 제품이 동작하지 않는 상황을 겪었다.

무엇이 문제였나

유닛 테스트 1,090개가 전부 통과하는 상태에서, 실제로 디자인을 보여주는 컴포넌트는 75.3%뿐이었다.

1,133개 컴포넌트를 가진 실제 프로젝트를 대상으로 전수 조사해서 알았다. 나머지 4분의 1은 스캔은 되고 분류도 되는데, 미리보기를 열면 빈 화면이거나 예외를 던지거나 의미 없는 껍데기만 나왔다.

왜 유닛 테스트가 이걸 못 잡았나

유닛 테스트는 내가 예상한 입력만 검증하기 때문이다.

분류기 테스트는 “이런 모양의 컴포넌트가 들어오면 이 카테고리가 나온다”를 확인한다. 번들러 테스트는 “이 spec 이 들어오면 이런 번들이 나온다”를 확인한다. 각 단계는 전부 옳게 동작한다.

문제는 실제 프로젝트의 컴포넌트가 내가 상상한 모양이 아니라는 것이다. 필수 객체 prop 을 요구하고, 컨텍스트 프로바이더를 기대하고, 자기 자신을 참조하는 타입을 갖고 있고, 포털로 body 에 렌더된다. 이 조합은 픽스처로 만들어낼 수 없다. 만들 수 있었다면 이미 테스트에 있었을 것이다.

“단위가 옳다”와 “제품이 동작한다” 사이에 검증되지 않은 간극이 있었고, 그 간극의 크기가 24.7%였다.

어떻게 해결했나 — 조사 도구를 게이트로 만들었다

한 번 조사하고 고치는 것으로 끝내지 않고, 조사 도구 자체를 저장소에 커밋해 재현 가능한 게이트로 만들었다.

센서스는 엔진의 자체 판정을 믿지 않는다. 렌더된 DOM 을 직접 읽어 판정한다. 엔진이 “이 컴포넌트는 렌더 가능”이라고 말해도, 실제로 그려진 것이 빈 <div> 라면 실패로 센다. 포털로 body 에 렌더되는 dialog·drawer·menu 를 놓치지 않도록 컨테이너가 아니라 body 전체를 탐침한다.

4일간 이 루프를 돌렸다. 센서스 실행 → 실패 목록 확인 → 가장 큰 실패 부류 수정 → 다시 센서스. 75.3% → 91.8% 로 올라갔다(853건 → 1,040건 / 1,133건).

그 과정에서 고친 것들

필수 객체 prop 을 빈 객체로 채우면 안 된다

{} 를 넣으면 예외가 사라지는 게 아니라 한 단계 뒤로 미뤄진다. 컴포넌트 안에서 props.config.items.map(...) 을 하는 순간 다시 터진다.

prop 의 실제 타입을 해석해 재귀적으로 안전한 기본값을 만들도록 했다. 배열 타입이면 표본 원소를 하나 채워 테이블이 테이블처럼 보이게 한다. 다만 자기 자신을 참조하는 타입에서 무한 재귀에 빠지므로 깊이 상한·속성 개수 상한·사이클 가드를 함께 걸었다.

렌더할 수 없으면 정직하게 강등한다

로드 불가능한 의존성을 가진 컴포넌트를 억지로 렌더하면 거짓말이 된다. 3단계 판정을 뒀다.

판정의미
full거의 스텁 없이 렌더된다
stubbed렌더되지만 앱 컨텍스트를 가짜로 채웠다 — 실제와 다를 수 있다
code-only렌더 불가. 코드를 참조용으로만 쓴다

stubbed 를 full 로 뭉뚱그리지 않는 것이 이 도구의 신뢰도를 결정한다. 사용자가 미리보기를 보고 “우리 앱에서도 이렇게 보이겠구나”라고 판단하는데, 그 판단이 틀리면 도구를 쓸 이유가 없다.

분류할 수 없으면 분류하지 않는다

역할 분류기는 DOM 엘리먼트·이름 매칭·prop 계약 세 가지 증거원을 문서화된 우선순위로 결합한다. 결정적 근거가 없으면 other 로 남긴다.

재현율을 포기하고 정밀도를 산 선택이다. 근거는 하나다 — 틀린 분류가 무분류보다 나쁘다. 무분류는 사용자가 직접 찾게 만들 뿐이지만, 틀린 분류는 사용자를 엉뚱한 곳으로 보낸다.

읽기 전용 원칙을 타입으로 강제했다

이 도구의 존재 이유는 남의 저장소를 건드리지 않는 것이다. 대상 프로젝트를 수정하지 않고, 대상의 dev 서버도 실행하지 않는다.

원칙을 문서에만 적으면 언젠가 깨진다. 그래서 대상 저장소 접근을 ReadOnlyFs 인터페이스 하나로 좁히고 쓰기 메서드를 아예 노출하지 않았다. 존재하지 않는 메서드는 실수로 호출할 수 없다. 모든 경로 접근이 프로젝트 루트 안쪽인지도 함께 검사한다.

토큰 재작성(write-back)은 이 도구 자신의 워크스페이스에서만 일어나는데, 여기에도 안전장치를 뒀다. 재작성 후 각 파일을 다시 파싱해 문법이 깨졌으면 그 파일의 계획 전체를 폐기하고 토큰을 하나도 발행하지 않는다. 결과적으로 “코드를 깨뜨리는 재작성이 토큰을 남기는 일”이 구조적으로 불가능하다.

같은 엔진을 AI 에이전트에게 노출했다

host 와 같은 엔진 세션을 stdio MCP 서버로 감싸 도구 6종을 노출했다. 스캔·목록·이식 코드·키트·재테마·접근성 감사다.

페이로드 설계 기준은 정직함으로 잡았다. 응답에 renderability, 스텁으로 바꾼 모듈, 원본 앱에서 온 파일(테마·i18n·컨텍스트 프로바이더)을 명시한다. 마지막 항목이 중요하다 — 그 파일들을 그대로 복사하면 원본 앱의 디자인 결정을 통째로 들여오게 되는데, “우리 테마에 맞춰줘”라는 요청에는 정반대 결과다. 에이전트가 그것을 알 수 있어야 한다.

긴 스캔이 타임아웃으로 죽지 않도록 엔진 진행률을 progress notification 으로 전달한다.

결과

항목값
실제 렌더 비율75.3% → 91.8% (853 → 1,040 / 1,133)
테스트1,134건 전부 통과
엔진(core) 커버리지구문 94.76% · 브랜치 88.2% · 함수 97.04%
MCP 도구6종

컨벤션 문서에 한 줄을 명문화했다 — “유닛 게이트가 통과했다고 컴포넌트가 렌더되는 것은 아니다.”

되돌아보면

유닛 테스트를 더 많이 썼어도 이 문제는 못 잡았을 것이다. 문제는 테스트의 양이 아니라 종류였다. 내가 상상할 수 있는 입력으로는 실제 세계의 조합을 만들어낼 수 없다.

그래서 실제 대상에 대고 전수로 돌려보는 검사를 품질 게이트의 한 층으로 따로 둬야 한다. 유닛 테스트를 대체하는 게 아니라 다른 층이다. 그리고 그 검사는 일회성 조사로 끝내지 말고 커밋해서 계속 돌려야 한다 — 그러지 않으면 다음 달에 다시 75%가 된다.

숫자를 100% 로 만들지 않은 것도 의도다. 억지로 렌더시켜 비율을 올릴 수는 있지만, 그건 위에서 말한 stubbed 를 full 로 뭉뚱그리는 것과 같은 일이다. 렌더되지 않는 것은 렌더되지 않는다고 두는 편이 도구의 신뢰도에 낫다.