Files
clean-architecture-backend-…/docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md
T
DongHyeonka 6a792b8144 refactor(layout)!: 옮긴 경로를 부르는 곳을 모두 새 배치에 맞춘다
문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.

고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
  :composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
  이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
  boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
  project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
  gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
  config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
  (getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
  훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
  rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
  src/를 붙인다. notification API surface의 application-notification 소스
  루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
  건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
  폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
  registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
  써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
  env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
  verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
  check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
  operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
  다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
  capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
  docs/upgrade/2026-11-relayout.md를 더한다.

위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.

검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.

BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
2026-11-11 22:15:42 +09:00

8.5 KiB

결정 기록 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 채택
  • 작성일: 2026-09-07
  • 요약: 공유 테스트 코드는 java-test-fixtures 한 가지 방식으로 둔다는 결정이다.
  • 현재 정본: build-logic/README.md

ADR-BUILD-001: 공유 시험 코드의 표준은 java-test-fixtures다

  • 상태: 채택
  • 날짜: 2026-09-07
  • 범위: 공유 시험 코드를 내놓거나 쓰는 모든 leaf
  • 출처: docs/reviews/2026-09-07-app-bootstrap-module-code-review.md BOOT-015

배경

이 저장소에서 같은 일을 하는 규약이 둘 있다.

ca.testkit-publisher — 규약 플러그인 — 는 leaf에 testkit source set을 주고, 그 출력을 leaf가 이름을 댄 lane에 배선하고, 원하면 쓸 수 있는 configuration으로 내놓는다. 다섯 leaf가 쓴다: persistence-jpa(jpaTestkit으로 내놓음), web(webTestkit), websocket(websocketTestkit), persistence-mongo와 httpclient(둘 다 내놓지 않음).

java-test-fixtures — Gradle 자신의 플러그인 — 는 leaf에 testFixtures source set을 주고, 그것을 test의 classpath에 자동으로 올리고, 쓰는 쪽이 testFixtures(project(':x'))로 닿는 variant로 언제나 내놓는다. 한 leaf가 쓴다: graphql. 이 leaf는 fixture를 src/testFixtures/java 밖에 쓰면 빌드를 실패시키기도 한다.

한 목적에 규약 둘이 있는 것이 결함이다. 공유 시험 코드를 더하는 사람은 파일을 어디 둘지 알기 전에 자기가 어느 leaf에 있는지 알아야 하고, 두 답은 서로 바꿔 쓸 수 없다: 첫째를 쓰는 쪽은 project(path: ':x', configuration: 'jpaTestkit')를 쓰고 configuration 이름을 알아야 하지만, 둘째를 쓰는 쪽은 testFixtures(project(':x'))를 쓰고 그럴 필요가 없다.

결정

java-test-fixtures가 표준이다. 새 공유 시험 코드는 src/testFixtures/java에 두고, 쓰는 쪽은 testFixtures(project(':x'))로 의존한다.

이유 셋, 무게 순으로:

  1. 쓰는 쪽이 스스로를 설명한다. testFixtures(project(':adapter:inbound:web'))는 그것이 무엇인지 말한다. project(path: ':adapter:inbound:web', configuration: 'webTestkit')는 어디를 볼지 말하고, 읽는 사람이 webTestkit이 lane이 아니라 testkit임을 배운 뒤에야 뜻이 통한다.
  2. 강제 장치가 이미 있고 복사할 수 있다. graphql의 빌드는 fixture를 엉뚱한 곳에 선언하면 실패한다. 같은 guard를 플러그인을 쓰는 어느 leaf에든 바꾸지 않고 적용한다.
  3. 지역 개념이 하나 준다. Gradle 플러그인을 다시 구현한 규약 플러그인은 그 플러그인에 맞춰 계속 관리해야 한다.

지역 플러그인이 더 잘하는 것과 그것을 대신하는 방법

이것은 적어 둘 만하다. 이 ADR을 낳은 리뷰는 ca.testkit-publisher를 읽기 전에 옮기기를 권했고, 읽어 보니 그 플러그인은 빠뜨린 것이 아니라 일부러 정한 결정 둘을 담고 있었다.

내놓기는 고를 때만 한다. persistence-mongo와 httpclient는 testkit이 있지만 아무것도 내놓지 않는다. persistence-jpa는 내놓는다. 플러그인 자신의 주석이 이것을 "a real difference in what each leaf offers rather than an oversight to normalise away"(각 leaf가 주는 것의 실제 차이이지, 맞춰 없앨 빠뜨림이 아니다)라고 부른다. java-test-fixtures는 언제나 variant를 만드니 이 구별이 사라진다 — fixture를 줄 생각이 없던 leaf도 주게 된다.

대신하는 것: 빌드 수준에서는 없다. 구별은 리뷰로 옮긴다: 아무도 쓰지 않는 leaf의 fixture는 그냥 쓰이지 않는다. 실제 손실이고, 받아들인 손실이다.

lane이 쓰는 것을 선언한다. persistence-jpa는 consumedBy 'test', 'postgresqlIntegrationTest'라고 말한다. java-test-fixtures는 fixture를 test에만 올리니, 다른 모든 lane에는 출력을 명시해서 더해야 한다.

대신하는 것: strictTestLanes의 기존 compilesAgainst가 바꾸지 않고 이것을 나타낸다 — lane이 compilesAgainst 'main', 'testFixtures'를 선언한다. 이 ADR의 첫 초안은 DSL을 바꿔야 한다고 가정했다. sourceSet(name)은 받은 것을 만들고 testFixtures는 이미 있기 때문이다. persistence-mongo를 옮겨 보니 아니었다: compilesAgainst는 source set을 찾기만 하므로, 플러그인이 만든 것의 이름을 대도 그대로 된다. leaf가 버리는 것은 lane의 선언이 아니라 sourceSet('testkit') 선언이다.

옮기기: 끝났고, 든 비용

leaf 다섯, lane 열하나, 내놓은 testkit 둘을 leaf 하나씩, 그 사이마다 suite를 돌리며 모두 옮겼다. ca.testkit-publisher는 지웠다.

순서는 실수가 싸게 끝나도록 골랐다: 내놓지 않는 leaf를 먼저, 내놓는 leaf를 마지막에 그 쓰는 쪽과 같은 단계에서.

  1. persistence-mongo — leaf 하나, lane 둘, 다른 모듈의 쓰는 쪽 없음. 길이 되는지 보는 증명이다. leaf마다 든 일:
    • leaf 빌드 파일 맨 위에 apply plugin: 'java-test-fixtures';
    • git mv src/testkit src/testFixtures;
    • sourceSet('testkit')와 testkitPublisher 블록 전체를 버린다. 다른 모든 lane의 compilesAgainst는 두고 'testkit'을 'testFixtures'로 이름을 바꾼다;
    • testkitImplementation을 testFixturesImplementation으로 이름을 바꾸고, 옛 source set이 소리 없이 물려받던 것을 더한다. 기계적이지 않은 단계는 이것 하나다: testkit*는 testImplementation을 상속해서, fixture가 leaf가 선언한 모든 시험 라이브러리를 봤다. Mongo는 네 줄(AssertJ, BSON, Spring Data commons, Toxiproxy)이 더 필요했다 — leaf가 fixture의 의존으로 적은 적이 한 번도 없는 것들이다;
    • leaf의 잠금 상태를 다시 만든다.
  2. httpclient, 그다음 websocket — 역시 내놓지 않고, lane이 더 많다.
  3. web과 persistence-jpa, 그리고 app-bootstrap의 쓰는 쪽 선언 둘. 그 선언은 testImplementation(testFixtures(project(':…')))가 됐다.
  4. ca.testkit-publisher를 지웠다. 그 plugins {} 항목과 루트 빌드의 적용도 함께.

옮기기가 깨뜨린 것 둘과 그것이 가르친 것

둘 다 바로 이것을 잡으려고 있는 시험이 잡았다. 그런 시험을 둘 이유가 그것이다.

ArchUnit 대상 묶음이 반대 방향으로 틀어졌다. httpclient의 경계 규칙은 build/classes/java/testkit을 뺐다. 옮긴 뒤 fixture는 같은 classpath에 …-test-fixtures.jar로 들어왔고, 그래서 빼기가 그것을 놓쳤으며 fixture 사이 호출 258개가 운영 코드가 testkit에 의존한다고 보고됐다. persistence-jpa의 규칙은 build/classes/java/main만 넣었다. java-test-fixtures를 적용하면 모듈 자신의 시험 classpath가 모듈을 class 디렉터리가 아니라 jar로 싣는다. 그래서 대상 묶음이 비었다. 위험한 쪽은 둘째다 — 빈 묶음이면 모든 noClasses() 규칙이 통과한다 — 그리고 그 suite가 무엇이든 단언하기 전에 묶음이 비어 있지 않음을 단언했기 때문에만 드러났다.

fixture에 보이지 않는 의존이 있었다. testkit* configuration은 testImplementation을 상속해서, fixture는 이름 한 번 대지 않고 leaf가 선언한 모든 시험 라이브러리에 대고 컴파일됐다. 그것을 명시하는 데 다섯 leaf에 걸쳐 testFixturesImplementation 줄이 대략 서른 개 들었다 — Micrometer, Spring Web, Netty, logback, Jackson, JUnit, AssertJ, Spring Data. 틀린 것은 없었다. 적힌 것도 없었다.

결과

  • docs/testing/TESTING_STRATEGY.md §5가 표준을 적는다. 이 ADR은 왜, 어떤 비용으로인지를 적는다.
  • 5단계까지는 규약 둘이 보이는 채로 남는다. 전략 문서가 그것을 분명히 말하므로, 읽는 사람이 어느 것이 지금 것인지 짐작하게 두지 않는다.
  • 고를 때만 내놓는 구별은 포기한다. 나중에 그것이 꼭 필요한 것으로 드러나면 — fixture에 정말 닿으면 안 되는 leaf — 답은 세 번째 규약이 아니라 따로 둔 모듈이다.