arasystem/.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) 으로 — 외부 네트워크/시간/랜덤에 의존하지 않도록 모킹한다.
  • 성능 단언("입력이 커져도 오래 걸리지 않는다")은 벽시계가 아니라 계산량으로 잰다 — 지금 스레드의 user CPU 시간(backend/test/cpu-time.ts)이나 비용 수치. 프로세스 전체 · system 시간은 쓰지 않는다 — V8 의 GC · JIT 도우미 스레드와 페이지 폴트가 기계 사정을 따라 흔들려, 2026-10-31 문서만 바꾼 PR 의 CI 에서 할당이 많은 단언 셋이 넘쳤다 (같은 컨테이너 16회: 프로세스 user + system 으로 4회 넘침 · 스레드 user 로 0회). CPU 시간 한도는 지금 값의 10배쯤 둔다 — CPU 시간도 부하에서 는다(2026-10-28: CI 와 같은 Linux 컨테이너에서 메모리가 모자라고 테스트가 함께 돌 때 평소의 47배 — 여유가 36배뿐이던 한도 두 곳이 CI 를 실패시켰다). 막으려는 옛 경로(제곱 등)는 그 한도를 확실히 넘어야 한다 — 둘 사이가 좁으면 입력을 키운다. 벽시계는 다른 작업이 CPU 를 나눠 쓰면 몇 배로 늘어 CI 에서 흔들린다 (2026-10-27: 혼자 0.8초인 정화가 부하에서 9초). 비동기 결과를 기다릴 때도 고정 대기(setTimeout(20)) 대신 조건이 될 때까지 짧게 다시 보고 넉넉한 기한을 둔다.
  • 시간대도 입력이다 — CI 는 UTC, 개발 PC 는 KST 다. 화면에 보이는 시각 · 날짜 글("오늘 오전 9:12")을 글자 그대로 보는 테스트는 시각을 지역 시각으로 만들거나(new Date(2026, 9, 31, 9, 12)) 포매터에 시간대를 넘긴다(frontend format.spec.ts 의 SEOUL). UTC 로 적은 고정값('2026-10-31T00:12:00Z')은 KST 에서만 그 글이 된다(2026-11-02 — 12단계 테스트 셋이 CI 에서만 실패). 시각을 보이는 화면을 고쳤으면 UTC 로도 돌려 본다(Git Bash — TZ=UTC npm run test:unit -- --run).
• 커밋 전 실행 — 변경 영역의 테스트가 통과해야 한다. (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 서비스 컨테이너를 띄워 자동으로 실행한다.

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

테스트하지 않아도 되는 것

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

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