프론트엔드에서 DIP는 어디에 쓰일까? 자동화 도구를 재설계하며 얻은 인사이트

직장동료와 함께 프론트엔드 개발 생산성에 대해 토론하다가, 반복되는 단순 작업을 줄이기 위한 자동화 프로젝트를 시작하게 되었습니다. 현재는 오픈소스 라이브러리를 커스텀하거나 직접 제작한 도구들을 npm에 배포하여 실제 팀 내 프로젝트에 적용해 사용하고 있습니다.

• msw-auto-mock: OpenAPI 스펙 기반의 MSW 핸들러 자동 생성 도구입니다. 기존 라이브러리를 포크하여, 복잡한 비즈니스 로직에 대응할 수 있도록 시나리오별 커스텀 기능을 확장했습니다.
• e2e-autogen: 테스트 시나리오가 담긴 스프레드 시트 데이터를 Playwright 테스트 스텁(Stub)코드로 변환해 주는 도구입니다.
• api-recorder: 실제 네트워크 API 호출을 녹화하여 JSON 데이터로 변환합니다. 이는 앞선 두 도구와 통합되어, 실제 데이터를 기반으로 한 정교한 MSW, Playwright 목업을 생성하는 데이터를 만드는 핵심 역할을 합니다.

하지만 이 도구들을 활용해 Playwright E2E 코드를 작성하다 보니 몇 가지 실질적인 불편함을 발견하게 되었고, 이를 개선하는 과정에서 기존 설계의 구조적 결함과 의존성 문제로 인한 확장성의 한계를 느꼈습니다. 이번 글에서는 기존 도구의 불편함을 개선함과 동시에, 더 유연한 아키텍처로 재설계하며 고민했던 과정들을 이야기해보려 합니다.

어떤 불편함이 있었을까?

api-recorder: 보조 도구로 쓰기에는 개입 비용이 큽니다

개발할 때는 보통 개발자 도구를 항시 열어두고 작업합니다. api-recorder로 네트워크 로그를 수집할 때도 마찬가지이고, 여기에 TanStack Query Devtools까지 함께 사용하는 경우도 많습니다.

이 상태에서 네트워크 녹화를 위해 api-recorder 패널까지 추가로 열게 되면, 화면에서 가려지는 영역이 많아져 작업 흐름이 끊기는 느낌을 받았습니다. 물론 패널을 최소화할 수는 있지만, 녹화 결과를 중간중간 확인하려면 다시 열어야 했고, 이 과정이 반복되면서 은근한 피로도가 쌓였습니다.

사소한 불편함처럼 보일 수 있지만, 이 지점에서 계속해서 이런 생각이 들었습니다.

msw-auto-mock: 자동화되었지만 여전히 손이 많이 갑니다

msw-auto-mock은 api-recorder로 녹화한 데이터를 기반으로 MSW override 핸들러 코드를 자동 생성해주는 도구입니다. 이 도구를 활용해 테스트 케이스별로 네트워크를 목업할 때는 다음과 같은 과정을 거치게 됩니다.

1. api-recorder를 실행하고 원하는 시나리오를 수행하여 네트워크 JSON 파일을 생성합니다.
2. 생성된 파일을 프로젝트 경로에 저장한 뒤, 어떤 시나리오에 매핑할지 설정합니다.
3. msw-auto-mock 명령어를 실행해 override 핸들러를 생성합니다.

테스트 케이스 하나를 추가할 때마다 이 세 단계를 반복해야 했고, 이 과정이 점점 번거롭게 느껴졌습니다. 이미 JSON 데이터가 있는데, 굳이 다시 코드를 생성하지 않고 이 데이터를 그대로 런타임에서 활용할 수는 없을까? 라는 생각이 들었습니다.

테스트 코드처럼 단순 반복 작업이 많은 영역에서는, 단계 하나를 줄이는 것만으로도 체감 생산성이 크게 달라진다고 느꼈습니다.

