[test-82/unit] 핵심 도메인 로직 단위 테스트 도입과 PR 검증 게이트 구축

[hm1n]

Summary

핵심 도메인 로직 3개에 Vitest 단위 테스트 43건을 추가하고, PR마다 타입 체크 → 린트 → 단위 테스트를 실행하는 검증 게이트를 GitHub Actions에 붙였습니다.
게이트를 켤 수 있는 상태를 만들기 위해 기존에 누적된 린트 에러 22건을 함께 해소했습니다.
E2E는 이 PR 범위가 아니며 워크플로우 파일을 분리해 두었습니다.

Closes #213

---

Why

왜 이 작업을 진행했나요?

금전 계산이 지점마다 다른 답을 내고 있었습니다.

1인당 정산 금액 계산이 세 곳에 중복되어 있었고 0 나눗셈 가드가 서로 달랐습니다.

위치	기존 코드	참여 인원 0일 때
getUserTotalNbreadAmount.ts	Math.floor(amount / Math.max(count, 1))	총 금액
nbread/nbreadCard.tsx	Math.floor(amount / count) || 0	0
home/NbreadCard.tsx	Math.floor(amount / count)	Infinity

세 번째는 화면에 ∞원으로 노출될 수 있었습니다.

납부 상태 정합성이 검증되지 않은 한 줄에 걸려 있었습니다.

nbread_records.payment_date 조회와 갱신이 각자 new Date(startDate).toISOString().split('T')[0]을 들고 있었습니다. 이 키가 어긋나면 조회는 0건, 갱신은 0행이 되고 예외가 발생하지 않습니다. 사용자가 납부 체크를 눌러도 반영되지 않고 오류도 표시되지 않는 경로입니다.

저장소에 테스트 러너가 없었습니다.

test 스크립트가 없고 .github/workflows에는 릴리즈 노트 자동화만 있어 PR에서 아무 검증도 실행되지 않았습니다.

---

Decision

어떤 구현 방식을 선택했나요?

대상 선정 기준은 "틀리면 사용자에게 즉시 금전 또는 신뢰 문제가 되는 로직"입니다. UI 컴포넌트와 E2E는 제외했습니다.

제외한 후보와 이유를 남깁니다.

• 그룹 권한 확인 로직: 순수 함수로 존재하지 않고 userData?.id === nbreadData.leaderId 형태로 JSX에 인라인되어 있습니다. 실제 권한은 RLS가 담당하므로 프론트 단위 테스트로 검증되는 것이 사실상 없습니다.
• insertParticipant 정원 만료 판정: 판정식 자체는 의미 있으나 IO 두 번 사이에 끼어 있어 추출 비용이 앞의 두 대상보다 큽니다.
• sortNotifications, getRelativeTime: 이미 순수 함수이고 테스트가 쉽지만, 틀려도 정렬 순서나 표시 문구만 어긋나 선정 기준에 미달합니다.

러너는 Vitest를 골랐습니다. 기존 설정이 없어 신규 도입입니다. 대안으로 Jest를 검토했으나 Next.js + TypeScript 환경에서 별도 트랜스파일 설정이 필요해 제외했습니다.

의존성은 vitest 하나만 추가했습니다. 처음에 vite-tsconfig-paths를 넣었다가, Vite가 resolve.tsconfigPaths로 같은 기능을 기본 제공한다는 경고를 확인하고 제거했습니다. 커버리지 리포터는 커버리지 수치를 성과 지표로 쓰지 않기로 해서 넣지 않았습니다.

CI는 E2E와 파일을 분리했습니다. 한 워크플로우에 합치면 느리고 불안정한 쪽이 빠르고 확정적인 쪽을 인질로 잡습니다. E2E가 타임아웃 한 번 나면 타입 오류 0건인 PR도 머지가 막힙니다. 분리 근거는 세 가지입니다.

1. required status check를 따로 등록할 수 있습니다. E2E는 안정화 전까지 required로 걸지 않는 선택이 가능해집니다.
2. E2E는 Supabase 자격증명이 필요해 fork PR에서 시크릿 접근이 불가합니다. 단위 테스트는 시크릿 없이 동작합니다.
3. E2E 작업이 다른 워크트리에서 병행 중이라 파일이 다르면 병합 충돌이 없습니다.

