Initial commit

2026-09-28 17:59:25 +09:00
commit 101e04a455
269 changed files with 33654 additions and 0 deletions
@@ -0,0 +1,72 @@
+---
+name: testing
+description: 세 스택 공통 테스트 규칙 — 테스트 위치/네이밍, 무엇을 테스트할지, 커밋 전 실행. 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 순수 유틸)
+
+```typescript
+// 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 을 초기화한다).
+> 로컬에서는 개발 스택을 띄운 뒤 컨테이너 안에서 실행하는 것이 가장 간단하다.
+> ```bash
+> docker exec <프로젝트>-backend npx jest --config ./test/jest-e2e.json
+> ```
+> CI 는 postgres 서비스 컨테이너를 띄워 자동으로 실행한다.
+
+- 에러 코드를 추가/삭제하면 **세 곳의 기대 목록을 함께 갱신**한다 ([[checklist]] 3절).
+- 매핑 로직(응답 래퍼·상태 역매핑)을 바꾸면 해당 분기 테스트를 추가한다.
+
+## 테스트하지 않아도 되는 것
+
+- 프레임워크가 보장하는 동작 (라우팅, DI 주입 자체, ORM 쿼리 빌더)
+- 단순 getter/setter, 위임만 하는 컨트롤러 메서드
+- 화면 스타일·레이아웃 값
+
+> API 응답 래퍼/에러 코드는 세 플랫폼 공유 계약이다 ([[response-format]] · [[error-codes]]).