e2e-autogen: 생성은 편하지만 실행 맥락이 분리되어 있습니다

e2e 테스트를 작성할 때는 보통 Playwright 제너레이터를 사용해 시나리오를 기록하는데, 이 단계에서는 목업된 데이터를 사용할 수 없습니다. mockApiResponse는 테스트 코드 실행 시점에만 적용되고, Playwright 제너레이터는 테스트 실행이 아니라 일반 브라우저 실행이기 때문입니다.

예를 들어 "목록에 아이템이 하나도 없을 때 빈 화면 문구가 노출되어야 한다"는 시나리오를 검증하려면,

• msw-auto-mock으로 빈 응답에 대한 목업을 만들어 Playwright 제너레이터 시점에 활용하고, 테스트 코드 실행 시점에는 e2e-autogen의 mockApiResponse fixture를 사용하는 방식으로 두 번의 작업을 하거나
• Playwright 제너레이터 실행 시점에는 UI 코드를 임시로 수정해 확인한 뒤, 테스트 코드 실행 시점에는 다시 mockApiResponse fixture를 사용하는 방식으로 우회해야 했습니다.

이 과정은 테스트를 빠르게 작성하고 검증하기에는 지나치게 번거로웠고, 결국 개발 흐름과 테스트 실행 맥락이 분리되어 있다는 점이 가장 큰 문제로 느껴졌습니다. 그래서 이 불편함들을 동시에 해결할 수 있는 구조가 필요하다고 판단했습니다.

개선 아이디어

앞서 언급한 불편함들을 정리하다 보니, 다음과 같은 아이디어가 떠올랐습니다.

• e2e-autogen의 편리함과 msw의 유연함을 합칠 수 없을까?
• api-recorder로 생성한 JSON 데이터를 기반으로, 코드를 생성하지 않고도 런타임에 MSW 핸들러를 동적으로 세팅할 수 있다면 어떨까?

이를 위해 각 테스트 시나리오에 대응하는 시나리오 매핑 파일을 두고, 해당 시나리오를 주입하면 런타임에서 필요한 핸들러가 구성되는 구조를 떠올렸습니다.

이 접근이 가능하다면,

• msw-auto-mock처럼 사전 생성 과정을 거치지 않아도 되고
• e2e-autogen처럼 테스트 실행 시점뿐 아니라, 개발·디버깅 단계에서도 동일한 목업을 사용할 수 있을 것이라고 생각했습니다.

아이디어를 구체화하며 알게 된 HAR 스펙

위 생각을 바탕으로 아이디어를 구체화하던 중, 한 가지 질문이 생겼습니다.

이 과정에서 HAR(Http Archive)스펙을 알게되었습니다. HAR 파일은 브라우저 개발자 도구의 네트워크 탭에서 기록되는 요청/응답 정보를 표준화된 JSON 포맷으로 저장한 파일입니다. 즉, 개발자가 이미 익숙하게 보고 있는 네트워크 로그를 그대로 파일로 추출할 수 있습니다.

HAR 파일을 기반으로 api-recorder에서 사용하는 JSON 포맷을 생성할 수 있다면, 별도의 api-recorder 라이브러리를 설치하지 않아도 되고, 개발자 도구의 네트워크 탭이라는 기존 흐름을 그대로 유지할 수 있을 것이라 생각했습니다.

기존 구조에서 드러난 문제점

하지만 이 아이디어를 기존 구조에 적용하려고 하자, 구조적인 문제들이 드러나기 시작했습니다.

의존성 문제

현재 구조에서는 e2e-autogen, msw-auto-mock이 api-recorder가 생성한 결과물의 타입과 스펙에 직접 의존하고 있습니다. 문제는 이 의존성이 성격상 어색하다는 점이었습니다. 두 라이브러리는 api-recorder의 기능을 사용하지 않고, 오직 결과물의 형태(타입) 만 필요로 합니다. 그럼에도 불구하고 단순히 타입을 참조하기 위해 api-recorder를 종속성으로 설치하는 것은 사용자 입장에서 납득하기 어려운 구조라고 느껴졌습니다.