게이트 순서는 타입 체크 → 린트 → 테스트입니다. 빠르게 실패하는 것을 앞에 둡니다. npm run build는 넣지 않았습니다. 느리고 Supabase 환경 변수 의존 가능성이 있어 게이트의 목적인 빠른 피드백에 맞지 않습니다.

---

Changes

무엇이 변경되었나요?

Fix

• NbreadDetail.tsx의 컴포넌트 함수명이 소문자 nbreadDetail이어서 react-hooks/rules-of-hooks 에러가 15건 발생하고 있었습니다. 파일명과 임포트하는 쪽은 이미 NbreadDetail이므로 선언부만 대문자로 맞췄습니다. 호출부 수정은 0건입니다.
• 같은 파일의 deleteParticipants(userData?.id!, ...)는 옵셔널 체이닝 결과에 비널 단언을 붙여 undefined가 그대로 전달될 수 있었습니다. 호출 전에 가드를 두었습니다.

Refactor

• calculateIndividualShare 추출. 세 곳의 중복을 없애고 가장 방어적이던 동작으로 통일했습니다.
• toPaymentDateKey 추출. 변환 규칙은 그대로 두고 위치만 옮겼습니다.
• @typescript-eslint/no-explicit-any 위반 6건을 실제 타입으로 대체했습니다. not-found.tsx의 (window as any)는 global.d.ts의 Window 선언으로 옮기고, Community.tsx와 getSearchFriend.ts는 Supabase Row 타입을 적용하고, deletePost/updatePost는 호출부가 넘기는 값에 맞춰 인자 타입을 지정했습니다.

Test

• calculateIndividualShare.test.ts 12건. 인원 0, 음수, 1명 미만 소수, NaN, 금액 0, NaN, Infinity, 음수 금액, 1원 미만 내림.
• toPaymentDateKey.test.ts 7건. KST 자정이 UTC 기준 전날로 밀리는 경계를 명시적으로 고정했고, 해석할 수 없는 입력은 예외로 끊는지 확인합니다.
• getNotificationDestination.test.ts 24건. 알림 타입 6종, camelCase와 snake_case 이중 키, data가 null/배열/빈 객체/숫자인 경우, URL 인코딩.
• 입출력만 다른 케이스는 test.for로 묶어 실패 시 어느 입력이 깨졌는지 리포트에 드러나게 했습니다.

Setting

• vitest 도입, vitest.config.mts 추가.
• package.json에 typecheck, test, test:watch 스크립트 추가.

CI/CD

• .github/workflows/ci-unit-test.yml 추가. job 이름은 unit-verify입니다.

---

Trade-off

한계와 트레이드오프

• 단위 테스트는 순수 함수만 덮습니다. Supabase 호출 경로, RLS, 실제 쿼리 정확성은 검증하지 않습니다. 이 영역은 E2E와 이후 API Route 이관 시점의 계약 테스트가 맡아야 합니다.
• 추출한 두 함수의 호출부가 실제로 새 함수를 쓰는지는 자동으로 검증되지 않습니다. UI 테스트를 범위에서 제외했기 때문입니다. 호출부 5곳은 표현식 한 줄 교체라 diff로 확인 가능한 수준으로 유지했습니다.
• toPaymentDateKey의 동작은 고치지 않았습니다. KST 자정 입력이 전날로 밀리는 문제가 남아 있습니다. start_date가 date 컬럼이라 현재는 문제가 되지 않지만, 타임스탬프가 섞이면 결제일이 하루 밀립니다. 이번 PR은 현재 동작을 회귀 테스트로 고정하는 것까지만 하고, 수정은 별도 이슈가 맞다고 판단했습니다.
• 린트 Warning은 남아 있습니다. exit code에 영향이 없어 게이트를 막지 않습니다. Error만 해소했습니다.

---

Impact

기존 기능에 미치는 영향

동작이 바뀌는 지점 2개

