문제: 설계서·계획서·납품 패키지·증거·학습 문서와 ADR이 기록이라는 표시 없이 지금 문서처럼 읽힌다. 상태 칸이 설계서 72개 중 40개, 계획서는 거의 없고, 있어도 Approved·확정·Accepted.처럼 값이 제각각이며 영어다. 고른 방법: docs/design, docs/history, docs/adr, docs/notification/adr의 .md 246개 맨 위에 같은 모양의 머리 블록을 단다. 칸은 상태·작성일· 요약(한국어 한 문장)·현재 정본, 대체됐으면 대체됨이다. 블록은 표시 줄 두 개로 감싸서 빼면 원문 바이트가 그대로 돌아온다(246개 모두 대조함). - 종류는 폴더가 정하고 둘째 줄에 적는다(plans/evidence는 증거). - 상태는 원래 상태 줄을 고정 어휘로 바꾼 값이다. 상태 줄이 없는 설계서와 체크 상자가 다 표시되지 않은 계획서는 「확인 안 함」. capability-status.md 제거 표로 지운 것이 확인된 설계서 다섯은 「폐기」, 2026-07-20 하네스 설계·계획과 production capability platform 설계는 「대체됨」이다. - 현재 정본은 구조 정리로 옮겨질 수 있는 src/messaging·src/grpc 대신 docs/ 쪽 문서나 옮기지 않는 leaf README를 가리킨다. docs/README.md에 「문서 수명과 언어」「기록 문서의 머리 블록」「문서와 코드를 같은 변경에서 고친다」를 더하고, 파생 서비스 안내에 머리 블록 충돌 가능성을 적었다. 버린 대안: H1 제목 아래에 블록을 두는 안은 보기에는 낫지만 빼는 규칙이 파일마다 달라져 원문 복원이 기계적이지 않다. 「종류」 칸을 따로 두는 안은 폴더와 같은 정보를 두 번 쓰게 한다. 위험·한계: 「확인 안 함」 설계서 38개, 계획서 51개는 지금 유효한지 아무도 판정하지 않았다. 요약은 제목·목표 줄을 보고 쓴 것이라 본문을 끝까지 읽지 않았다. 납품 패키지 셋의 MANIFEST.sha256는 이제 맞지 않는다 (납품 당시 바이트의 해시이고, 블록을 빼면 다시 맞는다). 리뷰 폴더에는 아직 머리 블록을 달지 않았다. 검증: 머리 블록을 뺀 내용과 HEAD 원본 246개 일치, check-work-docs.py rc=0, --links docs·README.md·CLAUDE.md·AGENTS.md 깨진 링크 0.
7.6 KiB
결정 기록 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-09-07
- 요약: 공유 테스트 코드는 java-test-fixtures 한 가지 방식으로 둔다는 결정이다.
- 현재 정본:
src/build-logic/README.md
ADR-BUILD-001: java-test-fixtures is the standard for shared test code
- Status: Accepted
- Date: 2026-09-07
- Scope: every leaf that publishes or consumes shared test code
- Source:
docs/reviews/2026-09-07-app-bootstrap-module-code-review.mdBOOT-015
Context
Two conventions do the same job in this repository.
ca.testkit-publisher — a convention plugin — gives a leaf a testkit source set, wires its output
onto the lanes that leaf names, and optionally publishes it as a consumable configuration. Five
leaves use it: persistence-jpa (published as jpaTestkit), web (webTestkit), websocket
(websocketTestkit), persistence-mongo and httpclient (both unpublished).
java-test-fixtures — Gradle's own plugin — gives a leaf a testFixtures source set, puts it on
test's classpath automatically, and always publishes it as a variant consumers reach with
testFixtures(project(':x')). One leaf uses it: graphql, which additionally fails its build when a
fixture is written outside src/testFixtures/java.
Two conventions for one purpose is the defect. A contributor adding shared test code has to know
which leaf they are in before they know where the file goes, and the two answers are not
interchangeable: a consumer of the first writes project(path: ':x', configuration: 'jpaTestkit')
and has to know the configuration's name, while a consumer of the second writes
testFixtures(project(':x')) and does not.
Decision
java-test-fixtures is the standard. New shared test code goes in src/testFixtures/java, and a
consumer depends on it with testFixtures(project(':x')).
Three reasons, in order of weight:
- The consumer side describes itself.
testFixtures(project(':adapter:inbound:web'))says what it is.project(path: ':adapter:inbound:web', configuration: 'webTestkit')says where to look, and only after the reader has learned thatwebTestkitis a testkit rather than a lane. - The enforcement already exists and is copyable.
graphql's build fails when a fixture is declared in the wrong place. The same guard applies unchanged to any leaf that adopts the plugin. - It is one fewer local concept. A convention plugin that reimplements a Gradle plugin has to be maintained against it.
What the local plugin does better, and how it is replaced
This is worth writing down, because the review that prompted this ADR recommended the migration
before reading ca.testkit-publisher, and the plugin turns out to encode two deliberate decisions
rather than being an oversight.
Publishing is opt-in. persistence-mongo and httpclient have a testkit and publish nothing;
persistence-jpa publishes. The plugin's own comment names this as "a real difference in what each
leaf offers rather than an oversight to normalise away". java-test-fixtures always creates the
variant, so the distinction is lost — a leaf that never meant to offer its fixtures will offer them.
Replacement: none at the build level. The distinction moves to review: the fixtures of a leaf that nobody consumes are simply unconsumed. This is a real, accepted loss.
Lane consumption is declared. persistence-jpa says consumedBy 'test', 'postgresqlIntegrationTest'.
java-test-fixtures puts fixtures on test only, so every other lane needs the output added
explicitly.
Replacement:
strictTestLanes' existingcompilesAgainstexpresses this unchanged — a lane declarescompilesAgainst 'main', 'testFixtures'. The first draft of this ADR assumed the DSL would need a change, becausesourceSet(name)creates what it is given andtestFixturesalready exists. Thepersistence-mongomigration showed otherwise:compilesAgainstonly looks a source set up, so naming a plugin-created one works as-is. What the leaf drops is thesourceSet('testkit')declaration, not the lane's.
Migration: done, and what it cost
Five leaves, eleven lanes, two published testkits, all migrated leaf by leaf with the suite run
between each. ca.testkit-publisher is deleted.
The order was chosen so a mistake would be cheap: unpublished leaves first, published ones last with their consumer in the same step.
persistence-mongo— one leaf, two lanes, no cross-module consumer; the proof the path works. What it took, per leaf:apply plugin: 'java-test-fixtures'at the top of the leaf build file;git mv src/testkit src/testFixtures;- drop
sourceSet('testkit')and the wholetestkitPublisherblock; keep every other lane'scompilesAgainst, renaming'testkit'to'testFixtures'; - rename
testkitImplementationtotestFixturesImplementation, and add what the old source set was inheriting silently. This is the one non-mechanical step:testkit*extendedtestImplementation, so the fixtures saw every test library the leaf declared. Mongo's needed four more lines (AssertJ, BSON, Spring Data commons, Toxiproxy) — none of which the leaf had ever stated the fixtures depended on; - regenerate the leaf's lock state.
httpclient, thenwebsocket— unpublished as well, more lanes.webandpersistence-jpawithapp-bootstrap's two consumer declarations, which becametestImplementation(testFixtures(project(':…'))).ca.testkit-publisherdeleted, along with itsplugins {}entry and its application in the root build.
Two things the migration broke, and what they taught
Both were caught by tests that exist to catch exactly this, which is the argument for having them.
ArchUnit corpora went wrong in opposite directions. httpclient's boundary rules excluded
build/classes/java/testkit; after the move the fixtures arrived as a …-test-fixtures.jar on the
same classpath, so the exclusion missed them and 258 fixture-to-fixture calls were reported as
production depending on the testkit. persistence-jpa's rules included only
build/classes/java/main; applying java-test-fixtures makes the module's own test classpath carry
the module as a jar rather than as a class directory, so its corpus became empty. The second is
the dangerous one — an empty corpus makes every noClasses() rule pass — and it surfaced only
because that suite asserts its corpus is non-empty before asserting anything about it.
Fixtures had invisible dependencies. testkit* configurations extended testImplementation, so
the fixtures compiled against every test library their leaf declared without ever naming one. Making
them explicit took roughly thirty testFixturesImplementation lines across the five leaves —
Micrometer, Spring Web, Netty, logback, Jackson, JUnit, AssertJ, Spring Data. None of them were
wrong; none of them were stated.
Consequences
docs/testing/TESTING_STRATEGY.md§5 records the standard; this ADR records why and at what cost.- Until step 5, two conventions remain visible. The strategy document says so explicitly, so a contributor reading it is not left to infer which one is current.
- The opt-in-publishing distinction is given up. If it later proves load-bearing — a leaf whose fixtures genuinely must not be reachable — the answer is a separate module, not a third convention.