특히 e2e-autogen, msw-auto-mock을 사용하는 사용자 중에는 api-recorder를 전혀 사용하지 않는 경우도 있기 때문에, 이 의존성은 불필요한 결합을 강제하는 셈이 됩니다.

그래서 임시방편으로 선택한 방법이, api-recorder의 타입 정의를 각 라이브러리 내부에 복사해서 관리하는 방식이었습니다. 하지만 이 방식은 명확하게 Single Source of Truth 원칙을 위배합니다. api-recorder의 타입이 변경되더라도 e2e-autogen, msw-auto-mock에서는 이를 자동으로 인지할 수 없고, 결국 세 곳의 코드를 모두 수정해야 하는 구조가 됩니다.

더 큰 문제는 의존성 방향이었습니다. 개념적으로 보면 e2e-autogen, msw-auto-mock은 하위 모듈에 가깝고, api-recorder 역시 하나의 하위 구현체에 불과합니다. 그런데 이 하위 모듈들이 서로의 내부 구조를 전제로 동작하게 되면서, 결과적으로 하위 모듈들끼리 강하게 결합된 상태가 되어버렸습니다.

이 구조에서는 어느 한 모듈의 변경도 다른 모든 모듈에 연쇄적인 영향을 줄 수밖에 없고, 확장이나 스펙 변경에 매우 취약한 상태라고 판단했습니다.

har 호환성 문제

api-recorder 대신 개발자도구의 har을 사용하려면, har을 api-recorder와 호환되는 형식으로 바꾸는 과정이 필요한데, 이 또한 이 동작을 수행해주는 har-to-api-recorder라는 라이브러리를 추가로 만들 계획을 세웠습니다.

하지만 여기서 또 하나의 이상함이 느껴졌습니다.

• har-to-api-recorder
• msw-auto-mock
• e2e-autogen

이 세 라이브러리는 api-recorder의 기능을 직접 사용하지 않음에도 불구하고, 모두 api-recorder의 스펙 변경에 영향을 받는 구조가 되어 있었습니다.

만약 api-recorder의 스펙이 변경된다면, 연쇄적으로 모든 라이브러리가 영향을 받게 됩니다.

게다가 HAR 파일에는 api-recorder에는 없지만,

• 향후 MSW 목업이나 테스트에 활용할 수 있을 법한 정보들이 존재했고
• 이를 스펙에 포함시키고 싶었지만
• 이미 배포된 라이브러리와 사용자들이 존재하기 때문에 마음대로 변경할 수 없는 상황이었습니다. 이 지점에서, 문제의 본질은 포맷 변환이 아니라 구조라는 결론에 이르렀습니다.

해결 방법: 스펙을 중심으로 DIP 원칙 적용하기

이 문제를 풀기 위해 떠올린 힌트는 OpenAPI 스펙 구조였습니다.

OpenAPI는 2.0, 3.0, 3.1 등 여러 버전의 스키마가 존재하지만, 이를 직접 처리하기보다 swagger-parser 같은 라이브러리를 통해 정규화된 형태로 해석합니다.

이 구조에서 아이디어를 얻어, 네트워크 로그도 같은 방식으로 다루기로 했습니다.

핵심 아이디어

• api-recorder가 생성한 포맷을 스키마 v1.0
• HAR 파일을 기반으로 생성한 포맷을 스키마 v1.1

로 정의하고, 이 다양한 스키마를 해석하고 정규화하는 코어 라이브러리를 분리하기로 했습니다. 이 스펙의 이름을 network-log라고 명명했습니다.

network-log-core의 역할

1. 다양한 형태의 입력을 단일 NetworkLog 포맷으로 정규화합니다.

