Files
clean-architecture-backend-…/docs/testing/TESTING_STRATEGY.md
T

9.0 KiB

테스트 전략 — TEST / INTEGRATION / SYSTEM / ARCHITECTURE / PERFORMANCE

  • 기준 일자: 2026-09-18
  • 상태: 활성 SSOT
  • 기계 기준: build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/TestLaneCategory.java
  • 관련 리뷰: docs/reviews/2026-09-07-app-bootstrap-module-code-review.md BOOT-014~016
  • 후속 결정: docs/superpowers/specs/2026-09-16-verification-surface-reduction-design.md

1. 공식 테스트 분류는 다섯 개뿐이다

이 저장소의 실행 taxonomy는 다음 다섯 개다.

Category 의미 외부 인프라
TEST 빠르고 결정적인 로컬 검증. unit, slice, hermetic contract를 포함한다. 원칙적으로 없음
INTEGRATION 실제 DB·브로커·스토리지·프로세스 등 외부 경계와의 통합을 검증한다. 허용
SYSTEM 여러 모듈이 조립된 애플리케이션/런타임 동작과 클래스패스 형상을 검증한다. 필요에 따라 허용
ARCHITECTURE 의존 방향, 패키지 경계, 금지 API, 테스트 taxonomy 같은 구조 규칙을 검증한다. 없음
PERFORMANCE 지연, 처리량, 자원 사용과 회귀를 측정한다. 실제에 가까운 환경 허용

StrictTestLaneSpec의 기본 category는 TEST이며, test(), integration(), system(), architecture(), performance()가 각각 위 다섯 값을 선택한다.

1.1 unit / slice / contract는 별도 category가 아니다

다음 용어는 TEST 안에서 무엇을 검증하는지 설명하는 스타일이다.

  • unit: 한 클래스·함수·도메인 규칙
  • slice: Spring MVC/JPA 등 한 프레임워크 계층의 좁은 조립
  • contract: 외부 인프라 없이 검증 가능한 모듈/API/직렬화 약속

예를 들어 @WebMvcTest는 slice이지만 category는 TEST다. JSON snapshot 검증은 contract이지만 hermetic하면 category는 TEST다. 새로운 SLICE나 CONTRACT category를 만들지 않는다.

1.2 qualification은 테스트 종류가 아니다

qualification은 CI/release 검증 gate다. 여섯 번째 테스트 category가 아니다.

현재 루트 qualificationCheck는 full system composition과 auxiliary-source style 검증을 묶는다. 특정 provider certification workflow나 leaf task 이름에 qualification이 들어갈 수도 있지만, 그 안에서 실행되는 테스트 자체는 다섯 category 중 하나로 분류한다.

즉 다음 두 질문을 분리한다.

  1. 이 테스트는 무엇을 검증하는가? → 다섯 category 중 하나.
  2. 언제/어떤 gate가 이 테스트를 실행하는가? → CI, qualification, release 정책.

2. Category와 source set은 같은 개념이 아니다

source set 이름으로 category를 추론하지 않는다.

  • 일반적인 src/test는 TEST의 기본 실행 위치다.
  • 별도 runtime/classpath가 필요한 테스트는 auxiliary source set을 사용할 수 있다.
  • strict lane은 자신이 사용할 source set과 category를 각각 명시한다.
  • postgresqlIntegrationTest처럼 이름에 integration이 들어가더라도, 기계 기준은 이름이 아니라 lane의 integration() 선언이다.

source set 목록은 계속 변하는 구현 세부사항이다. 이 문서에 전체 목록을 복제하지 않는다.

2026-09-16 verification-surface 축소에서 verifyTestSourceSetRegistry를 삭제했다. Markdown 표와 Gradle source set을 대조하는 parser는 current-state를 또 하나의 build contract로 복제했기 때문이다. 이 verifier를 다시 만들지 않는다.

3. 어디에 어떤 테스트를 두는가

대상 Category 기본 방식
도메인 엔티티·값 객체 TEST 순수 단위 테스트
Application use case TEST fake/stub port, 필요 최소 mock
startup validator / settings validation TEST MockEnvironment 또는 순수 객체
Spring @Configuration 한 조각 TEST ApplicationContextRunner
MVC/WebFlux controller 한 slice TEST framework slice test
hermetic serialization/API snapshot TEST contract assertion
JPA repository + 실제 PostgreSQL INTEGRATION Testcontainers/real DB
Kafka/Rabbit/Redis/Mongo와 실제 프로토콜 통신 INTEGRATION real service/container
전체 Boot composition, optional classpath 조합 SYSTEM full application/runtime graph
sample 제거/transport 포함 여부 등 전체 조립 결과 SYSTEM 별도 classpath/source set 가능
ArchUnit, module dependency rule, forbidden API ARCHITECTURE static/bytecode structure
JMH, throughput/latency regression PERFORMANCE benchmark/performance lane

3.1 TEST에서 금지하는 것

