Files
clean-architecture-backend-…/docs/improvement/05-test-structure.md
T
DongHyeonka 3b66358e52 docs(improvement): 리뷰·개선 작업 매뉴얼을 만든다
문제: 이 repo를 리뷰하거나 결함 수정·리팩터링·성능 최적화·구조 변경을 할 때
기준으로 삼을 문서가 없다. docs/manual/은 새 기능을 만드는 순서이고, 리뷰
기준으로 써 온 공용 가이드는 프론트 repo에만 있으며 AGENTS.md·CLAUDE.md가
가리키지 않는다. 2026-11-01부터 쌓인 소유자 결정과 반복 결함 패턴은 리뷰
문서 여러 곳에 흩어져 있다.

방법: docs/improvement/에 README, 01~09장, 결함 패턴 부록을 둔다. 규칙은
다시 쓰지 않고 정본(AGENTS.md, modules.json, application-core/CLAUDE.md,
TESTING_STRATEGY.md, src/build.gradle, 리뷰 문서의 결정 절)을 가리킨다.
정본이 없는 것 — 작업 종류별 절차, 이 repo의 28개 관점 점검 항목과 결함
정의, 반복 결함 패턴, 성능 측정 조건, 무거운 실행 위치, 결정 색인, 세션
분업과 리뷰 반복 종료 조건 — 만 매뉴얼이 정본이 된다. AGENTS.md에
「리뷰·개선 작업 기준」 절, CLAUDE.md에 그 요약을 두고 docs/README.md와
docs/manual/README.md에서 가리킨다. 프론트 매뉴얼과 같은 장 번호를 쓴다.
버린 대안: docs/reviews/ 안에 두기(결과 보관소와 기준서가 섞인다), 공용
가이드 복사(갈라진 복사본이 된다), 소유자 환경 규칙을 AGENTS.md에 직접
쓰기(파생 프로젝트가 정책 문서를 고쳐야 한다).

위험·한계: 매뉴얼을 정본과 대조하는 자동 검사는 없다(문서 파서를 두지
않는 repo 방침). 08장 결정 표는 색인이고 원문과 다르면 원문이 맞다. 저장소
밖 문서(공용 가이드, 커밋 규칙)는 lychee가 따라갈 수 없어 링크 대신 코드
표기로 썼다. 근거를 찾지 못한 것 하나(측정 스크립트를 scripts/perf/로
넣기)는 [제안]으로 표시했다.

검증: 인용한 저장소 경로·리뷰 ID·클래스 이름·태스크 이름·상대 링크·절
번호를 스크립트로 전수 대조했다(로컬, 읽기만). 남은 불일치는 저장소 밖
가이드 경로, 자리표시자, 제안 경로, 원래 있던 문장뿐이다. CLAUDE.md는
DeveloperExperienceContractTest가 요구하는 architectureTest 명령을 그대로
둔다. 문서 대조 lane은 이 커밋을 push한 뒤 desktop에서 돌린다.
2026-11-05 21:59:44 +09:00

144 lines
11 KiB
Markdown

