Nuxt Test Utils v4가 Vitest v4 의존성 도입으로 테스트 환경 초기화 시점을 setupFiles에서 beforeAll 훅으로 변경해 모의 객체 적용의 일관성 확보

Context

Nuxt Test Utils v3에서는 테스트 환경 설정을 setupFiles에서 수행했으므로 미들웨어나 플러그인 내부의 조합형 함수를 vi.mock과 mockNuxtImport가 신뢰성 있게 가로채지 못했다. 모듈 수준의 모의 객체가 자동으로 무시되는 문제로 사용자들이 버그 보고를 여러 차례 제출했다.

Technical Solution

• 테스트 환경 초기화 시점 변경: setupFiles에서 beforeAll 훅으로 이동해 Nuxt 시작 전에 모의 객체 등록 완료
• mockNuxtImport 개선: 원본 구현을 팩토리 함수에 전달해 전체 모의 객체 작성 대신 실제 구현을 래핑하거나 확장 가능하도록 변경
• registerEndpoint 유틸리티 수정: 설정 파일 내부에 등록된 엔드포인트가 테스트 간 모듈 리셋 후에도 유지되도록 상태 관리 개선
• 쿼리 파라미터 지원: URL 패턴에 쿼리 파라미터를 포함하는 엔드포인트가 올바르게 매칭되도록 수정
• 모의 객체 내보내기 엄격화: Vitest v4에서 팩토리 함수가 명시하지 않은 내보내기 접근 시 undefined 반환 대신 예외 발생하도록 변경, importOriginal을 스프레드하는 방식으로 기존 내보내기 모두 기본 제공
• 종속성 버전 상향: happy-dom 20.0.11 이상, jsdom 27.4.0 이상, @jest/globals 30.0.0 이상, @cucumber/cucumber 11 이상 필수

Impact

아티클에 정량적 수치가 없습니다.

Key Takeaway

테스트 환경 초기화 순서와 모의 객체 적용 시점의 정렬은 프레임워크 수준 테스트 라이브러리의 신뢰성을 크게 좌우한다. 상위 버전 의존성 도입 시 기존 API 호출 지점을 재검토하고 새로운 엄격성 규칙에 맞춰 마이그레이션하는 것이 장기 유지보수성을 확보한다.