1. home/NbreadCard.tsx에서 참여 인원이 0일 때 Infinity(∞원)가 아니라 총 금액이 표시됩니다. nbread/nbreadCard.tsx는 같은 조건에서 0이 아니라 총 금액이 표시됩니다. 참여 인원 0은 DB 제약상 정상 경로에서 발생하지 않지만, 세 지점의 답이 달랐던 것을 통일했습니다.
2. Community.tsx의 mapToPost에서 post 테이블의 nullable 컬럼(content, user_name, profile_image, user_id)이 null일 때 빈 문자열로 렌더됩니다. any를 제거하니 드러난 실제 타입 불일치입니다. 화면상 둘 다 빈 값이라 눈에 보이는 차이는 없습니다.

회귀 가능성이 있는 영역

• NbreadDetail.tsx 컴포넌트 리네임. default export이고 임포트하는 쪽이 이미 NbreadDetail을 쓰고 있어 영향이 없다고 판단하지만, 엔빵 상세 페이지 전체가 이 컴포넌트라 렌더 확인이 필요합니다.
• getNbreadRecords, updateNbreadRecord의 날짜 키 생성. 변환식은 동일하지만 납부 체크 경로 전체가 여기에 의존합니다.

배포 시 확인할 사항

• 이 PR은 런타임 동작보다 개발 환경 변경이 큽니다. Vercel 빌드에 영향을 주는 변경은 없습니다.
• develop에 unit-verify required status check를 등록하면 다른 기여자의 머지에도 적용됩니다.

---

Edge Cases

Edge Case 및 실패 시나리오

