React Testing Library 실전 설계 가이드

React Testing Library의 가치는 단순히 React 컴포넌트를 렌더링할 수 있다는 점이 아닙니다. 핵심은 **테스트를 컴포넌트 내부 구현이 아니라 사용자가 실제로 관찰할 수 있는 결과에 묶어 두게 만든다**는 데 있습니다.

그래서 RTL은 UI 행동 검증에 강하고, 컴포넌트 내부 구조를 증명하려는 테스트에는 맞지 않습니다.

먼저 보이는 행동을 테스트해야 합니다

건강한 RTL 테스트는 보통 다음을 묻습니다.

• 사용자가 무엇을 볼 수 있는가
• 무엇을 클릭하거나 입력하거나 선택할 수 있는가
• 그 상호작용 뒤에 화면에서 무엇이 바뀌는가

그래서 다음 같은 assertion이 더 강합니다.

• validation 에러가 보인다
• loading indicator가 나타났다가 사라진다
• 저장 후 성공 상태가 보인다
• 입력이 잘못되면 버튼이 비활성화된다

이런 검증은 component state를 직접 들여다보는 테스트보다 리팩터링에 오래 버팁니다.

Query 우선순위가 중요합니다

RTL은 사용자가 요소를 찾는 방식과 접근성 도구의 기준을 따라갈 때 가장 강합니다.

보통 좋은 우선순위는 다음과 같습니다.

• getByRole
• getByLabelText
• getByText
• getByPlaceholderText
• 의미 기반 query가 부족할 때만 test ID

querySelector나 취약한 DOM 탐색에 많이 기대는 테스트는 대개 사용자 중심 검증에서 멀어지고 있다는 신호입니다.

저수준 이벤트보다 실제 상호작용을 써야 합니다

userEvent는 보통 저수준 이벤트를 직접 발생시키는 것보다 더 현실적인 사용자 의도를 모델링합니다.

특히 다음에서 차이가 큽니다.

• 입력 타이핑
• 포커스 이동
• 클릭 상호작용의 순서
• 키보드 탐색

저수준 이벤트도 필요할 수 있지만, 이를 기본값으로 두면 테스트가 실제 사용자 흐름과 멀어지기 쉽습니다.

비동기 UI는 기다림 규율이 필요합니다

현대 React UI는 다음을 자주 포함합니다.

• loading state
• 지연 렌더링
• 서버 데이터 fetch
• 비동기 검증

그래서 RTL 테스트는 보통 다음을 잘 써야 합니다.

• 나중에 나타나는 요소는 findBy...
• 조건 기반 대기는 waitFor
• loading과 settled state를 모두 명시적으로 검증

임의의 타이밍 트릭은 테스트를 더 약하고 flaky하게 만듭니다.

공통 render helper는 보일러플레이트만 줄여야 합니다

많은 React 테스트는 routing, theme, query client, state store 같은 provider가 필요합니다. 공통 render utility는 유용하지만, setup 의미를 감추면 오히려 해롭습니다.

좋은 render helper는:

• 필요한 provider를 일관되게 제공하고
• 테스트를 짧게 유지하며
• 시나리오별 override를 허용합니다

나쁜 helper는 실제로 어떤 환경에서 렌더링되는지 이해하기 어렵게 만듭니다.

컴포넌트 세계를 과도하게 mocking하지 말아야 합니다

RTL 테스트는 child component, hook, dependency를 과도하게 mock하기 시작하면 가치가 크게 줄어듭니다.

mock가 잘 맞는 곳은 진짜 외부 경계나 불안정한 의존성입니다.

• 네트워크 요청
• 테스트 환경에 없는 브라우저 API
• 비싼 통합 경로

중요한 행동 자체가 사라질 정도로 mock를 많이 쓰면 RTL의 장점이 약해집니다.

흔한 안티패턴

실무에서는 다음 패턴이 자주 테스트를 약하게 만듭니다.

• component state를 직접 검사
• 의미 기반 query 대신 CSS selector 의존
• child component를 과도하게 mock
• 비동기 UI에서 loading state 검증 생략
• setup 의미를 가리는 거대한 render helper

이런 패턴은 테스트를 brittle하고 신뢰하기 어렵게 만듭니다.

리뷰 체크리스트

RTL 스위트가 건강한지 보려면 다음을 물어야 합니다.

• 사용자가 실제로 관찰할 수 있는 결과를 검증하는가
• query가 semantic하고 의도가 드러나는가
• 비동기 상태를 timing hack 대신 조건으로 다루는가
• render helper가 setup을 숨기지 않고 드러내는가
• mock가 진짜 불안정한 경계에만 제한되는가

마무리

RTL은 React 테스트를 다시 사용자 관점으로 돌려놓는 도구입니다. 보이는 결과에 기준을 둘수록 테스트는 리팩터링 이후에도 더 오래 살아남고, 더 유용한 신뢰를 제공합니다.

Continue Reading

다음으로 읽기 좋은 글

🧪 Test

Mock, Stub, Spy 테스트 더블 설계 가이드

Mock, Stub, Spy를 언제 어떤 기준으로 선택해야 하는지 정리합니다. 상태 검증과 상호작용 검증의 차이, 과도한 mocking의 위험, fake와의 선택 기준까지 실무 관점에서 다룹니다.

🧪 Test

TDD 실천 가이드: Red-Green-Refactor

TDD를 순서 암기가 아니라 설계 피드백 루프로 보고, Red-Green-Refactor의 의미, 잘 맞는 문제와 과한 문제, 팀에서 지속 가능하게 적용하는 방법을 정리합니다.

🖥️ Frontend

React Server Components 완전 정복 — RSC와 Server Actions

React Server Components를 개념 소개 수준이 아니라 아키텍처 선택의 관점에서 정리합니다. Client Component와의 경계 설정, Server Actions, 캐싱, 스트리밍, 실무에서 자주 겪는 함정까지 Next.js App Router 기준으로 설명합니다.

🖥️ Frontend

스트리밍 UI의 실패 복구 패턴

부분 렌더링, 서버 스트리밍, AI 응답 UI에서 중간 실패를 사용자 경험으로 흡수하는 설계 방법을 정리합니다.