network-log-core의 핵심 진입점은 NetworkLogParser입니다. 이 함수를 통해raw 데이터가 api-recorder(v1.0)이든, HAR 기반으로 생성된 v1.1 스키마이든 관계없이 항상 정규화된 NetworkLog 형태로 변환합니다. 이 구조 덕분에 e2e-autogen, msw-auto-mock 같은 하위 모듈들은 데이터가 어디에서 왔는지를 전혀 신경 쓰지 않고 항상 동일한 형식의 네트워크 로그를 기준으로 동작할 수 있습니다.

즉,입력 포맷의 다양성은 network-log-core에서 흡수하고, 하위 모듈은 해석된 결과만 바라보는 구조가 됩니다.

2. network-log-core는 안정적인 라이브러리입니다.

클린 아키텍처 관점에서 말하는 컴포넌트의 안정성이란, 다음과 같습니다.

안정적이라는 것은 곧 변경하기 어렵다는 의미이고, 그만큼 많은 코드가 해당 컴포넌트(배포 가능한 최소 단위)에 의존하고 있다는 뜻이기도 합니다.

network-log-core는 이 기준을 만족하도록 설계되었습니다.

• e2e-autogen, msw-auto-mock, api-recorder 등 여러 하위 모듈이 이를 참조하지만
• network-log-core 자체는 외부 구현에 의존하지 않습니다

그 결과, 하위 모듈들은 변경 가능성이 높은 구현이 아니라 안정적인 상위 스펙(NetworkLog 타입) 에만 의존하게 되었고, 구조 전체가 변경에 훨씬 덜 취약해졌습니다.

3. 의존성이 역전됩니다.

이 구조에서는 api-recorder나 har-to-network-log가 자체적인 기준 인터페이스를 정의하지 않습니다. 대신, network-log-core가 제시하는 인터페이스와 타입을 기준으로 구현합니다. 즉 하위 구현체(api-recorder, har-to-network-log)가 상위 모듈이 정의한 계약을 구현하는 구조가 되면서 의존성이 명확히 역전됩니다. 클래스 단위가 아니라 라이브러리 단위에서 DIP를 적용한 사례라고 볼 수 있습니다.

정리하자면, 위 구조 덕분에 network-log를 통한 생태계를 확장해나가더라도 기존 하위 모듈들은 전혀 영향을 받지 않고, 하위 모듈 간 직접적인 의존성도 사라졌으며 새로운 입력 포맷이나 활용 도구를 추가하기도 용이해졌습니다.

마무리

이번 글에서는 네트워크 로그 도구들을 확장하는 과정에서 드러난 구조적 문제를 어떻게 설계로 풀어냈는지 정리했습니다. 다음 글에서는 이 설계를 기반으로 실제 라이브러리를 구현한 과정과 코드 레벨의 선택들을 다뤄볼 예정입니다.

이번 사례는 프론트엔드 환경에서 DIP(Dependency Inversion Principle) 를 적용한 경험이기도 합니다. 클린 아키텍처에서 말하는 원칙들은 보통 백엔드나 객체지향 언어 중심으로 설명되지만, 이번 작업을 통해 프론트엔드에서도 모듈 단위, 스펙 단위로 충분히 체감할 수 있다는 걸 느꼈습니다. 특히 컴포넌트 안정도 관점에서 의존성을 다시 바라보게 된 점이 인상 깊었습니다.

최근 클린 아키텍처를 읽으면서 "이걸 프론트엔드에서 어디에 써먹을 수 있을까?"라는 고민을 많이 했는데, 코드 레벨에서는 바로 떠오르지 않던 답이 모듈 설계 레벨에서 자연스럽게 연결되었습니다.

요즘은 AI 덕분에 새로운 기술을 빠르게 학습하고 소비하는 경험이 많아졌지만, 그럴수록 이런 기본적인 설계 원칙들이 오히려 더 큰 힘을 발휘한다고 느낍니다. AI를 잘 활용하기 위해서라도, 가끔은 클린 아키텍처 같은 책을 다시 펼쳐보며 내 사고방식 자체를 천천히 업데이트하는 시간이 필요하다는 생각이 들었습니다.