📡 07. [실무] TanStack Query 프론트엔드 테스트(Testing) 전략

📋 목차

• ☕️ 영철이의 고민: "테스트만 짜면 리액트 쿼리가 다 뱉어내요!"
• 🤔 왜 알아야 하는가: 테스트 격리와 네트워크 가로채기
• 1. 전역 오염 차단: QueryClient 인스턴스 격리 테크닉
• 2. API 모킹(Mocking)의 정점: MSW (Mock Service Worker)
• 📝 배운 내용 점검하기 (Quiz)

"영철 님, 단위 테스트 돌렸더니 'Network Error: Fetch is not defined' 만 50줄 뜨는데, Jest 안에서 진짜 배포 서버를 찌르고 계셨나요?"

☕️ 영철이의 고민: "테스트만 짜면 리액트 쿼리가 다 뱉어내요!"

(금요일 저녁, 마지막 테스트 커버리지를 챙기려다 오열하는 영철)

🐣 영철: 아니 리드 님! 이제 완벽하게 컴포넌트 다 짰으니까 든든하게 Vitest(또는 Jest) 랑 React Testing Library(RTL) 켜서 테스트 레이어 얹으려고 했거든요?
근데 테스트(npm run test) 실행하자마자... 에러가 산더미처럼 쏟아져요!
No QueryClient set, use QueryClientProvider 에러부터 시작해서,
기껏 Provider 감싸줬더니 이번엔 백엔드 서버가 안 켜져 있다고 Network Timeout 나고요,
그거 고쳤더니 "1번 테스트에서 만든 캐시 데이터" 가 "2번 테스트" 에 오염돼서 테스트가 핑퐁으로 깨져요. 리액트 쿼리 테스트는 불가능한 영역인가요?

🦁 영호: 영철 님, 프론트엔드 테스트 세계에 발을 들이셨군요. useQuery가 컴포넌트 안에 짱박혀 있는데 그걸 로컬 노드(Node.js / JSDOM) 환경에서 그냥 렌더링하려고 하니까 온갖 오류란 오류는 다 터지는 겁니다.

