테스트 주도 개발

핵심 원칙

동작 변경은 테스트가 올바른 이유로 먼저 실패한 후, 구현으로 인해 통과해야만 신뢰를 얻을 수 있습니다.

테스트는 구현 세부 사항이 아닌 공개 인터페이스를 통해 동작을 검증해야 합니다. 코드는 완전히 바뀔 수 있지만 테스트는 바뀌지 않아야 합니다.

좋은 테스트는 통합 스타일입니다. 즉, 공개 API를 통해 실제 코드 경로를 실행합니다. 테스트는 시스템이 '무엇'을 하는지를 설명해야 하며, '어떻게' 하는지를 설명해서는 안 됩니다. 좋은 테스트는 명세처럼 읽힙니다: "사용자가 유효한 장바구니로 체크아웃할 수 있다"는 어떤 기능이 존재하는지 정확히 알려줍니다. 이러한 테스트는 리팩터링 후에도 유지됩니다. 내부 구조에 신경 쓰지 않기 때문입니다.

나쁜 테스트는 구현에 결합되어 있습니다. 내부 협력자를 목(mock) 처리하거나, 비공개 메서드를 테스트하거나, 호출 횟수를 확인하거나, 공개 인터페이스 대신 외부 수단을 통해 검증합니다. 경고 신호: 동작은 동일한데 리팩터링 후 테스트가 깨집니다.

tests.md, mocking.md, testing-anti-patterns.md 파일을 참조하세요.

철칙

소유한 프로덕션 동작 변경은 실패하는 테스트가 먼저 있어야 합니다.

의미:

하나의 동작에 대해 하나의 테스트를 작성하십시오.
테스트를 실행하고 실패하는지 확인하십시오.
실패가 누락된 동작을 증명하는 것이지, 오타나 설정 버그가 아님을 확인하십시오.
테스트를 통과시키는 가장 작은 프로덕션 변경을 작성하십시오.
초록불(GREEN) 상태에서만 리팩터링하십시오.

이미 구현 코드가 테스트보다 먼저 존재하는 경우:

사용자 작업을 허가 없이 삭제하지 마십시오.
이를 검증된 구현이 아닌 스파이크(spike)/참조로 취급하십시오.
코드를 제쳐두고, 실패하는 테스트를 작성한 다음 테스트부터 구현하는 것을 선호하십시오.
기존 코드를 유지해야 하는 경우, 먼저 회귀/특성화 테스트를 추가한 다음 새로운 실패 테스트로 동작을 변경하십시오.

안티패턴: 수평적 분할

모든 테스트를 먼저 작성하고, 그다음 모든 구현을 작성하지 마십시오. 그것이 수평적 분할입니다.

잘못된 예:

RED:   test1, test2, test3, test4
GREEN: impl1, impl2, impl3, impl4

올바른 예:

RED -> GREEN -> REFACTOR: 동작 1
RED -> GREEN -> REFACTOR: 동작 2
RED -> GREEN -> REFACTOR: 동작 3

이유: 대량의 테스트는 상상된 설계를 인코딩하고, 피드백 주기를 늦추며, 종종 동작 대신 형태(form)를 테스트합니다.

워크플로우

1. 동작 계획

코드를 작성하기 전에:

명확하지 않은 경우 사용자와 공개 인터페이스 변경 사항을 확인합니다.
구현 단계가 아닌 테스트할 동작을 목록으로 만듭니다.
중요 경로와 복잡한 로직에 우선순위를 두고, 가짜 완전성을 쫓지 마십시오.
깊은 모듈(deep modules) 기회를 식별합니다.
테스트 용이성을 위한 인터페이스를 설계합니다.
첫 번째 트레이서 불릿(tracer-bullet) 동작을 선택합니다.

질문: "어떤 공개 동작이 존재해야 하는가? 어떤 동작이 먼저 중요한가?"

2. RED: 하나의 실패 테스트

하나의 관찰 가능한 동작에 대해 하나의 최소 테스트를 작성하십시오.