기본 TEST가 개발자의 로컬 루프를 무겁게 만들면 taxonomy가 무너진다.

  • 실제 Docker/DB/broker를 요구하지 않는다.
  • 외부 SaaS/network를 호출하지 않는다.
  • 전체 애플리케이션 graph가 필요하지 않은데 @SpringBootTest를 사용하지 않는다.
  • production 패키지와 무관한 unit/, service/, regression/ 같은 별도 분류 폴더를 만들지 않는다.

taxonomy 자체를 검증하기 위한 negative fixture는 예외다. 예를 들어 Testcontainers import를 일부러 가진 fixture는 실제 컨테이너를 실행하려는 테스트가 아니라 ARCHITECTURE 규칙의 입력이다.

4. 배치 원칙

테스트 코드는 가능한 한 production package를 그대로 mirror한다. 위치는 대상 코드의 소유권으로 찾을 수 있어야 한다.

별도 source set은 다음 중 하나가 실제로 달라질 때만 만든다.

  • runtime/classpath
  • 외부 인프라 요구
  • JVM 옵션/환경
  • 실행 비용과 스케줄
  • 독립적인 strict-lane evidence가 필요한 경우

단순히 이름을 예쁘게 나누기 위해 source set을 만들지 않는다.

5. 공용 테스트 지원 코드

공유 fixture의 publish 표준은 Gradle java-test-fixtures다.

  • 다른 source set 또는 다른 leaf가 소비해야 하는 fixture/fake/assertion/container helper는 src/testFixtures/java에 둔다.
  • 다른 leaf는 testFixtures(project(':...'))로 명시적으로 소비한다.
  • auxiliary lane이 fixture를 쓰면 그 lane의 classpath에 testFixtures를 명시적으로 연결한다.
  • 반대로 한 source set 안에서만 쓰는 helper는 그 source set 안에 둔다. 사용처가 하나의 test classpath뿐인데 testFixturesJar를 만들 이유는 없다.
  • TestUtil, CommonUtil처럼 역할이 드러나지 않는 bucket을 만들지 않는다.

과거 testkit custom source set / ca.testkit-publisher 방식은 java-test-fixtures로 이관됐으며 다시 도입하지 않는다.

fixture는 지원 코드다. TEST/INTEGRATION/SYSTEM/ARCHITECTURE/PERFORMANCE 중 하나의 category를 추가하지 않는다.

6. Gradle 실행 계층

leaf

  • :<leaf>:check: 그 leaf의 compile, 일반 테스트와 로컬 quality 검증.
  • :<leaf>:testLaneCheck: 그 leaf가 선언한 TEST category strict lanes.
  • :<leaf>:integrationTestLaneCheck: INTEGRATION strict lanes.
  • :<leaf>:systemTestLaneCheck: SYSTEM strict lanes.
  • :<leaf>:architectureTestLaneCheck: ARCHITECTURE strict lanes.
  • :<leaf>:performanceTestLaneCheck: PERFORMANCE strict lanes.

모든 leaf가 모든 category lane을 가질 필요는 없다.

repository

  • integrationCheck: production leaf들의 INTEGRATION lanes.
  • systemTestCheck: production leaf들의 SYSTEM lanes.
  • architectureCheck: repository architecture rules + ARCHITECTURE lanes.
  • qualificationCheck: SYSTEM composition + auxiliary-source style gate.
  • ci: leaf checks + architecture/quality/config contract + qualification.
  • releaseCheck: ci + release-only provenance/archive/public-path checks.

integrationCheck는 현재 ci에 암묵적으로 포함되지 않는다. 여러 integration lane이 container runtime을 요구하므로 별도 workflow/main/nightly에서 실행할 수 있다.

PERFORMANCE는 기본 로컬 check에 붙이지 않는다. 명시적 benchmark/performance task나 scheduled workflow가 실행한다.

7. 새 테스트를 추가할 때 판단 순서

  1. 실제 외부 인프라가 필요한가?
    • yes → INTEGRATION 후보.
  2. 여러 모듈의 실제 application graph/classpath 조합이 검증 대상인가?
    • yes → SYSTEM 후보.
  3. 코드 구조/의존 관계 자체가 검증 대상인가?
    • yes → ARCHITECTURE.
  4. 성능 수치가 검증 대상인가?
    • yes → PERFORMANCE.
  5. 모두 아니면 TEST.

그 다음에야 어떤 source set과 fixture가 필요한지 결정한다.

8. SSOT 역할 분리

  • 기계 SSOT: TestLaneCategory + StrictTestLaneSpec
  • 사람 SSOT: 이 문서
  • 실행 graph: 각 leaf의 strict lane 선언과 root lifecycle task
  • qualification/release 정책: CI/workflow 및 qualification task

문서와 build.gradle의 전체 현재 상태를 다시 파싱해 서로 맞는지 검사하는 별도 verifier는 두지 않는다. 불변조건은 코드와 convention plugin이 강제하고, 이 문서는 분류 기준과 의도를 설명한다.