wandergo/.claude/rules/testing.md

name, description

name	description
testing	세 스택 공통 테스트 규칙 — 테스트 위치/네이밍, 무엇을 테스트할지, 커밋 전 실행. backend Jest, frontend Vitest, flutter flutter_test 기준.

테스트 규칙

템플릿은 각 스택에 테스트 러너가 준비되어 있다 — backend jest, frontend vitest, flutter flutter_test. 새 로직을 추가하면 최소한의 테스트를 함께 작성한다.

공통 원칙

• 무엇을 테스트하나: 순수 함수(utils), 서비스/비즈니스 로직, 에러 코드 매핑 분기를 우선한다. 프레임워크 기본 동작은 테스트하지 않는다.
• 공유 계약은 반드시 테스트한다 — 아래 "계약 테스트" 절 참조.
• 테스트는 결정적(deterministic) 으로 — 외부 네트워크/시간/랜덤에 의존하지 않도록 모킹한다.
• 커밋 전 실행 — 변경 영역의 테스트가 통과해야 한다. (checklist)
• CI 가 강제한다 — .github/workflows/ci.yml 이 세 스택의 lint·test·build 와 에러 코드 동기화를 PR 마다 검사한다.
• 테스트 설명(it/test 제목)은 한국어로 "무엇을 검증하는지" 명확히 작성한다.

스택별 위치·실행

스택	러너	위치·네이밍	실행
backend	Jest	단위 *.spec.ts (소스 옆), e2e test/*.e2e-spec.ts	npm run test, npm run test:e2e

| frontend | Vitest | *.spec.ts / *.test.ts (대상 옆 또는 __tests__/) | npm run test:unit | | flutter | flutter_test | test/ 하위, *_test.dart | flutter test |

예시 (backend 순수 유틸)

// shared/utils/format.spec.ts
import { formatSomething } from './format';

describe('formatSomething', () => {
  it('빈 입력이면 빈 문자열을 반환한다', () => {
    expect(formatSomething('')).toBe('');
  });
});

---

계약 테스트 (삭제·비활성화 금지)

세 플랫폼이 공유하는 계약은 어긋나도 컴파일 에러가 나지 않는다. 아래 테스트가 그 안전망이다.

대상	위치	검증 내용
에러 코드 레지스트리	backend/src/common/errors/error-codes.spec.ts	네이밍 규약, 상태 역매핑, 클라이언트 전용 코드가 서버에서 선택되지 않음
에러 응답 포맷	backend/src/common/filters/http-exception.filter.spec.ts	코드/상태/traceId, 내부 정보 미노출, 검증 상세 사유 미노출
프론트 에러 사전	frontend/src/composables/useApi.spec.ts	코드 목록이 백엔드와 일치, 폴백 동작
앱 에러 사전	flutter/test/error_lexicon_test.dart	코드 목록이 백엔드와 일치, 폴백 동작
응답 계약 (e2e)	backend/test/app.e2e-spec.ts	실제 HTTP 로 래퍼·에러코드·traceId·페이지네이션·헬스체크 형식 검증

e2e 는 DB 가 필요하다 (AppModule 이 TypeORM 을 초기화한다). 로컬에서는 개발 스택을 띄운 뒤 컨테이너 안에서 실행하는 것이 가장 간단하다.

docker exec <프로젝트>-backend npx jest --config ./test/jest-e2e.json

CI 는 postgres 서비스 컨테이너를 띄워 자동으로 실행한다.

e2e 스위트는 한 DB 를 함께 쓰므로 순서대로 돈다(jest-e2e.json 의 maxWorkers: 1). 빈 DB 에서 여러 스위트가 동시에 마이그레이션하면 같은 테이블을 만들다 부딪혀 무작위로 실패한다(2026-11-03, 스위트 5개에서 재현). 새 e2e 스위트는 실제 데이터와 겹치지 않는 값(없는 지역 코드 '99', e2e- 접두어 id, 2030년 날짜 등)만 쓰고 끝나면 지운다.

• 에러 코드를 추가/삭제하면 세 곳의 기대 목록을 함께 갱신한다 (checklist 3절).
• 매핑 로직(응답 래퍼·상태 역매핑)을 바꾸면 해당 분기 테스트를 추가한다.

테스트하지 않아도 되는 것

• 프레임워크가 보장하는 동작 (라우팅, DI 주입 자체, ORM 쿼리 빌더)
• 단순 getter/setter, 위임만 하는 컨트롤러 메서드
• 화면 스타일·레이아웃 값

API 응답 래퍼/에러 코드는 세 플랫폼 공유 계약이다 (response-format · error-codes).