1. QueryClientProvider 없이는 쿼리가 동작하지 않습니다. (Provider 래핑 위임을 모르심)
2. 테스트 중에 진짜 백엔드 서버에 트래픽을 찌르면 안 됩니다. 빠르고 격리된 망(Mock) 을 써야죠. MSW(Mock Service Worker)를 도입해야 합니다 (TkDodo #5).

5년 차 실무 프론트엔드 테스트의 성배, "MSW + 1 테스트 1 QueryClient 팩토리" 세팅을 파헤쳐 봅시다.

🤔 왜 알아야 하는가: 테스트 격리와 네트워크 가로채기

버튼 누르면 상태 변하는 건 누구나 테스트할 수 있습니다.
하지만 "백그라운드에서 백엔드 API를 콜해서 프로필을 그려주는 컴포넌트"를 브라우저도 없는 CI/CD 콘솔창(Terminal) 안에서 테스트하려면 난이도가 극상으로 뜁니다.

React Query 환경의 테스트가 어려운 이유는 그 강력한 장점 때문입니다.

• 캐싱(Caching)의 부작용: 테스트 A에서 생성된 캐시 데이터가, 테스트 B를 실행할 때까지 메모리(QueryCache) 에 상해(Stale) 있지 않아서 남아버립니다. (상태 오염)
• 비동기 재시도(Retry): 테스트 서버가 없어서 에러가 나면, 리액트 쿼리가 무려 3번이나 재시도를 하느라 테스트 하나당 시간이 무한정 지연됩니다.

이를 제압하는 아키텍처 옵션을 모르면, 평생 E2E(Cypress) 테스트에만 의존하며 엉성한 앱을 만들게 됩니다.

1. 전역 오염 차단: QueryClient 인스턴스 격리 테크닉

실무에서 가장 많이 저지르는 실수가 바로 "운영 코드에 있는 QueryClient를 가져와서 테스트에 넣는 짓" 입니다.
운영 코드는 전역 변수 하나를 평생 울궈먹게 캐싱(staleTime: 5분) 세팅을 해뒀기 때문에, 테스트 간 데이터 침범 버그가 작렬합니다.

✅ 해결책: 테스트 코드가 돌 때마다(매 it 이나 test 블록마다) 새삥 QueryClient를 찍어내는 래퍼(Wrapper) 함수를 만든다!

// 📝 tests/utils.tsx (테스트 헬퍼 파일)
import { render } from '@testing-library/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 
// 🚀 커스텀 렌더러 생성!
export function renderWithQueryClient(ui: React.ReactElement) {
  // 핵심: 함수가 불릴 때마다 완전히 새롭고 텅 빈 쿼리 클라이언트를 생성합니다.
  const testQueryClient = new QueryClient({
    defaultOptions: {
      queries: {
        // 테스트 환경용 세팅의 국룰: 재시도 발악을 꺼버린다! 에러 나면 즉시 실패 뜨게.
        retry: false, 
        // 옵션: 메모리 절약을 위해 캐시 청소를 초스피드로 돌립니다.
        gcTime: 0,
      },
    },
  });
 
  return {
    ...render(
      <QueryClientProvider client={testQueryClient}>
        {ui}
      </QueryClientProvider>
    ),
    // 나중에 테스트 안쪽에서 캐시를 엿봐야 할 때를 위해 인스턴스 반환
    testQueryClient,
  };
}

이제 실제 테스트(*.test.tsx) 파일에서는 이렇게 씁니다.

test('유저 프로필이 성공적으로 렌더링 되는가?', async () => {
  // 방금 만든 헬퍼로 브라우저 없이 컴포넌트 가상 마운트 완성!
  renderWithQueryClient(<UserProfile id={1} />);
  
  // 요소가 파바박- 나타날 때까지 기다립니다.
  expect(await screen.findByText('영철')).toBeInTheDocument();
});

2. API 모킹(Mocking)의 정점: MSW (Mock Service Worker)

자, 그럼 저 UserProfile 컴포넌트 안에 있는 useQuery(fetchUser) 는 도대체 어디로 네트워크 요청을 날릴까요? JSDOM 환경에서는 가고 싶어도 갈 서버가 없습니다!

이럴 때 jest.mock() 으로 axios 통신부를 거북하게 가짜 객체로 갈아끼우는 건 너무 고통스럽습니다.
TanStack Query 제작자가 제일 맹렬히 추천하는 방법은, 아예 서버(네트워크 계층) 자체를 가로채 버리는 MSW 라이브러리를 붙이는 겁니다.

MSW를 세팅하면 fetch 나 axios 코드를 1바이트도 수정하지 않은 채, 내가 쏜 네트워크 요청이 진짜 백엔드가 아닌 내 로컬 테스트가로채기 망으로 쏙쏙 빨려 들어옵니다.

// 📝 tests/mocks/handlers.ts
import { http, HttpResponse } from 'msw'
 
export const handlers = [
  // "GET /api/users/1" 요청이 날라오면, 가짜 객체를 200 OK로 반환해랏!
  http.get('https://my-api.com/users/1', () => {
    return HttpResponse.json({ name: '영철', role: 'junior' })
  }),
 
  // 옵션: 에러 상황 컴포넌트(Error Boundary) 테스트를 위해 500 에러를 쏘는 목업도 생성
  http.get('https://my-api.com/users/999', () => {
    return new HttpResponse(null, { status: 500 })
  })
]

이제 테스트 코드 환경 셋업 파일(setupTests.ts) 에서 MSW 서버를 켜줍니다.

import { setupServer } from 'msw/node'
import { handlers } from './handlers'
 
const server = setupServer(...handlers)
 
// 테스트 시작 전 목업 서버 ON
beforeAll(() => server.listen())
// 테스트마다 핸들러 리셋 (독립성)
afterEach(() => server.resetHandlers())
// 몽땅 끝나면 서버 끔
afterAll(() => server.close())

이 두 가지(QueryClient 격리 + MSW 결합)가 뭉치는 순간, 당신은 어떠한 복잡한 useInfiniteQuery 나 꼬이고 꼬인 캐싱 상황도 백엔드 연결 없이 완벽하게 프론트엔드 단독으로 블랙박스 테스트할 수 있는 신의 권능을 가지게 됩니다!

🐣 영철이의 퇴근 일기

와... 오늘 MSW 세팅해서 네트워크 가로채는 거 눈으로 보는데 소름 돋았다.
난 그동안 API 콜하는 함수 자체를 jest.spyOn().mockResolvedValue(...) 이런 식으로 어거지로 깎아서 만들었었는데, 그러니까 컴포넌트 안쪽 React Query의 캐시 로직이 진짜로 어떻게 움직이는지 테스트를 못 했던 거였어.

💡 오늘의 교훈: "React Query 컴포넌트를 테스트할 때는 1) 무조건 retry: false 옵션을 준 껍데기 1회용 빈 QueryClient를 찍어내서 주입(Provider)해 줄 것! 2) 네트워크 요청은 절대 mock 함수로 치지 말고 MSW를 붙여 서버의 행위를 재현할 것!"

이로써 리드 님이 짜주신 17개의 험난한 TanStack Query 기초/심화 가이드라인 여정이 몽땅 다 끝났다 ㅠㅠ!
이제 처음 프론트 입사했을 때 "queryKey가 뭐죠 먹는 건가요" 하던 나 영철도, 어디 가서 전역 아키텍처 캐시 금고 따고 다니는 5년 차라고 명함 내밀 수 있겠지?! 수고했다 나 자신!! 🔥 (주말엔 푹 자야지...)

📝 배운 내용 점검하기 (Quiz)

Q. 테스트 코드를 작성하던 영철이는 "에러 났을 때 Fallback 컴포넌트를 잘 그려주는가?"(에러 바운더리) 테스트를 돌리고 있었는데, Jest 콘솔 창에 빨간색 Timeout 에러가 뜨면서 무려 테스트 하나가 완료되는 데 3초 이상이 딜레이되는 현상을 겪었습니다. MSW는 정상적으로 500 에러를 뱉게 짜 놨는데도 말이죠. 이 슬로우 테스트의 근본적인 원인은 무엇입니까?

✅ 정답: 테스트를 덮어주는 QueryClientProvider 껍데기에 테스트 전용 옵션인 retry: false (재시도 끔) 세팅을 깜빡했기 때문입니다.

💡 상세 해설:

• 원리 설명: TkDodo 아티클 #5의 핵심! React Query의 엄청난 강점인 "API 요청 실패 시 기본 3번 재시도 (Exponential Backoff 지연시간 포함)" 기능은, 야속하게도 테스트 환경(Node.js)에서도 똑같이 동작합니다. MSW가 500 에러를 주면, React Query는 "어? 에러 났어? 잠깐 기다려봐. 1초 뒤에 다시 찔러볼게... 또 에러 나네? 2초 뒤에 다시..." 하면서 테스트 창을 하염없이 멈춰 세웁니다. 결국 3번 발악을 다 끝내고 완전히 장렬히 전사했을 때에야 컴포넌트 쪽에 에러 결과값을 넘겨주며 3초를 허비하게 되는 것입니다.
• 오답 피드백: "영철 님, 테스트 프레임워크가 느린 게 아닙니다! React Query가 살려보려고 뒤에서 식은땀 흘리면서 재시도(Retry) 하고 있는 거예요. 테스트 렌더 헬퍼의 쿼리 옵션에 무조건 retry: false 한 줄을 수혈해서 1트만에 즉사(?)하도록 만드셔야 숨 막히는 테스트 병목 지연을 박살 낼 수 있습니다."
• 📌 핵심 기억법: 테스트 환경의 QueryClient는 무조건 자비 없는 노가다 방지, retry: false!