요구 사항:

공개 인터페이스만 사용합니다.
이름이 동작을 설명합니다.
가능한 실제 코드를 테스트합니다.
시스템 경계나 불가피한 연결점에서만 목(mock)을 사용합니다.
구현 전에 실패합니다.

가장 좁은 유용한 명령을 실행하십시오. 예:

npm test path/to/test.test.ts

실패를 확인하십시오:

설정/오타 오류가 아닌 테스트 자체가 실패해야 합니다.
실패 이유가 누락된 동작과 일치해야 합니다.
즉시 통과하면 테스트가 잘못되었거나 동작이 이미 존재하는 것입니다. 테스트를 수정하거나 다음 누락된 동작을 선택하십시오.

3. GREEN: 최소 구현

현재 테스트를 통과시키기에 충분한 코드만 작성하십시오.

하지 말아야 할 것:

추측성 기능을 추가하지 마십시오.
관련 없는 코드를 리팩터링하지 마십시오.
미래 옵션을 추가하지 마십시오.
"여기서 하면 쉬우니까" 범위를 넓히지 마십시오.

실행:

npm test path/to/test.test.ts

그런 다음 관련 주변 테스트를 실행하십시오. 출력은 깨끗해야 합니다: 새로운 경고, 불규칙 또는 숨겨진 오류가 없어야 합니다.

4. REFACTOR: 초록불 상태에서 정리

테스트가 통과한 후에만 리팩터링하십시오. 유용한 리팩터링이 없으면 간략히 말하고 계속 진행하십시오.

리팩터링 후보를 찾으십시오:

중복
부적절한 이름
얕은 모듈
혼란스러운 경계
작은 인터페이스 뒤로 이동할 수 있는 복잡성

규칙:

동작과 기대치는 변하지 않습니다.
각 리팩터링 단계 후 테스트는 초록불을 유지합니다.
테스트 리팩터링은 이름 변경, 중복 제거, 픽스처/빌더 추출, 또는 실패 메시지 개선을 포함할 수 있습니다.
단언(assertion)이 예상 동작을 변경하면 중단하십시오: 그건 새로운 RED 주기입니다.

5. 수직으로 반복

마지막 주기에서 배운 내용을 바탕으로 다음 동작을 선택하십시오. 한 번에 하나의 동작씩.

주기별 체크리스트

[ ] 테스트는 구현이 아닌 관찰 가능한 동작을 설명합니다
[ ] 테스트는 공개 인터페이스만 사용합니다
[ ] 테스트는 구현 전에 실패했습니다
[ ] 실패 이유가 올바릅니다
[ ] 코드는 이 테스트에 최소화되어 있습니다
[ ] 추측성 동작이 추가되지 않았습니다
[ ] 관련 테스트가 깨끗하게 통과합니다
[ ] 리팩터링은 초록불 상태에서만 고려되었습니다

커밋 게이트

감사 가능한 작업을 위해 가능한 경우 단계별로 커밋하십시오:

RED 커밋: 테스트 전용 또는 최소 스캐폴드와 실패 단언. 본문에 실패한 명령과 이유를 기록합니다.
GREEN 커밋: 최소 구현. 본문에 대상 테스트 통과와 리팩터링 고려 사항을 기록합니다.
REFACTOR 커밋: 동작이나 기대치 변경 없음. 본문에 변경된 내용과 변경되지 않은 내용을 명시합니다.

커밋에 AI 기여자 표시를 포함하지 마십시오.

CLI 계약 테스트

CLI 도구의 경우, 명령 인터페이스가 제품 계약입니다. 가장 낮은 신뢰 수준에서 외부에서 내부로(outside-in) 테스트하는 것을 선호하십시오:

