> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 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 — 답은 세 번째 규약이 아니라 따로 둔 모듈이다.