React Native 테스트 스위트는 모두 통과했지만, 실제 기기에서 사용자가 '계속' 버튼을 탭해도 아무 반응이 없다고 보고합니다. 컴포넌트 테스트는 버튼을 찾고 핸들러를 호출했으며, 모킹된 JavaScript 환경에서 예상된 화면을 확인했습니다. 하지만 네이티브 권한 프롬프트, 키보드 동작, 애니메이션, 플랫폼 API, 실제 내비게이션 스택은 검증하지 않았습니다.
그 간극에서 팀들은 잘못된 확신을 갖게 됩니다. React Native Testing Library React Native Testing Library는 컴포넌트가 어떻게 렌더링되고 사용자 상호작용에 어떻게 반응하는지 테스트하는 데 탁월하지만, 디바이스 테스트나 성능 측정의 대안은 아닙니다. 신뢰할 수 있는 전략은 각 계층이 드러낼 수 있는 실패 유형에 맞춰 해당 계층을 활용하는 것입니다.
목차
- 사용자 중심 테스트가 모든 것을 바꾸는 이유
- 실제로 작동하는 설치 및 설정
- 핵심 API: Queries와 Assertions 설명
- 컴포넌트, Hook, Navigation을 위한 실전 패턴
- Flaky Test 디버깅, CI 및 성능 체크
- 종합 및 향후 방향
사용자 중심 테스트가 모든 것을 바꾸는 이유
흔히 발생하는 테스트 실패는 테스트 코드를 작성하기 전부터 시작됩니다. 개발자는 검증하기 쉬운 세부 사항에 매몰되어 컴포넌트의 props를 조사하거나, 내부 state에 접근하거나, 거대한 스냅샷을 비교하곤 합니다. 이렇게 하면 테스트는 통과하지만, 사용자 경험은 그대로인데 컴포넌트 구조만 리팩터링해도 테스트가 깨지게 됩니다. 더 심각한 건, 테스트가 계속 통과해도 사용자에게 보이는 동작은 잘못될 수 있다는 점입니다. assertion이 사용자가 봐야 할 동작을 제대로 설명하지 않았기 때문입니다.
React Native Testing Library는 이와 정반대의 접근 방식을 취합니다. 컴포넌트를 렌더링하고, 눈에 보이는 컨트롤을 통해 상호작용한 뒤, 사용자가 볼 수 있는 결과를 검증합니다. 이러한 접근 방식은 React Native Testing Library의 사용자 중심 예시와, 그리고 테스트를 간결하게 유지하고, 각 테스트를 한 가지에만 집중하며, 뷰 관련 관심사를 비즈니스 로직 및 state와 분리하고, 내부 구현 세부 사항보다는 눈에 보이는 출력이나 accessibility helper를 우선시하라는 React Native의 테스트 가이드를 모두 충족합니다.
사용자가 의존하는 동작을 테스트하세요
로그인 폼이 요청이 진행되는 동안 제출 버튼을 비활성화한다고 가정해 봅시다. 취약한 테스트라면 disabled 특정 컴포넌트 인스턴스를 확인하거나 상태 변수가 변경되었는지 검증합니다. 더 강력한 테스트는 접근성 있는 “Sign in” 컨트롤을 누르고, 로딩 인디케이터를 기다린 뒤, 에러 메시지나 목적지 화면이 나타나는지 확인합니다.
두 번째 테스트는 폼이 로컬 state를 사용하는지, reducer를 쓰는지, 커스텀 hook이나 다른 버튼 구현체를 사용하는지는 신경 쓰지 않습니다. 오직 앱이 올바른 결과를 전달하는지에만 집중합니다.
실무 원칙: 사용자가 관찰할 수 없는 것이라면, 컴포넌트 동작 테스트에 포함되어야 할지 고민해 보세요.
접근성 레이블과 역할 기반의 쿼리는 더 나은 제품 code를 이끌어냅니다. 의미 있는 레이블을 노출하는 화면은 보조 기술로 사용하기 더 쉽고 테스트에서 실행하기도 더 쉽습니다. 이 연결은 더 넓은 범위의 앱 사용자 경험을평가할 때 중요합니다. 테스트 가능성과 사용성은 종종 함께 향상되기 때문입니다.
통과한 테스트가 증명하지 못하는 것을 알아두세요
사용자 중심의 컴포넌트 테스트는 JavaScript가 예상되는 분기를 렌더링하고 시뮬레이션된 press에 반응하는지 증명할 수 있습니다. 하지만 생체 인증 prompt가 올바르게 열리는지, 네이티브 카메라가 사용 가능한 결과를 반환하는지, 또는 결제 흐름이 플랫폼별 라이프사이클 동작에서도 유지되는지는 증명할 수 없습니다.
이러한 경계는 라이브러리의 약점이 아닙니다. 오히려 테스트 레이어를 제 역할에 충실하게 유지해야 하는 이유입니다. 컴포넌트 동작에는 RNTL을 사용하고, 네이티브 통합, 실제 네비게이션, 권한, 인증, 결제 또는 핵심 앱 기능이 결과에 영향을 줄 수 있는 흐름에는 디바이스 기반 테스트를 사용하세요.
실제로 작동하는 설치 및 설정
최신 설정은 스코프 패키지로 시작합니다:
@testing-library/react-native예전 react-native-testing-library npm 패키지 이름은 과거의 흔적으로 남아 있지만, 현재 프로젝트에서는 Testing Library 계열에서 관리하는 스코프 패키지를 사용해야 합니다. 이 프로젝트의 GitHub 리포지토리 설명에 따르면 좋은 테스트 관행을 장려하기 위한 React Native 유틸리티이며, 릴리스 기록을 보면 이 라이브러리가 정적인 헬퍼에 머물지 않고 React Native와 함께 계속 변화해 왔음을 알 수 있습니다.
기존 Jest 환경에 라이브러리를 설치하세요. Expo 프로젝트는 보통 Expo Jest preset을 사용하는 반면, bare React Native 프로젝트는 React Native preset을 사용할 수 있습니다:
npm install --save-dev @testing-library/react-native jestExpo라면 프로젝트에서 이미 사용 중인 preset을 추가하세요:
{
"scripts": {
"test": "jest"
},
"jest": {
"preset": "jest-expo"
}
}bare React Native 애플리케이션이라면 대신 해당 React Native Jest 설정을 사용하세요. preset은 프레임워크 버전에 맞춰 유지하세요. RNTL 문제처럼 보이는 많은 실패는 React renderer, Babel transform 또는 Jest preset의 불일치에서 비롯됩니다.
설정 파일은 명시적으로 관리하세요
모든 테스트에서 mock을 반복하지 말고, 공유 환경 설정은 setup 파일에 두세요:
// jest.setup.js
import '@testing-library/react-native/extend-expect';그런 다음 Jest에서 참조하세요:
{
"jest": {
"preset": "jest-expo",
"setupFilesAfterEnv": ["<rootDir>/jest.setup.js"]
}
}앱에 React Navigation, Reanimated, 제스처 처리, safe-area context 또는 storage 모듈을 사용하는 경우, 테스트 환경에 필요한 mock만 설정하세요. 애플리케이션 동작을 변경하는 전역 mock은 모든 테스트를 통과하기 쉽게 만들 수 있지만, 테스트 스위트의 신뢰성을 떨어뜨릴 수 있습니다.
TypeScript에도 동일한 주의가 필요합니다. Jest가 .ts 및 .tsx 파일을 preset 또는 Babel 설정을 통해 변환하도록 하고, 컴파일러가 테스트 타입에 접근할 수 있도록 유지하세요. 로컬에서는 실행되지만 타입 체크가 되지 않는 테스트는 잘못된 쿼리 이름, 잘못된 내비게이션 파라미터, 또는 안전하지 않은 mock 구조를 숨길 수 있습니다.
릴리스 연대기는 오래된 설정 조언을 진단할 때 유용합니다. 프로젝트는 127개의 릴리스를, 그중 2026-06-23에 태그된 v14.0.1을, 반면 2024-11-27에 출시된 v12.9.0은 React Native 0.77과 Expo 52에 대한 공식 지원을 추가했습니다. 2025년 3월의 v14 알파 버전은 비추천된 React Test Renderer에서 Universal Test Renderer로 전환하고 React 19 전용 지원을 준비했습니다. 이러한 세부 사항은 RNTL 릴리스 히스토리, 따라서 앱 버전을 확인하지 않고 오래된 튜토리얼의 renderer 의존성을 그대로 복사하지 마세요.
실용적인 Jest 기반을 다지려면, 이 내용과 설정을 비교해 보세요. JavaScript 유닛 테스트 가이드, 그다음 navigation 및 native mock을 추가하기 전에 작은 컴포넌트 테스트를 하나 실행하세요.
핵심 API: Queries와 Assertions 설명
RNTL 테스트는 query가 사용자가 보고, 찾고, 조작할 수 있는 요소와 일치할 때 신뢰할 수 있습니다. API 자체는 작지만, 구현 세부 사항을 드러내는 selector를 선택하면 통과된 테스트가 오해를 불러일으킬 수 있습니다.
시작하기 render:
const screen = render(<LoginForm />);사용자와 가장 관련성 높은 query를 선택하세요. 컴포넌트가 노출한다면 접근성 중심 query를 우선 사용하고, 텍스트가 동작을 나타낸다면 보이는 텍스트를 사용하세요. 그리고 testID 의미 있는 사용자 대상 selector가 없거나 안정적인 integration hook이 필요한 경우에만 사용하세요.
타이밍과 의도에 따라 query 선택하기
각 쿼리 계열은 서로 다른 목적을 가집니다:
- 동기적 존재 확인: 사용
getByRole,getByText, 또는 다른getBy쿼리는 요소가 이미 존재해야 할 때 사용합니다. 요소가 없으면 테스트가 즉시 실패합니다. - 비동기적 등장 확인: 사용
findByRole또는findByText렌더링이나 상호작용으로 비동기 업데이트가 발생할 때 사용합니다. - 부재 확인: 사용
queryByText또는queryByTestId요소가 없을 수 있고 예외 대신 null 결과가 예상될 때. - Fallback 셀렉터: 사용
getByTestId의도적으로 사용합니다. 복잡한 컨트롤에 내구성 있는 훅을 제공하지만, 앱 전체의 접근성 라벨을 대체해서는 안 됩니다.
집중된 이벤트 테스트의 경우, fireEvent.press 직접적입니다:
fireEvent.press(screen.getByRole('button', { name: 'Save' }));사용 userEvent 설치된 버전이 더 현실적인 상호작용 시퀀스를 지원할 때. 어느 쪽이든 결과 UI를 assert하세요:
expect(await screen.findByText('Saved')).toBeTruthy();핸들러 어설션은 공개 계약이 이벤트 콜백인 컴포넌트에 적합합니다. 사용자 여정이 정상 작동한다는 유일한 근거로는 약합니다.
스냅샷보다 구체적인 assertion을 사용하세요
좋은 어설션은 화면을 설명합니다:
expect(screen.getByText('Account created')).toBeTruthy();
expect(screen.getByRole('button', { name: 'Continue' })).toBeEnabled();접근성 상태, 선택, 표시되는 검증 피드백도 검증할 수 있습니다. 내부 연결을 확인하는 것은 피하세요:
expect(screen.getByTestId('submit-button').props.onPress).toBeDefined();그 단언은 prop이 존재한다는 것만 증명할 뿐, 기능이 작동한다는 것을 증명하지는 않습니다. 작고 의도적인 스냅샷은 구조적 변경을 잡아낼 수 있지만, 큰 네비게이션이나 화면 스냅샷은 노이즈가 많은 리뷰를 만들고 설명 없는 업데이트를 쉽게 승인하게 만듭니다.
Testing Library 패키지는 더 큰 testing-library npm 조직에 속합니다. 활성 패키지에는 @testing-library/react-native, 버전은 2026년에 게시된 13.3.3입니다, 프로젝트의 저장소 정보에 따릅니다. 공통 쿼리 컨벤션은 플랫폼 전반에 도움이 되지만, 어떤 단언이 제품 동작을 나타내는지는 결정하지 않습니다.
Jest 컴포넌트 테스트 관행을 더 폭넓게 비교하려면 다음 가이드를 참고하세요: React 단위 테스트. RNTL은 여전히 JavaScript로 렌더링된 컴포넌트 경계까지만 다룹니다. 네이티브 권한, 실제 네비게이션 스택, 디바이스 키보드, 프레임 타이밍, 메모리 동작은 더 많은 컴포넌트 모킹 대신 E2E 또는 성능 도구가 필요합니다.
아래 영상은 실제 맥락에서 쿼리와 단언 워크플로우를 보여줍니다.
컴포넌트, Hook, Navigation을 위한 실전 패턴
유용한 테스트 스위트는 애플리케이션의 구조를 따라야 합니다. 프레젠테이션 컴포넌트는 직접적인 동작 테스트가 필요하고, 훅은 제어된 입력과 출력이 필요하며, 네비게이션은 충분히 현실적인 프로바이더가 필요합니다. 또한 네이티브 모듈은 실제 기기 검증과 명확히 구분되는 모킹이 필요합니다.
Presentational 컴포넌트
컴포넌트 테스트는 공개 인터페이스에 가깝게 유지하세요:
const onSelect = jest.fn();
render(
<PlanCard
title="Team"
description="Shared workspace"
onSelect={onSelect}
/>
);
fireEvent.press(screen.getByRole('button', { name: 'Choose Team' }));
expect(onSelect).toHaveBeenCalled();레이블은 실제 UI와 정확히 일치해야 합니다. 중요한 점은 테스트가 사용자나 접근성 서비스가 하는 방식으로 컨트롤을 찾고, 중요한 보이는 결과나 콜백 결과를 확인하는 것입니다. 기본적으로 모든 자식 컴포넌트를 모킹하지 마세요. 테스트 중인 동작을 가릴 때만 비용이 크거나 관련 없는 경계를 모킹하세요.
커스텀 훅에는 다음을 사용하세요: renderHook 설치된 RNTL 버전에서 지원하는 경우:
const { result } = renderHook(() => useSearch());
await act(async () => {
await result.current.submit('query');
});
expect(result.current.status).toBe('success');훅 테스트는 앱 전체를 재현하는 것이 아니라 네트워크나 레포지토리 경계를 제어해야 합니다. 훅의 상태가 유용한 UI로 이어지는지 알 수 있도록 스크린은 별도로 테스트하세요.
Navigation과 비동기 데이터
네비게이션 동작의 경우, 실제 내비게이션 안에 스크린을 렌더링하는 것과 NavigationContainer 작은 테스트 네비게이터를 사용하는 것이 모든 네비게이션 메서드를 모킹하는 것보다 더 가치 있는 경우가 많습니다. 보이는 컨트롤을 누르고, 목적지 콘텐츠가 나타날 때까지 기다린 후, 새 스크린의 출력을 검증하세요. 직접적인 useNavigation 타입이 지정된 라우트만 디스패치하는 작은 버튼에는 mock이 여전히 적절하지만, 라우트 등록, 파라미터, 또는 중첩 내비게이터 동작은 검증하지 못합니다.
비동기 데이터에도 동일한 규율이 필요합니다. API 또는 리포지토리 응답을 mock하고, 화면을 렌더링한 후 로딩 상태를 assert합니다. 요청을 resolve한 뒤 성공 또는 에러 출력을 assert하세요. 사용 findBy 예상되는 최종 요소에는 queries를 사용하고, 거부된 요청은 명시적으로 처리하세요. 그렇지 않으면 컴포넌트가 의도된 분기에 도달하지 못해도 테스트가 통과할 수 있습니다.
Native module 모킹
AsyncStorage, 권한, 카메라, 생체 인증, 플랫폼 API에 대한 mock은 결정론적인 JavaScript 테스트에 유용합니다. 하지만 네이티브 기능이 실제로 작동한다는 증거는 아닙니다. mock 동작은 모듈 계약에 가깝게 유지하고, 테스트 간에 호출을 리셋하며, 정상 경로만 모델링하지 말고 실패 응답도 포함하세요.
| 시나리오 | RNTL과 가장 잘 어울리는 경우 | E2E 검증이 필요한 경우 |
|---|---|---|
| 폼 검증 및 오류 표시 | 지원 | 보통은 아닙니다 |
| 모킹된 리포지토리의 로딩, 성공, 오류 UI | 지원 | 중요한 프로덕션 플로우용 |
| 등록된 스크린 간의 네비게이션 | 네, 테스트 네비게이터로 가능 | 네, 제스처, 딥링크, 플랫폼 동작이 중요할 때 가능 |
| AsyncStorage 상태 결정 로직 | 네, 제어된 mock으로 가능 | 네, 앱 실행과 영속성이 네이티브 라이프사이클과 상호작용할 때 가능 |
| 카메라, 생체 인식, 권한 또는 플랫폼 API | JS 폴백 및 분기 로직 | 네, 실제 또는 대표 기기에서 가능 |
| 레이아웃, 렌더링 성능 및 네이티브 code | 아니요 | 네, 디바이스나 전문 도구를 사용하면 가능합니다. |
실용적인 경계는 이렇습니다: 의존성을 mock으로 처리해 JavaScript 로직을 테스트한 다음, 디바이스 테스트로 의존성의 실제 동작을 확인하세요.
Flaky Test 디버깅, CI 및 성능 체크
Flaky 테스트는 대개 제어되지 않는 시간, 공유 상태, 또는 UI와 경합하는 assertion 때문에 발생합니다. 타임아웃을 늘리기 전에 어떤 조건이 문제인지 먼저 파악하세요. 타임아웃만 늘리면 스케줄링 문제를 숨기게 되어 전체 테스트 스위트가 느려질 수 있습니다.
사용 findBy 업데이트 후 나타날 것으로 예상되는 요소에는 다음을 사용하세요. waitFor 상태 조건이나 mock 호출에는 다음을 사용하세요. Fake timer가 활성화되어 있다면 상호작용이 필요한 시점에 타이머를 진행시키고, 이후에는 실제 타이머로 복구하세요. act 경고가 발생했다는 것은 React가 예상된 상호작용 경계 밖에서 업데이트를 감지했다는 의미입니다. 누락된 await, 사용자 상호작용 또는 타이머 flush를 수정하세요. 경고를 억제하지 마세요.
CI 실패를 재현 가능하게 만들기
신뢰할 수 있는 CI 작업은 lockfile을 통해 설치하고, 로컬에서 사용한 것과 동일한 Jest 명령어를 실행하며, mock 상태를 격리합니다. 테스트 사이에 mock 호출을 초기화하고, 모듈 수준의 상태가 동작에 영향을 준다면 모듈을 리셋하며, 실행 순서에 의존하지 않도록 하세요. Jest 캐싱은 피드백 속도를 높여주지만, 의존성이나 설정이 변경되면 적절한 캐시 무효화가 필요합니다.
CI에서만 발생하는 실패는 컴포넌트 재작성 전에 환경 비교가 필요합니다. Node, 패키지 매니저, Jest 워커 설정, 타이머 구성, 환경 변수를 확인하세요. 가능하면 로컬에서 동일한 명령을 재현한 후, 차이를 드러내는 최소 상호작용으로 실패하는 테스트를 축소하세요.
Observability는 다른 공백을 다룹니다. 앱 헬스 모니터링 실제 디바이스와 네이티브 통합과 관련된 실패를 포함하여, 목(mock)된 컴포넌트 테스트로 재현할 수 없는 프로덕션 에러 컨텍스트를 제공합니다.
보안 민감한 여정에는 두 번째 경계가 필요합니다. 검증과 상태 전이에 컴포넌트 테스트를 사용하고, 핸드오프와 네이티브 동작에 디바이스 레벨 커버리지를 추가하세요. 일회용 code 플로우의 경우, 해당 통합이 여정의 일부일 때 어떻게 SMS 인증 플로우를 테스트하는지 가이드를 참조하세요.
성능을 주장이 아닌 측정으로 다루기
기능 테스트는 목록이 렌더링되는지 확인할 수 있지만, 리팩토링으로 렌더링 시간이나 렌더링 횟수가 변경되었는지 신뢰할 수 있게 판단하기 어렵습니다. 테스트 런타임이 노이즈를 추가하기 때문입니다. Reassure는 시나리오에 대해 해당 값을 측정하고, 시나리오를 반복하여 편차를 줄인 후, 통계적 분석을 적용하여 의미 있는 변경 사항을 보고합니다. 이 도구의 성능 테스트 문서 에는 CI 및 풀 리퀘스트 리뷰에 적합한 보고 방식도 다루고 있습니다.
“이 렌더링은 정해진 임계값 이내에 완료되어야 한다”와 같은 고정된 단언은 피하세요. CI 워커가 바쁘면 거짓 실패가 발생할 수 있고, 임계값이 느슨하면 실제 회귀를 놓칠 수 있습니다. 회귀 신호에는 반복 측정을 사용하고, 비교에서 유의미한 차이가 보이면 컴포넌트와 디바이스 프로필을 점검하세요.
측정 규칙: 기능 테스트는 동작이 올바른지를 확인합니다. 성능 도구는 측정된 시나리오가 변했는지를 확인합니다. 이 두 질문은 분리해서 다루세요.
종합 및 향후 방향
React Native Testing Library는 테스트 전략에서 넓고 빠른 계층에 속합니다. 컴포넌트 동작, 가시적인 상태 변화, 접근성 결과, 유효성 검사, 모킹된 데이터 상태, JavaScript 컴포넌트 간 통합을 다뤄야 합니다. 이런 테스트는 사용자가 관찰할 수 있는 것에 집중하고, 실패 시 거대한 렌더링 트리 전체가 아닌 특정 동작을 지목하도록 만드세요.
모킹이 실제와 다를 수 있는 흐름은 더 작은 디바이스 기반 계층에서 보호해야 합니다. React Native의 테스트 개요 RNTL은 완전한 React Native 런타임을 제공하지 않으며 네이티브 기능을 테스트할 수 없다고 명시합니다. 같은 가이드에서 인증, 결제, 핵심 앱 기능 등 중요한 흐름에는 컴포넌트 테스트와 함께 Detox 같은 E2E 도구를 사용하도록 권장합니다.
실용적인 마이그레이션 경로
기존 테스트 스위트를 한 번에 모두 다시 작성할 필요는 없습니다.
- 가치 있는 비즈니스 테스트는 유지하세요. 순수 상태 및 도메인 로직은 명확한 피드백을 주는 집중된 단위 테스트로 옮기세요.
- 먼저 구현 세부 사항에 대한 단언을 교체하세요. props와 내부 상태 검사를 화면에 보이는 출력, 접근성 상태, 상호작용 결과로 바꾸세요.
- 스냅샷 크기를 줄이세요. 리뷰어가 이해하고 유지보수할 수 있는 스냅샷만 남기세요.
- 네이티브 경계 커버리지를 추가하세요. 모킹된 주요 모듈마다, 여전히 검증이 필요한 디바이스 동작이 무엇인지 파악하세요.
- 핵심 사용자 여정을 보호하세요. 인증, 결제, 핵심 네비게이션, 권한 등 네이티브 동작이 결과를 바꿀 수 있는 흐름에 E2E 커버리지를 추가하세요.
- 민감한 화면은 별도로 측정하세요. Jest 실행 시간으로 추측하는 대신, 리스트, 피드, 비용이 큰 렌더링 경로에 대해 반복적인 성능 비교를 수행하세요.
릴리스 신뢰성을 위해 스위트를 CI/CD 통합 테스트는 에 연결하고, 배포 전에 적절한 테스트 레이어를 필수로 요구하세요. 검증 후 JavaScript 또는 에셋 수정 사항을 사용자에게 전달해야 한다면, Capgo는 CapacitorJS 및 Electron 애플리케이션의 타깃 채널에 서명된 웹 번들을 배포할 수 있으며, 롤아웃 제어와 롤백 보호 기능을 갖추고 있습니다. 이 배포 워크플로우는 React Native 디바이스 테스트를 대체하지는 않지만, 같은 원칙을 보여줍니다: 동작이 실제로 실행되는 레이어에서 검증하세요.
올바른 질문은 React Native Testing Library가 앱 전체를 테스트할 수 있는지 여부가 아닙니다. 테스트할 수 없으며, 공식 경계가 유용합니다. 올바른 질문은 각 중요한 리스크마다 이를 드러낼 수 있는 환경에서 테스트가 실행되고 있는지 여부입니다.
Capgo는 검증된 JavaScript 및 에셋 변경 사항을 CapacitorJS 및 Electron 팀을 위한 제어된 배포로 연결하며, 타깃 채널, 롤아웃 가시성, 롤백 보호 기능을 제공합니다. 방문하여 Capgo 컴포넌트, E2E, CI 테스트 워크플로우와 함께 어떻게 활용될 수 있는지 확인하세요.