CLI 계약 테스트: 가짜 공급자나 픽스처로 루트/하위 명령을 실행하고, stdout, stderr, 종료 동작, JSON 형태를 단언합니다.
단위 테스트: 구문 분석, 비교, 분류, 컨텍스트 선택, 오류 분류.
공급자 통합 테스트: 파일 시스템 픽스처와 가짜 외부 서비스, 네트워크/인증 없음.
라이브 스모크 테스트: 옵트인 전용, 형태/불변 속성은 단언하되 변덕스러운 정확한 출력은 단언하지 않습니다.

수동 QA 회귀 규칙

수동 QA는 발견(discovery)이지, 검증의 근간이 아닙니다. 수동 QA가 동작 격차를 발견하면:

이를 재현하는 가장 낮은 수준의 RED 회귀 테스트를 작성하십시오.
실패 증거를 확인하십시오.
GREEN을 구현하십시오.
자동화된 테스트를 다시 실행하십시오.
테스트가 통과한 후에만 수동 QA를 다시 실행하십시오.

출력/복사/CLI 형태가 변경된 경우 CLI 계약 테스트를 추가하거나 업데이트하십시오.

합리화 함정

주장	대응
"테스트하기엔 너무 간단해"	간단한 동작도 회귀됩니다. 작은 테스트를 추가하세요.
"나중에 테스트할게"	나중에 통과하는 테스트는 테스트가 실패할 수 있다는 것을 증명하지 않습니다.
"수동으로 확인했어"	수동 확인은 반복 가능한 회귀 테스트가 아닙니다.
"먼저 탐색해야 해"	괜찮습니다. 스파이크를 하고, 제쳐둔 후 TDD를 시작하세요.
"테스트가 어려워"	인터페이스 사용이 어려울 수 있습니다. 연결점/설계를 단순화하세요.
"목(mocking)으로 쉬워져"	아마 목의 동작을 테스트하고 있을 수 있습니다. 안티패턴을 읽어보세요.
"하나의 큰 테스트가 다 커버해"	엔드투엔드 계약이 더 필요하지 않다면 동작당 하나의 테스트를 선호하세요.
"리팩터링에는 실패 테스트가 필요해"	순수 리팩터링은 초록불에서 시작하고 초록불을 유지합니다. 동작 변경에는 RED가 필요합니다.

위험 신호: 중단하고 수정

프로덕션 동작이 실패 테스트 전에 변경되었습니다.
테스트가 즉시 통과하지만 RED라고 주장합니다.
실패 이유를 검사하지 않았습니다.
테스트 이름이 구현을 설명합니다.
테스트가 비공개 호출, 호출 순서, 또는 내부 협력자를 단언합니다.
목 설정이 테스트 로직을 지배합니다.
테스트만을 위해 새로운 메서드가 존재합니다.
구현이 테스트와 맞지 않아 GREEN 단계에서 테스트를 수정합니다.
어떤 구현보다 먼저 수평적으로 테스트를 일괄 작성합니다.

막혔을 때

문제	해결책
테스트 방법을 모르겠음	원하는 공개 API와 첫 번째 단언을 작성하세요.
테스트 설정이 너무 큼	픽스처/헬퍼를 추출하세요. 그래도 크면 설계를 단순화하세요.
모든 것을 목(mock)해야 함	코드가 너무 결합되어 있을 가능성이 높습니다. 의존성 주입/연결점을 도입하세요.
기존 코드에 테스트가 없음	현재 동작에 대한 특성화 테스트를 추가한 다음, 변경을 위해 RED를 수행하세요.
버그가 명확하지 않음	먼저 수동으로 재현하거나 로그를 확인한 다음, 가장 작은 실패 회귀 테스트를 작성하세요.

완료 전 확인

새롭거나 변경된 동작에 테스트가 있습니다.
각 새 동작 테스트가 올바른 이유로 실패하는 것이 관찰되었습니다.
모든 관련 테스트가 통과합니다.
테스트가 공개 동작을 검증합니다.
목(mock)은 경계 전용이거나 정당화됩니다.
테스트 전용 프로덕션 API가 추가되지 않았습니다.
수동 QA 발견 사항이 회귀 테스트가 되었습니다.

barlevalon/skills

skills란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서