TypeScript 테스트 코드 작성 가이드

테스트 파일 구조

테스트 대상 파일과 1:1 매칭. 테스트 파일은 대상 파일과 동일한 디렉토리에 위치.

파일 명명

{대상파일명}.spec.ts 형식.

예시: user.service.ts → user.service.spec.ts

테스트 프레임워크

Jest 사용. 프로젝트 내 일관성 유지.

테스트 계층

메서드(함수) 단위로 대단원 구성, 각 케이스별로 소단원 작성. 복잡한 메서드는 시나리오별 중단원 추가 가능.

테스트 범위 선택

자명하거나 지나치게 단순한 로직(단순 getter, 상수 반환)은 생략. 비즈니스 로직, 조건 분기, 외부 의존성이 있는 코드를 우선 테스트.

테스트 케이스 구성

기본 성공 케이스 최소 1개 필수. 주요 초점은 실패 케이스, 경계값(boundary), 엣지 케이스, 예외 상황에 둠.

테스트 독립성

각 테스트는 독립적으로 실행 가능해야 함. 테스트 간 실행 순서 의존 금지. 공유 상태 사용 시 각 테스트마다 초기화.

Given-When-Then 패턴

테스트 코드를 3단계로 구조화—Given(준비), When(실행), Then(검증). 복잡한 테스트는 주석이나 빈 줄로 단계 구분.

테스트 데이터

하드코딩된 의미 있는 값 사용. 랜덤 데이터는 재현 불가능한 실패를 유발하므로 피함. 필요시 시드 고정.

모킹 원칙

외부 의존성(API, DB, 파일 시스템)은 모킹. 같은 프로젝트 내 모듈은 가급적 실제 사용, 복잡도가 높을 때만 모킹.

테스트 재사용

반복되는 모킹 설정, 픽스처, 헬퍼 함수는 공통 유틸로 추출. 단, 과도한 추상화로 테스트 가독성을 해치지 않도록 주의.

통합/E2E 테스트

유닛 테스트가 우선. 통합/E2E는 복잡한 흐름이나 여러 모듈 상호작용이 코드만으로 파악 어려울 때 작성. 별도 디렉토리(tests/integration, tests/e2e)에 위치.

테스트 명명

테스트 이름은 "무엇을 테스트하는가"를 명확히 표현. "~할 때 ~해야 한다" 형태 권장. 구현 세부사항보다 행동(behavior) 중심.

단언(Assertion) 수

하나의 테스트에서 여러 관련 단언은 허용하되, 서로 다른 개념을 검증하는 경우 테스트 분리.

구조화

describe로 메서드/기능 그룹핑, it으로 개별 케이스 작성. 중첩 describe로 시나리오 분류 가능.

모킹

Jest의 jest.mock(), jest.spyOn() 활용. 외부 모듈은 최상단에서 모킹, 테스트별 동작 변경은 mockReturnValue, mockImplementation 사용.

비동기 테스트

async/await 사용. Promise rejection 테스트는 await expect(fn()).rejects.toThrow() 형태.

Setup/Teardown

beforeEach, afterEach로 공통 준비/정리. beforeAll, afterAll은 무거운 초기화(DB 연결 등)에만 사용.

타입 안전성

테스트 코드도 타입 체크. as any나 @ts-ignore 최소화. 필요시 타입 가드나 타입 단언 명확히.

테스트 유틸 위치

단일 파일용은 같은 파일 내 하단, 여러 파일 공유는 __tests__/utils 또는 test-utils 디렉토리.

Coverage

코드 커버리지는 참고 지표. 맹목적인 100% 추구보다 의미 있는 케이스 커버에 집중.