핵심 사용자 흐름의 회귀를 빠르게 발견하면서, 테스트 작성과 유지보수 비용을 관리한다. 테스트는 구현 세부 사항보다 사용자가 경험하는 결과와 비즈니스 규칙을 검증한다.
프로젝트에는 다음 테스트 환경이 구성되어 있다.
- Jest와
jest-expo @testing-library/react-native- React Query Provider를 포함하는
renderWithProviders axios-mock-adapter
테스트 파일은 대상 파일과 같은 폴더에 *.test.ts 또는 *.test.tsx로 둔다. JSX가 포함되면 .test.tsx, 순수 로직만이면 .test.ts를 사용한다.
- 사용자 행동과 비즈니스 규칙을 기준으로 테스트한다.
- 사용자에게 관찰되는 결과와 비즈니스 규칙을 우선적으로 검증한다.
- 정상·경계·실패를 기준으로 사례를 설계한다.
- 같은 동작을 여러 테스트 계층에서 중복 검증하지 않는다.
- 테스트 코드의 유지보수 비용도 구현 범위를 결정하는 기준으로 삼는다.
| 대상 | 테스트 방식 | 우선순위 | 예시 |
|---|---|---|---|
| 순수 로직 | 단위 테스트 | 높음 | validation, Zod schema, mapper, payload adapter |
| API 훅 | 훅 테스트와 API 경계 mock | 높음 | 요청 성공, 실패, 로딩, 활성화 조건 |
| UI 컴포넌트 | 컴포넌트 테스트 | 중간 | 입력, 버튼 활성화, 오류·성공 UI |
| 핵심 사용자 흐름 | E2E 테스트 | 도입 후 검토 | 로그인, 회원가입, 지도 검색, 리뷰 작성 |
각 계층은 자신이 가진 책임만 검증한다. 예를 들어 API 응답 mapper는 순수 함수 단위 테스트로 검증하고, API 훅에서는 loading·success·error 같은 React Query 상태 변화를 검증한다.
기능 이름으로 계층을 고정하지 않고, 검증하려는 책임으로 계층을 선택한다. 같은 도메인 규칙도 범위에 따라 여러 계층의 후보가 될 수 있다.
| 검증하려는 책임 | 적절한 계층 | 예시 |
|---|---|---|
| 외부 의존성 없이 입력과 결과만으로 확인 가능한 규칙 | 단위 테스트 | 필수 약관 동의 조건, schema, payload 변환 |
| API·타이머·폼 상태 등 상태 변화와 의존성 연결 | 훅 테스트 | 인증 발송·검증 성공 또는 실패 후 상태 변화 |
| 사용자 입력·탭 후 화면에 보이는 상태 변화 | 컴포넌트 테스트 | 조건부 입력칸, 버튼 활성화, 오류 메시지 |
| 여러 계층을 연결한 사용자 여정 | E2E 후보 | 역할 선택부터 가입 완료까지 |
단계 순서는 순수 로직으로 결정될 때만 단위 테스트다. 실제 버튼 클릭, 화면 전환, API 응답까지 포함하면 컴포넌트 테스트 또는 E2E 후보로 분류한다. 약관도 동의 규칙은 단위, 체크 UI는 컴포넌트, 가입 완료까지의 여정은 E2E 후보로 나눈다.
단위·컴포넌트 테스트로 기본 회귀 방어선을 만든 뒤, 가장 중요한 사용자 흐름에 한정해 E2E를 도입한다. 모든 화면을 E2E로 만들지 않는다.
테스트 대상은 비즈니스 영향, 변경 가능성, 실패 비용을 종합적으로 고려하여 우선순위를 정한다.
| 기능 | 비즈니스 영향 | 변경 가능성 | 실패 비용 | 우선순위 |
|---|---|---|---|---|
| 회원가입 검증 | 높음 | 높음 | 높음 | 높음 |
| 지도 검색 API | 높음 | 높음 | 중간 | 높음 |
| 단순 UI 텍스트 | 낮음 | 낮음 | 낮음 | 낮음 |
각 대상에 대해 구현 전 아래 세 범주를 먼저 정리한다.
| 범주 | 확인할 내용 |
|---|---|
| 정상 | 사용 가능한 입력이나 성공 응답에서 기대 결과가 나오는지 |
| 경계 | 빈 값, 제한 시간 만료, 공백 문자열, 선택값 누락 같은 경계 조건을 안전하게 처리하는지 |
| 실패 | API 오류, 권한 거부, 잘못된 입력에서 사용자에게 올바른 상태를 보여 주는지 |
예를 들어 회원가입 단계 검증은 인증번호 발송 여부와 남은 시간, 역할 선택, 필수 동의, 파일 업로드 여부처럼 다음 단계 이동을 차단하거나 허용하는 조건을 검증한다.
- 비즈니스 로직은 입력과 결과가 명확한 단위 테스트부터 작성한다.
- UI 테스트는 내부 state, 함수 호출 횟수, 컴포넌트 구조 대신 사용자가 보는 텍스트·상태·상호작용을 검증한다.
- 외부 네트워크에 의존하지 않도록 API 경계를 mock한다. 현재 프로젝트에서는
axios-mock-adapter를 사용한다. - 테스트 파일도 해당 FSD slice의 일부로 취급한다. FSD 의존성 규칙을 유지하며, 테스트 전용 코드가 상위 레이어를 참조하지 않도록 한다.
- 테스트를 편하게 만들기 위한 과도한 프로덕션 코드 리팩터링은 피한다. 테스트 가능성을 높이는 작은 분리는 기능 요구와 함께 검토한다.
- 테스트 이름은 하나의 중요한 사용자 행동이나 비즈니스 규칙을 명확하게 설명한다.
Jest로 함수를 직접 호출한다. 외부 상태나 UI 렌더링 없이 빠르고 안정적으로 실행되어야 한다.
대상 예시:
validation.tssignupStepSchemas.tssignupPayloadAdapters.ts- API 응답 mapper
React Native Testing Library의 훅 테스트와 renderWithProviders를 사용한다. API 경계를 mock해 성공·실패 응답을 만들고, 로딩·성공·오류 상태와 캐싱, 활성화 조건, 재요청 등 사용자 동작에 영향을 주는 훅의 동작을 검증한다. 응답 변환은 API 훅이 아니라 mapper의 순수 함수 테스트에서 검증한다.
사용자 관점으로 렌더링하고 입력 또는 탭을 수행한다. 폼 입력값에 따라 버튼이 활성화되는지, 오류 메시지와 로딩 상태가 올바른지 확인한다.
다음은 중요한 회귀를 막는 데 비해 유지보수 비용이 크므로 기본적으로 테스트하지 않는다.
- 단순 스타일과 레이아웃 구조
- React 및 외부 라이브러리 자체의 동작
- 단순 props 전달만 수행하는 컴포넌트
- 내부 함수 호출 횟수처럼 구현 세부 사항에 해당하는 동작
- 동일한 동작을 여러 계층에서 반복 검증하는 테스트
테스트 실행은 기본적으로 개발자가 직접 수행하고 결과를 검토한다. 반복 실행과 자동 분석이 필요한 경우에만 assu-test-run 스킬을 호출해 승인된 범위 안에서 실행한다.
- 개발자가 테스트할 제품 규칙, 기대 결과, 테스트 기준, 구현 범위를 먼저 확인하고 승인한다. AI는 승인된 범위 안에서만 실행하고, 요청에 정책이나 범위가 빠져 있으면 실행 전에 확인한다.
- AI는 새로 작성하거나 수정한 테스트 파일만 대상으로
yarn test <test-file>을 실행한다. 전체 테스트, coverage, watch 실행은 별도 요청이나 승인이 있을 때만 수행한다. - 실패 원인을 다음 네 가지로 구분한다.
- 테스트 코드·mock·fixture·실행 환경 문제: 승인된 기대 동작을 유지한 채 테스트 측 파일만 수정해 재실행한다. 공용 Jest 설정·전역 setup·의존성 파일 변경은 자동 수정 범위가 아니므로 개발자 승인을 받는다.
- 기존 구현과 테스트 기댓값 불일치: 어떤 정책을 기준으로 판단해야 하는지 개발자에게 확인하고, 승인된 정책 기준으로만 테스트를 수정한다.
- 제품 코드 변경 필요: 원인, 영향 범위, 수정안, 대상 파일을 개발자에게 제시하고 승인을 기다린다. 승인 후에는 승인된 범위만 수정하고 Jest를 재실행한다.
- 반복 실행해도 불안정 (flaky 의심): 재시도로 덮지 않고 재현 조건과 flaky 가능성을 기록해 보고한다.
- 한 작업의 대상 테스트는 최초 실행을 포함해 최대 3회 실행한다. 한도 안에서 통과하지 못하면 중단하고 시도 내역과 미해결 원인을 보고한다.
- 성공한 경우에만
docs/ai-qa/test-run-log.md에 실행 결과와 변경 내역을 기록한다. 실패·중단한 실행은 누적 기록에 남기지 않고 현재 작업 결과로 보고한다. 원본 로그 전체는 기록하지 않는다. - 테스트 통과만을 목표로 기댓값을 희석하지 않는다. 개발자는 테스트가 실제 기능과 승인된 정책을 검증하는지 최종 검토한다.
- typecheck와 lint는 자동 실행하지 않는다.
전체 coverage 비율은 강제 목표가 아니라 참고 지표로 사용한다. 신규 또는 변경된 비즈니스 로직을 우선 테스트 대상으로 삼고, 의미 없는 테스트로 수치를 채우지 않는다.
테스트 설계와 구현을 분리한 스킬을 저장소의 .agents/skills에서 관리한다. 저장소 스킬은 팀이 함께 버전 관리할 수 있으며 Codex가 자동으로 탐색한다. 일반적인 테스트 코드 작성 요청은 assu-test가 설계와 구현을 연결한다.
| 스킬 | 책임 | 산출물 |
|---|---|---|
assu-test |
개발자 사전 승인부터 설계·구현·현황판 갱신까지 연결 | 테스트 설계, *.test.ts(x), 현황판 갱신 |
assu-test-design |
제품 규칙 확인 및 테스트 범위 승인 지원 | 테스트 매트릭스, 정상·경계·실패 사례, 우선순위 |
assu-test-implementation |
승인된 범위의 테스트 코드 작성 | *.test.ts(x), 필요한 mock, 현황판 갱신 |
assu-test-run |
승인된 테스트 파일 실행과 실패 원인 분류 | 성공 실행 기록, 시도 내역, 미해결 원인 보고 |
docs/ai-qa/test-dashboard.md는 회원가입에 한정하지 않고 프로젝트 전체 기능의 테스트 이력을 관리한다. 테스트를 추가하거나 보강할 때마다 기능, 우선순위, 계층, 보호하는 규칙, 테스트 파일, GitHub 사용자명, 날짜를 갱신한다.
- 변경 또는 기능에서 사용자·비즈니스 위험이 큰 동작을 식별한다.
- 각 동작을 순수 로직, API 훅, UI 컴포넌트, E2E 후보로 분류한다.
- 정상·경계·실패 사례를 표로 정리한다.
- 비즈니스 영향, 변경 가능성, 실패 비용을 기준으로 구현 우선순위를 제안한다.
- 구현에 필요한 mock, provider, 테스트 데이터의 범위를 명시한다.
- 설계 문서 또는 사용자가 지정한 범위만 구현한다.
- 대상과 같은 FSD slice 안에 테스트 파일을 둔다.
- 실제 API 호출과 네이티브 의존성은 필요한 최소 범위에서 mock하며, mock 도구보다 테스트 경계를 우선한다.
docs/ai-qa/test-dashboard.md에 해당 기능의 테스트 현황을 갱신한다.- 작성한 테스트 파일, 시나리오, 제외한 범위를 보고해 개발자가 최종 검토할 수 있게 한다. 실행은 개발자가 직접 수행하거나 별도로
assu-test-run을 호출한다.
- 승인된 범위의 테스트 파일만
yarn test <test-file>로 실행한다. - 실패 원인을 네 가지(테스트 코드·mock·fixture·환경 문제 / 기존 구현과 기댓값 불일치 / 제품 코드 변경 필요 / flaky 의심)로 분류한다.
- 자동 수정 가능한 범위에서만 수정·재실행한다. 제품 코드 변경, 공용 설정·전역 setup 수정은 개발자 승인을 받는다.
- 최초 실행 포함 최대 3회 안에서 처리하며, 통과하지 못하면 중단하고 시도 내역·미해결 원인을 보고한다.
- 성공한 경우에만
docs/ai-qa/test-run-log.md에 실행 결과와 변경 내역을 기록한다. - 테스트별로 어떤 정책을 검증했는지, 무엇을 수정했는지, 실행 결과가 무엇인지 함께 보고한다.
yarn test
yarn test:watch
yarn test:coverage특정 파일만 확인할 때는 다음처럼 실행한다.
yarn test validation.test.ts테스트 실행은 기본적으로 개발자가 직접 수행한다. assu-test-run을 사용할 때의 기본 실행 범위는 새로 작성하거나 수정한 테스트 파일이며, 전체 테스트(yarn test), coverage, watch 실행은 별도 요청이나 승인이 있을 때만 사용한다.
- 회원가입, 지도 검색, 리뷰처럼 변경이 잦거나 실패 비용이 큰 기능의 순수 로직 테스트를 추가한다.
- 해당 기능의 API 훅에 성공·실패 상태 테스트를 추가한다.
- 사용자 입력과 단계 이동처럼 중요한 UI 상호작용을 컴포넌트 테스트로 추가한다.
- 반복되는 테스트 설계·구현 패턴을 스킬에 반영하고 지속적으로 개선한다.
- 단위·컴포넌트 테스트로 기본 회귀 방어선을 만든 뒤, 로그인·회원가입·지도 검색·리뷰 작성처럼 중요한 흐름에 한정해 E2E 도구와 실행 환경을 결정한다.