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

11 KiB

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(...) { ... } }이다.

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)을 통과한다.

포트 (소유 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(그 결함을 말하는 실패 메시지)를 실행으로 본 뒤에 끝난다.