• 참여 인원이 0, 음수, NaN, 0.5(정수로 버리면 0이 되는 소수)인 경우를 모두 1명으로 취급합니다.
• 총 금액이 NaN 또는 Infinity면 0을 반환합니다.
• 날짜 키 변환에서 빈 문자열과 해석 불가 문자열은 RangeError를 던집니다. 조용히 잘못된 키를 만드는 것보다 끊는 편이 안전하다고 판단했습니다.
• 알림 data가 배열이거나 값이 빈 문자열이면 키가 없는 것으로 취급합니다. camelCase 키가 비어 있으면 snake_case 키로 넘어갑니다.
• Vitest가 Playwright 스펙을 집어가는 경우: include를 src/**/*.test.ts로 좁혀 e2e/*.spec.ts가 걸리지 않게 했습니다.

---

Review Points

리뷰어가 집중해서 봐야 할 부분

🔴 High

• calculateIndividualShare로 통일하면서 home/NbreadCard.tsx와 nbread/nbreadCard.tsx의 참여 인원 0일 때 표시값이 바뀝니다. 통일 방향(1명으로 취급 = 총 금액 표시)이 맞는지 확인이 필요합니다.

🟡 Medium

• NbreadDetail.tsx 리네임이 엔빵 상세 페이지 렌더에 영향이 없는지. 그리고 탈퇴 처리에 추가한 가드가 기존 실패 경로(catch → 토스트)와 동일하게 동작하는지.

🟢 Low

• develop에 걸 브랜치 보호 규칙의 범위. 이번에는 unit-verify required + 최신화 요구(strict)까지만 적용하고 리뷰 승인 요구나 force push 금지는 넣지 않았습니다.

---

Validation

어떻게 검증했나요?

• 단위 테스트 — 로컬 43건 통과 (npm test, 411~566ms)
• E2E 테스트 — 이번 PR 범위 아님
• 수동 테스트 — 게이트 3단계를 로컬에서 순차 실행해 통과 확인
• lint — npm run lint exit 0 (Error 0건)
• typecheck — npm run typecheck exit 0

CI에서의 통과 시간과, 일부러 실패를 만들었을 때 머지가 막히는지는 이 PR에서 직접 확인하고 결과를 코멘트로 남깁니다.

---

남기는 기록

NbreadDetail.tsx의 탈퇴 실패 처리에서 useToast.success('엔빵 나가기에 실패했어요.')로 실패인데 success를 호출하는 기존 버그를 발견했습니다. 린트 대상이 아니고 이번 범위 밖이라 그대로 두었습니다. 별도 이슈가 필요합니다.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
nbread	Ready	Preview	Sep 2, 2026 5:36am UTC

[hm1n]

검증 게이트 동작 확인 결과

develop에 unit-verify를 required status check(strict)로 등록한 뒤, 이 PR에서 통과와 실패 양쪽을 확인했습니다.

실행 시간

경우	총 시간	어디서 끊겼는지	머지
통과	43초	전 단계 통과	가능
타입 오류	31초	Type check (5초 만에 실패, Lint·Unit test 건너뜀)	차단
테스트 실패	39초	Unit test (Type check 5초·Lint 8초 통과 후)	차단

통과 기준 단계별 소요는 아래와 같습니다.

Checkout               2초
Setup Node             6초
Install dependencies  18초
Type check             6초
Lint                   7초
Unit test              1초

npm ci가 18초로 가장 큰 비중이라 단계 순서로 절약되는 시간은 12초 수준입니다. 다만 타입 오류일 때 린트와 테스트를 아예 실행하지 않는다는 점은 의도한 대로 동작합니다.

머지 차단 확인

두 실패 모두 gh pr merge가 아래와 같이 거부되었습니다.

X Pull request andbread/Andbread_Frontend#214 is not mergeable:
  the base branch policy prohibits the merge.

mergeStateStatus도 BLOCKED으로 바뀌는 것을 확인했습니다.

적용한 브랜치 보호 규칙

required status checks : unit-verify
strict                 : true   (최신 develop 동기화 필요)
enforce_admins         : false
required reviews       : 없음
force push / deletion  : 금지

enforce_admins: false이므로 admin은 --admin 플래그로 우회할 수 있습니다. 긴급 상황을 위해 남겨두었습니다. 필요하면 true로 올릴 수 있습니다.

CI E2E test는 required로 등록하지 않았습니다. 실행 시간과 외부 의존이 달라 안정화 데이터가 쌓인 뒤 판단하는 편이 낫다고 보았습니다.

---

이 과정에서 게이트가 잡아낸 실제 문제

게이트를 처음 돌렸을 때 로컬에서는 통과하던 타입 체크가 CI에서 실패했습니다.

error TS2307: Cannot find module '@/assets/logo/nbreads-not-found.svg'
  or its corresponding type declarations.

원인은 next-env.d.ts가 .gitignore 대상이어서 CI의 새 체크아웃에는 존재하지 않는 것이었습니다. 이 파일이 참조하는 next/image-types/global이 *.svg 모듈 선언을 제공하는데, 로컬에는 이전 next dev 실행이 남긴 파일이 있어서 문제가 드러나지 않았습니다.

next build를 게이트에 넣어 파일을 생성하게 하는 대신 src/types/svg.d.ts를 저장소에 추가했습니다. 게이트의 목적이 빠른 피드백이고, 빌드는 Supabase 환경 변수 의존 가능성이 있기 때문입니다. @svgr/webpack을 쓰므로 next/image-types/global의 any 대신 FunctionComponent<SVGProps<SVGSVGElement>>로 선언했습니다.

로컬 검증만으로는 이 문제를 계속 놓쳤을 것이고, 게이트를 붙인 첫 실행에서 드러났습니다.

그 외 확인된 것

• conflict 상태의 PR은 CI가 아예 실행되지 않습니다. pull_request 워크플로우는 merge commit 기준으로 돌기 때문에, 충돌이 있으면 merge commit을 만들 수 없어 실행이 생성되지 않습니다. 이 PR도 처음에는 develop에 E2E 작업이 머지되어 13커밋 뒤처진 상태였고, unit-verify가 실행되지 않았습니다. strict: true와 함께 보면, 뒤처진 PR은 실행 자체가 안 되므로 머지 전에 반드시 최신화가 필요합니다.
• 액션 버전을 develop의 E2E 워크플로와 맞춰 checkout@v7, setup-node@v7, Node 22로 올렸습니다. v4는 Node 20 대상이라 deprecation 경고가 발생했습니다.