Files
course-registration/docs/testing-and-domain-validation-conventions.md
T

3.6 KiB

Test and Domain Validation Conventions

이 문서는 테스트의 Given / When / Then 문법과 Domain/JPA model validation 기준을 고정한다.

Test language

테스트 종류에 따라 하나의 문법을 선택한다.

테스트 성격 기준
API / Controller Scenario.given(...).when(...).then(...)
Application Integration Scenario GWT
Repository Integration Scenario GWT
Domain Policy Scenario GWT
Concurrency Scenario Scenario GWT
Mock 기반 Unit BDDMockito.given(...) / BDDMockito.then(...).should(...)
Pure Function / Parameterized 직접 assertion 허용
Entity Invariant 직접 assertion 허용
Architecture / Source / Config 직접 assertion 허용

Mockito.when(...)은 행동 실행이 아니라 mock setup이므로 사용하지 않는다. mock setup은 given(...).willReturn(...), interaction 검증은 then(mock).should(...)를 사용한다.

Scenario를 사용하는 경우 .when(...) 또는 .whenRunning(...) 뒤에는 반드시 terminal assertion이 있어야 한다. ScenarioUsageTest가 이 규칙을 검사한다.

SourceStyleTest는 classic Mockito의 when/verify 계열 사용을 금지한다. times, never, inOrder, mock처럼 BDDMockito의 given/then 의미를 훼손하지 않는 Mockito utility는 허용한다.

Validation contract

기계적인 invariant는 domain.validation.Require만 사용한다.

값의 의미 사용 규칙
필수 일반 객체 Require.nonNull
필수 String Require.text
필수 양수 Integer / Long Require.positive
선택 양수 Long Require.positiveIfPresent
선택 String 해당 경계에서 normalize하거나 null/empty 의미를 명시
두 필드 사이 관계 Entity / Value Object / Snapshot 내부 invariant

Require.text는 null, empty, blank를 모두 거부한다. Require.nonNull은 null만 거부한다. 둘은 같은 검증이 아니다.

다음과 같은 관계 invariant는 공통 Guard로 옮기지 않는다.

  • LessonSchedule.startTime < endTime
  • Semester.startDate <= endDate
  • Semester.registrationStartAt < registrationEndAt
  • LessonPolicySnapshot.registrationStartAt < registrationEndAt
  • RegistrationDecisionSnapshot.enrolledCount >= 0

optional normalization도 required invariant와 구분한다. 예를 들어 Subject.description == null은 빈 문자열로 normalize하고, optional request parameter나 idempotency header의 blank 처리는 application/infrastructure 경계에서 별도로 처리한다.

Value Object selection

이번 리팩터링에서는 primitive/String을 일괄 Value Object로 올리지 않는다.

  • Credit: 여러 위치에 있지만 현재 독립 행동보다 positive invariant 비중이 크다. Require.positive로 중복을 제거하고 유지한다.
  • Grade: 동일하다. 별도 타입이 필요한 정책 행동이 늘어날 때 재검토한다.
  • Capacity: 동일하다. 정원 경쟁 자체는 registration policy/locking 책임이며 숫자 타입의 행동은 아직 없다.
  • RegistrationWindow: cross-field 의미와 행동이 있어 가장 강한 Domain VO 후보지만 현재 LessonPolicySnapshot 한 곳이 소유한다. 재사용 경계가 생길 때 추출한다.
  • IdempotencyKey: business domain이 아니라 registration application concern이다. 별도 타입이 필요해지면 Domain VO가 아니라 application boundary value로 둔다.

Value Object는 같은 검증이 반복된다는 이유만으로 만들지 않는다. 도메인 의미, 타입 혼동 위험, 관련 행동, 규칙 확장성 중 하나 이상이 실제로 커질 때 도입한다.