# 05. 테스트 구조 기준
## 핵심
테스트는 **이름이 말한 것을 증명해야 한다.** 통과하는 테스트가 지키겠다고 한 동작을 실제로 지키지 못하면, 그 테스트는
초록색 거짓말이다. 지난 리뷰에서 그런 테스트가 반복해서 나왔다(부록 A6).
정본은 셋이다. 이 장은 그 셋을 가리키고, 개선 작업에서 테스트를 평가·수정할 때의 기준을 더한다.
| 무엇 | 정본 |
| --- | --- |
| 테스트 작성 규칙 6개(이름·`@DisplayName`·GWT·`@Nested`·단언·fake) | `AGENTS.md` 「테스트 전략」 |
| 테스트 분류 5개(TEST·INTEGRATION·SYSTEM·ARCHITECTURE·PERFORMANCE), 배치, source set, 공용 지원 코드 | `docs/testing/TESTING_STRATEGY.md`, 기계 기준 `src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/TestLaneCategory.java` |
| 새 기능의 테스트 배치(포트 → fake → 계약 → adapter 계약) | `docs/manual/08-testing.md` |
## 1. lane과 단계
**lane**은 테스트 묶음 하나다. 분류(category)·source set·태그를 선언하고, 그 분류에 따라 어느 **단계**(PR·main·integration·
performance)에서 돌지가 정해진다. 선언은 leaf `build.gradle`의 `strictTestLanes { lane(...) { ... } }`이다.
```text
lane 선언(leaf build.gradle)
└─ category ── test() ── leaf check ────────────────────────> ci (PR)
├─ architecture() ── architectureCheck ───────────> ci (PR)
├─ mainStage()(document-contract 등) ─────────────> mainCheck (main)
├─ integration() ─────────────────────────────────> integrationCheck
├─ system() ──────────────────────────────────────> systemTestCheck(mainCheck 안)
├─ performance() ─────────────────────────────────> performanceCheck
└─ explicitOnly(reason) ── 어떤 집계에도 없음, 실행하면 이유를 출력
```
예외 하나: `app-bootstrap`의 전체 기동 lane은 그 leaf의 `check`에 들어 있어 `ci`에서 돈다. 조립이 뜨지 않으면 병합을
막아야 하기 때문이다(`src/build.gradle` `systemTestCheck` 위 주석).
단계 표의 정본은 `docs/manual/08-testing.md` 「lane과 단계」와 `src/build.gradle` 라이프사이클이다. 개선 작업에서 지킬 것:
- **새 lane은 반드시 어떤 단계에 속한다.** 어떤 workflow도 돌리지 않는 lane 14개가 있었다(`1101/08-01`). 이제
`verifyStrictLaneStages --dry-run`(PR)이 단계 없는 lane에서 실패한다. workflow를 고치지 않고 집계 태스크로 붙인다.
- **반드시 돌아야 하는 테스트는 이름을 박는다.** `requires(클래스)` + `rejectSkipped`. 이름이 바뀌거나 지워지면 lane이
실패한다(`docs/manual/08-testing.md` 「판단: 새 테스트를 어느 lane에」).
- **lane 정책 값은 캐시 입력이다.** `rejectSkipped`를 바꿨는데 옛 결과가 캐시에서 통과하던 것을 고쳤다(`1103/RR-06-02`).
lane 정책을 새로 더하면 Test 입력으로 선언한다.
- **저장소 파일을 읽는 테스트는 태그가 있다.** 문서와 대조하면 `document-contract`(`mainStage()`), 빌드 스크립트·workflow·
compose를 읽으면 `repository-contract`. 저장소 루트는 이 두 lane에만 준다. 태그 없이 저장소를 읽으면 `test`에서 실패한다
(`AGENTS.md` 「Gradle 정책 권위」, `1101/08-03`).
- **hermetic lane이 파일을 읽으면 그 파일을 입력으로 선언한다.** 그래야 캐시가 거짓 통과를 내지 않는다(`AGENTS.md`
「Gradle 정책 권위」 strict lane 캐시).
## 2. 포트당 fake와 공유 계약
규칙의 정본은 `AGENTS.md` 테스트 작성 규칙 6이다: 포트마다 hand-rolled fake 하나를 포트 소유 leaf의 `testFixtures`에 두고,
adapter가 있는 포트는 fake와 adapter가 같은 추상 계약(`XxxContract`)을 통과한다.
```text
포트 (소유 leaf)
├─ testFixtures: InMemoryX (fake, 하나)
├─ testFixtures: XContract (abstract — 약속 목록)
├─ test: InMemoryXContractTest extends XContract → ci
└─ adapter leaf: RealXContractTest extends XContract → integrationCheck (실 vendor)
```
fake가 실제와 다르게 동작하면 그 fake 위의 유스케이스 테스트가 모두 거짓 초록이 된다(`docs/testing/TESTING_STRATEGY.md` 9절).
개선 작업에서 지킬 것:
- **계약 밖 fake를 만들지 않는다.** 테스트 안 private fake는 실제와 갈라진다(`docs/manual/08-testing.md` 「판단: fake가
어디 사나」, `1101/01-05`).
- **소비자 없는 fake도 만들지 않는다.** 쓰는 유스케이스 테스트가 없는 fake는 두 번째 복사본이 된다(`1101` README 15절
04-14 결정).
- **fake의 동작을 바꾸면 계약 케이스를 같이 바꾼다.** 계약에 없는 동작을 fake에만 넣지 않는다. fake가 실제와 달랐던 예:
쿼터 fake(`1103/RR-01-04`), in-memory fake가 fingerprint 검사 전에 기록을 넘겨줌(`1103` README 17절 r10-02).
- **계약과 겹친 adapter 손 사본 테스트는 지운다.** 같은 약속을 두 번 쓰면 둘 중 하나만 고쳐진다(`1103` README 17절 r10-02,
20건 삭제).
- **skip 수를 본다.** 계약 케이스가 skip되면 그 약속은 검증되지 않았다. command fake 위 계약이 시계를 움직일 수 있는데도
시간 케이스 17개를 skip했다(`1103/RR6-02-02` → 0). 남긴 skip은 설계 이유를 적는다(`1103` README 17.2절 "in-memory fake
계약의 skip 19는 시간 케이스(설계)").
- **현황표를 갱신한다.** 포트를 더하거나 계약을 옮기면 `docs/testing/TESTING_STRATEGY.md` 9절 표를 고친다(`1101` README
16절 r3-h "TESTING_STRATEGY 9절 표를 오케스트레이터가 갱신").
## 3. 이름·GWT
규칙은 `AGENTS.md` 테스트 작성 규칙 1~5가 정본이다. 요약하지 않고 개선 작업의 적용 방법만 적는다.
- 테스트를 **고칠 때** 그 테스트에 규칙을 적용한다. 기존 영어 `@DisplayName`은 고칠 때 한국어로 바꾼다(결정 5,
`AGENTS.md` 규칙 2).
- 이름을 바꾸면 이름이 말한 성질을 단언하는지 다시 본다. 이름과 설명이 다른 계약 테스트가 남은 적이 있다
(`1101` README 13절 05-01 "WorkerCrashRecoveryContractTest 이름/설명 불일치").
- GWT 주석을 검사하는 자동 게이트는 만들지 않는다. 주석은 bytecode에 없고, 실질적인 강제 수단은 공유 계약 상속이다
(`AGENTS.md` 「테스트 전략」).
## 4. RED 확인
**RED**는 고치기 전 코드에서 새 테스트가 실패하는 것을 실행으로 본 기록이다. 수정의 완료 기준이다(01장 2절).
**하는 법**
1. 테스트만 먼저 쓰고 지금 코드에서 돌린다. 실패 메시지를 기록한다.
2. 이미 수정과 테스트를 함께 썼다면, 기준 커밋에 테스트만 얹은 임시 worktree에서 돌린다. 예: desktop 임시 worktree에
`45d2a478` + 새 fixture 7개만 얹어 예상한 6건 실패를 확인했다(`1103` README 17.2절).
3. 또는 수정 커밋에서 production 변경만 되돌려 돌린다. 예: TRANSITION 시작 revision 검사만 되돌리자 command fake 계약과
실 Redis 계약이 같은 2건으로 실패했다(`1103` README 17.2절).
4. 실험한 worktree와 되돌린 변경은 지운다.
**RED가 증거가 되려면**
- **실패 메시지가 그 결함을 말한다.** 예: `expected NOT_OWNER but was ALREADY_STARTED_SAME_OPERATION`(`1103` README 17.2절).
컴파일 오류·준비 실패로 인한 실패는 RED가 아니다.
- **환경에 따라 통과하지 않는다.** watchdog RED 테스트가 공용 풀 병렬도 1인 머신에서는 옛 코드도 통과시켰다
(`1103/RR4-03-01` → 병렬도와 무관하게 고침, `1103` README 16절 r9-b).
- **실 vendor가 필요한 결함은 실 vendor에서 RED를 본다.** 단위 테스트 RED로 대신했으면 그렇게 적는다(`1101` README 14절
r2-04 "새 실 PG 테스트 3개는 수정 전 실패를 실 PG로 확인 안 함").
- 기록 형식: 테스트 이름 + 실패 수(예: "RED 실 PG 5·실 Redis 6·fake 2" — `1103` README 15절 r8-a).
## 5. 테스트가 증명해야 하는 것 — 리뷰 점검표
| 점검 | 결함 모양 | 지난 예 |
| --- | --- | --- |
| 이름이 말한 성질을 단언하나 | 이름은 "carrier를 남기지 않는다"인데 준비는 다른 예외 | `1103/RR6-01-08`(`aClientSideCarrierIsNotLogged`가 `IllegalArgumentException`을 넣음) |
| 부재 단언이 null과 "키 없음"을 구분하나 | `doesNotExist`가 null 필드도 통과 | `1101/02-02` |
| 지키려는 코드를 지우면 실패하나(변이) | 소유자 검사를 지워도 전부 통과 | `1101/05-08`, `1101` README 3절(변이 대부분은 잡음) |
| 시간 제한 대기의 반환값을 단언하나 | `CountDownLatch.await(timeout)` 결과를 버려 시간 초과에도 다음 단계로 | `1103` README 14절(7건) |
| skip이 0이거나 설계 이유가 있나 | 계약 케이스가 조용히 skip | `1103/RR6-02-02` |
| 규칙 테스트가 위반·허용 fixture를 둘 다 가지나 | 위반 fixture만 있어 거짓 양성(허용해야 할 것을 거부)을 못 봄 | `1103/RR6-01-03`, `1103` README 17절 r10-01(A1·A2 위반, A5 허용 fixture) |
| 한 테스트에 `// when`이 하나인가 | 두 동작을 한 테스트가 봄 | `AGENTS.md` 규칙 3 |
| 테스트 코드도 정적 분석을 통과하나 | 게이트 밖에서 53개 태스크가 실패한 채 방치 | `1103` README 14절 → `testQualityCheck` |
| 타이밍에 기대지 않나 | 부하가 높으면 실패하는 "스레드 없음" 단언 | `1103` README 16.1절(`ClientRuntimeRegistryTest`) |
ArchUnit 규칙의 fixture는 `src/app-bootstrap/src/architectureTest/`의 `ArchitectureViolationFixtureTest`가 모은다. 규칙을
더하거나 넓히면 잡혀야 할 위반 fixture와 통과해야 할 허용 fixture를 같은 변경에 넣는다.
## 6. 테스트를 옮기거나 나눌 때
- 옮기기 전과 뒤의 **테스트 수**를 lane별로 비교한다. 보고는 테스트 수로 한다(예: `jpaPlatformContractTest` 407 —
`1103` README 17.2절).
- lane을 바꾸면 그 lane이 단계에 속하는지 `verifyStrictLaneStages --dry-run`으로 본다.
- 공유 테스트 코드는 `testFixtures`로 옮긴다(`docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md`). 한
source set에서만 쓰면 그 source set에 둔다(`docs/testing/TESTING_STRATEGY.md` 5절).
- 아무도 쓰지 않는 테스트 helper는 지운다(`1103` README 14절 — web-fileserver helper 2개).
## 지금 이해하면 되는 것
- 테스트는 이름이 말한 것을 증명한다. 변이로 확인한다.
- fake는 포트당 하나, 계약을 fake와 adapter가 함께 상속한다. skip 수를 본다.
- 수정은 RED(그 결함을 말하는 실패 메시지)를 실행으로 본 뒤에 끝난다.