From bc84faf7a8881c3c2e0644c1404d827466246184 Mon Sep 17 00:00:00 2001 From: Klaus Date: Thu, 19 Nov 2026 14:21:56 +0900 Subject: [PATCH] =?UTF-8?q?build(test):=20=EA=B0=80=EC=9A=A9=20=EB=A9=94?= =?UTF-8?q?=EB=AA=A8=EB=A6=AC=EB=A1=9C=20=ED=85=8C=EC=8A=A4=ED=8A=B8=20?= =?UTF-8?q?=ED=9E=99=EC=9D=84=20=EC=82=B0=EC=A0=95=ED=95=98=EA=B3=A0=20?= =?UTF-8?q?=EC=9B=8C=EC=BB=A4=20=EC=88=98=EB=AA=85=EC=9D=84=20=EC=A0=9C?= =?UTF-8?q?=ED=95=9C=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- build.gradle.kts | 28 +++- buildSrc/build.gradle.kts | 20 +++ .../main/java/buildlogic/TestHeapPolicy.java | 124 +++++++++++++++ .../java/buildlogic/TestHeapPolicyTest.java | 149 ++++++++++++++++++ docs/agent-guides/실행명령어.md | 11 ++ 5 files changed, 331 insertions(+), 1 deletion(-) create mode 100644 buildSrc/build.gradle.kts create mode 100644 buildSrc/src/main/java/buildlogic/TestHeapPolicy.java create mode 100644 buildSrc/src/test/java/buildlogic/TestHeapPolicyTest.java diff --git a/build.gradle.kts b/build.gradle.kts index 0552043c..6efde370 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -1,3 +1,4 @@ +import buildlogic.TestHeapPolicy import org.jetbrains.kotlin.gradle.tasks.KotlinCompile plugins { @@ -108,8 +109,33 @@ tasks.withType { tasks.withType().configureEach { useJUnitPlatform() - maxHeapSize = "4g" + maxParallelForks = 1 + forkEvery = 50 + systemProperty("spring.test.context.cache.maxSize", 4) jvmArgs("-Dfile.encoding=UTF-8") + + val gcLogDirectory = layout.buildDirectory.dir("test-gc/$name").get().asFile + doFirst { + val availableBytes = TestHeapPolicy.readAvailableBytes() + val maxWorkers = gradle.startParameter.maxWorkerCount + val heapMiB = TestHeapPolicy.calculateHeapMiB(availableBytes, maxParallelForks, maxWorkers) + maxHeapSize = "${heapMiB}m" + logger.lifecycle( + "Test heap: available estimate={} MiB, workers={}, maxHeap={} MiB (50% budget, 1 GiB native reserve per worker)", + availableBytes / (1024 * 1024), + minOf(maxParallelForks, maxWorkers), + heapMiB + ) + gcLogDirectory.mkdirs() + } + jvmArgs( + "-Xlog:gc*:file=${gcLogDirectory.resolve("gc-%p.log")}:time,uptime,pid,level,tags:filecount=3,filesize=10M" + ) + beforeSuite( + closureOf { + if (className != null) logger.lifecycle("Test class: $className") + } + ) } tasks.getByName("jar") { diff --git a/buildSrc/build.gradle.kts b/buildSrc/build.gradle.kts new file mode 100644 index 00000000..2b9a71d4 --- /dev/null +++ b/buildSrc/build.gradle.kts @@ -0,0 +1,20 @@ +plugins { + java +} + +repositories { + mavenCentral() +} + +java { + toolchain.languageVersion.set(JavaLanguageVersion.of(17)) +} + +dependencies { + testImplementation("org.junit.jupiter:junit-jupiter-api:5.8.2") + testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:5.8.2") +} + +tasks.test { + useJUnitPlatform() +} diff --git a/buildSrc/src/main/java/buildlogic/TestHeapPolicy.java b/buildSrc/src/main/java/buildlogic/TestHeapPolicy.java new file mode 100644 index 00000000..0e1dfcd0 --- /dev/null +++ b/buildSrc/src/main/java/buildlogic/TestHeapPolicy.java @@ -0,0 +1,124 @@ +package buildlogic; + +import com.sun.management.OperatingSystemMXBean; +import java.io.IOException; +import java.io.InputStream; +import java.io.OutputStream; +import java.lang.management.ManagementFactory; +import java.nio.charset.StandardCharsets; +import java.util.concurrent.TimeUnit; +import java.util.regex.Matcher; +import java.util.regex.Pattern; + +public final class TestHeapPolicy { + private static final long MIB = 1L << 20; + private static final long WORKER_RESERVE_BYTES = 1L << 30; + private static final long MINIMUM_HEAP_MIB = 4096; + private static final Pattern PAGE_SIZE = Pattern.compile( + "Mach Virtual Memory Statistics:\\s*\\(page size of ([0-9]+) bytes\\)" + ); + private static final Pattern PAGE_COUNTER = Pattern.compile("Pages (free|inactive)\\s*:\\s*([0-9]+)\\.?"); + + private TestHeapPolicy() { + } + + public static long calculateHeapMiB(long availableBytes, int maxParallelForks, int maxWorkers) { + if (availableBytes <= 0 || maxParallelForks <= 0 || maxWorkers <= 0) { + throw new IllegalArgumentException("Available bytes, maxParallelForks and maxWorkers must be positive"); + } + + int effectiveWorkers = Math.min(maxParallelForks, maxWorkers); + long perWorkerBytes = availableBytes / 2 / effectiveWorkers; + long heapMiB = (perWorkerBytes - WORKER_RESERVE_BYTES) / MIB; + if (heapMiB < MINIMUM_HEAP_MIB) { + throw new IllegalStateException( + "Insufficient test memory: availableBytes=" + availableBytes + ", effectiveWorkers=" + effectiveWorkers + + ", minimumHeapMiB=" + MINIMUM_HEAP_MIB + ". Close other applications or reduce workers." + ); + } + return heapMiB; + } + + public static long readAvailableBytes() { + long availableBytes; + if (System.getProperty("os.name").startsWith("Mac")) { + ProcessBuilder builder = new ProcessBuilder("/usr/bin/vm_stat").redirectErrorStream(true); + builder.environment().put("LC_ALL", "C"); + try { + Process process = builder.start(); + try ( + InputStream output = process.getInputStream(); + InputStream error = process.getErrorStream(); + OutputStream input = process.getOutputStream() + ) { + if (!process.waitFor(5, TimeUnit.SECONDS)) { + throw new IllegalStateException("vm_stat did not finish within 5 seconds"); + } + if (process.exitValue() != 0) { + throw new IllegalStateException("vm_stat failed with exit code " + process.exitValue()); + } + availableBytes = parseMacVmStat(new String(output.readAllBytes(), StandardCharsets.US_ASCII)); + } finally { + process.destroyForcibly(); + } + } catch (InterruptedException failure) { + Thread.currentThread().interrupt(); + throw new IllegalStateException("Interrupted while reading available memory with vm_stat", failure); + } catch (IOException failure) { + throw new IllegalStateException("Unable to read available memory with vm_stat", failure); + } + } else { + OperatingSystemMXBean operatingSystem = ManagementFactory.getPlatformMXBean(OperatingSystemMXBean.class); + if (operatingSystem == null) { + throw new IllegalStateException("OperatingSystemMXBean free-memory observation is unavailable"); + } + availableBytes = operatingSystem.getFreeMemorySize(); + } + if (availableBytes <= 0) { + throw new IllegalStateException("Available-memory observation must be positive: availableBytes=" + availableBytes); + } + return availableBytes; + } + + static long parseMacVmStat(String output) { + long pageSize = -1; + long freePages = -1; + long inactivePages = -1; + try { + for (String rawLine : output.lines().toList()) { + String line = rawLine.strip(); + if (line.startsWith("Mach Virtual Memory Statistics")) { + Matcher header = PAGE_SIZE.matcher(line); + if (pageSize >= 0 || !header.matches()) { + throw new IllegalArgumentException("Duplicate or malformed vm_stat page-size header: " + line); + } + pageSize = Long.parseLong(header.group(1)); + } else if (line.startsWith("Pages free") || line.startsWith("Pages inactive")) { + Matcher counter = PAGE_COUNTER.matcher(line); + if (!counter.matches()) { + throw new IllegalArgumentException("Malformed vm_stat page counter: " + line); + } + long pages = Long.parseLong(counter.group(2)); + if (counter.group(1).equals("free")) { + if (freePages >= 0) { + throw new IllegalArgumentException("Duplicate vm_stat Pages free counter"); + } + freePages = pages; + } else { + if (inactivePages >= 0) { + throw new IllegalArgumentException("Duplicate vm_stat Pages inactive counter"); + } + inactivePages = pages; + } + } + } + if (pageSize <= 0 || freePages < 0 || inactivePages < 0) { + throw new IllegalArgumentException("vm_stat requires a positive page size and both free and inactive counters"); + } + // Raw free already includes speculative pages; do not subtract or add them separately. + return Math.multiplyExact(Math.addExact(freePages, inactivePages), pageSize); + } catch (NumberFormatException | ArithmeticException failure) { + throw new IllegalArgumentException("vm_stat page size or counters exceed the supported long range", failure); + } + } +} diff --git a/buildSrc/src/test/java/buildlogic/TestHeapPolicyTest.java b/buildSrc/src/test/java/buildlogic/TestHeapPolicyTest.java new file mode 100644 index 00000000..1c4cd754 --- /dev/null +++ b/buildSrc/src/test/java/buildlogic/TestHeapPolicyTest.java @@ -0,0 +1,149 @@ +package buildlogic; + +import java.util.Arrays; +import java.util.stream.Stream; +import org.junit.jupiter.api.DynamicTest; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.TestFactory; + +import static org.junit.jupiter.api.Assertions.assertAll; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.junit.jupiter.api.DynamicTest.dynamicTest; + +class TestHeapPolicyTest { + private static final long MIB = 1L << 20; + private static final long GIB = 1L << 30; + + @TestFactory + Stream shouldCalculateHeapWithinTheAvailableWorkerBudget() { + return Stream.of( + dynamicTest("10 GiB reaches the 4096 MiB floor", () -> + assertEquals(4096, TestHeapPolicy.calculateHeapMiB(10 * GIB, 1, 1))), + dynamicTest("20 GiB supports two workers at the floor", () -> + assertEquals(4096, TestHeapPolicy.calculateHeapMiB(20 * GIB, 2, 2))), + dynamicTest("13 GiB leaves half and the per-worker reserve", () -> + assertEquals(5632, TestHeapPolicy.calculateHeapMiB(13 * GIB, 1, 1))), + dynamicTest("max workers caps four requested forks", () -> + assertEquals(7168, TestHeapPolicy.calculateHeapMiB(32 * GIB, 4, 2))), + dynamicTest("max forks caps four available workers", () -> + assertEquals(7168, TestHeapPolicy.calculateHeapMiB(32 * GIB, 2, 4))), + dynamicTest("fractional MiB rounds down", () -> + assertEquals(5632, TestHeapPolicy.calculateHeapMiB(13 * GIB + 2 * MIB - 1, 1, 1))), + dynamicTest("an exact additional MiB is retained", () -> + assertEquals(5633, TestHeapPolicy.calculateHeapMiB(13 * GIB + 2 * MIB, 1, 1))), + dynamicTest("the largest positive long does not overflow", () -> + assertEquals(4_398_046_510_079L, TestHeapPolicy.calculateHeapMiB(Long.MAX_VALUE, 1, 1))) + ); + } + + @TestFactory + Stream shouldRejectInsufficientBudgetsWithActionableDiagnostics() { + return Stream.of( + new long[] {10 * GIB - 1, 1, 1}, + new long[] {20 * GIB - 1, 4, 2}, + new long[] {1, 1, 1}, + new long[] {GIB, 1, 1}, + new long[] {2 * GIB, 1, 1}, + new long[] {8 * GIB, 1, 1} + ).map(input -> dynamicTest(Arrays.toString(input), () -> { + IllegalStateException failure = assertThrows(IllegalStateException.class, () -> + TestHeapPolicy.calculateHeapMiB(input[0], (int) input[1], (int) input[2])); + + String message = failure.getMessage(); + assertAll( + () -> assertTrue(message.contains("availableBytes=" + input[0]), message), + () -> assertTrue(message.contains("effectiveWorkers=" + Math.min(input[1], input[2])), message), + () -> assertTrue(message.contains("minimumHeapMiB=4096"), message), + () -> assertTrue(message.contains("Close other applications"), message), + () -> assertTrue(message.contains("reduce workers"), message) + ); + })); + } + + @TestFactory + Stream shouldRejectNonpositiveAvailabilityOrWorkerLimits() { + return Stream.of( + new long[] {0, 1, 1}, + new long[] {-1, 1, 1}, + new long[] {Long.MIN_VALUE, 1, 1}, + new long[] {10 * GIB, 0, 1}, + new long[] {10 * GIB, -1, 1}, + new long[] {10 * GIB, Integer.MIN_VALUE, 1}, + new long[] {10 * GIB, 1, 0}, + new long[] {10 * GIB, 1, -1}, + new long[] {10 * GIB, 1, Integer.MIN_VALUE} + ).map(input -> dynamicTest(Arrays.toString(input), () -> + assertThrows(IllegalArgumentException.class, () -> + TestHeapPolicy.calculateHeapMiB(input[0], (int) input[1], (int) input[2])))); + } + + @TestFactory + Stream shouldParseOnlyRawFreeAndInactivePages() { + return Stream.of( + dynamicTest("4K pages ignore speculative and file-backed counts", () -> + assertEquals(2_371_584, TestHeapPolicy.parseMacVmStat(""" + Mach Virtual Memory Statistics: (page size of 4096 bytes) + Pages free: 123. + Pages speculative: 100. + Pages inactive: 456. + File-backed pages: 999. + """))), + dynamicTest("16K pages accept reordered counters and whitespace", () -> + assertEquals(81_920, TestHeapPolicy.parseMacVmStat(""" + Mach Virtual Memory Statistics: (page size of 16384 bytes) + Pages inactive : 3. + Pages active: 999. + Pages free:\t2. + """))), + dynamicTest("both raw counters may be zero", () -> + assertEquals(0, TestHeapPolicy.parseMacVmStat(vmStat("4096", "0", "0")))), + dynamicTest("counters need not have trailing periods", () -> + assertEquals(20_480, TestHeapPolicy.parseMacVmStat( + vmStat("4096", "2", "3").replace(".\n", "\n")))), + dynamicTest("the largest representable byte count remains valid", () -> + assertEquals(Long.MAX_VALUE, TestHeapPolicy.parseMacVmStat(vmStat("1", "9223372036854775806", "1")))) + ); + } + + @TestFactory + Stream shouldRejectMissingDuplicateMalformedNegativeOrOverflowingVmStatFields() { + String valid = vmStat("4096", "2", "3"); + return Stream.of( + "", + "Pages free: 2.\nPages inactive: 3.\n", + "page size of 4096 bytes\nPages free: 2.\nPages inactive: 3.\n", + valid.replace("Pages free: 2.\n", ""), + valid.replace("Pages inactive: 3.\n", ""), + valid + "Pages free: 2.\n", + valid + "Pages inactive: 3.\n", + valid + "Mach Virtual Memory Statistics: (page size of 4096 bytes)\n", + valid + "Pages free: broken.\n", + vmStat("4096", "-1", "3"), + vmStat("4096", "2", "-1"), + vmStat("-4096", "2", "3"), + vmStat("0", "2", "3"), + vmStat("invalid", "2", "3"), + vmStat("4096", "2x", "3"), + vmStat("4096", "2", "3.5"), + valid.replace("Pages free:", "Pages free"), + valid.replace("bytes)", "bytes) trailing"), + vmStat("9223372036854775808", "2", "3"), + vmStat("4096", "9223372036854775808", "3"), + vmStat("1", "9223372036854775807", "1"), + vmStat("4096", "2251799813685248", "0") + ).map(output -> dynamicTest("rejects " + output.replace('\n', ' '), () -> + assertThrows(IllegalArgumentException.class, () -> TestHeapPolicy.parseMacVmStat(output)))); + } + + @Test + void shouldReadPositiveAvailabilityFromTheCurrentOperatingSystem() { + assertTrue(TestHeapPolicy.readAvailableBytes() > 0); + } + + private static String vmStat(String pageSize, String free, String inactive) { + return "Mach Virtual Memory Statistics: (page size of " + pageSize + " bytes)\n" + + "Pages free: " + free + ".\nPages inactive: " + inactive + ".\n"; + } +} diff --git a/docs/agent-guides/실행명령어.md b/docs/agent-guides/실행명령어.md index 055caa38..2e5efdb1 100644 --- a/docs/agent-guides/실행명령어.md +++ b/docs/agent-guides/실행명령어.md @@ -44,6 +44,17 @@ 위 명령은 목적에 맞게 하나를 선택한다. 전체 테스트 확인만 필요하면 `./gradlew test`로 충분하다. +## 테스트 메모리와 진행 진단 +- IntelliJ의 `Build, Execution, Deployment > Build Tools > Gradle > Run tests using`을 `Gradle`로 맞추면 CLI와 같은 테스트 JVM 설정을 사용한다. IDE 자체 JUnit runner는 Gradle의 heap/worker 설정을 적용하지 않는다. +- 테스트 JVM heap은 Test task 실행 직전에 가용 메모리로 계산한다. 가용 추정의 50%를 유효 동시 worker 수(`min(maxParallelForks, maxWorkers)`)로 나누고 worker마다 힙 외 1GiB를 남긴 뒤 MiB 단위로 내린 값을 명시적 `maxHeapSize`로 전달한다. 계산값이 4GiB 미만이면 올려 할당하지 않고 worker 시작 전에 실패한다. 4GiB는 기존 검증을 유지하는 보수적 실행 하한이며, 실제 최소 필요량을 증명한 수치는 아니다. +- macOS 가용 추정은 `vm_stat`의 `(Pages free + Pages inactive) × page size`이며 speculative/file-backed를 별도로 더하지 않는다. 다른 OS는 JDK의 free-memory 관측값을 보수적으로 사용하므로 회수 가능한 캐시를 충분히 반영하지 못할 수 있다. 가용 추정은 OS의 할당 보장이 아니며 다른 앱의 이후 사용량도 예측하지 못한다. +- 콘솔의 `Test heap:`에서 관측값·유효 worker 수·선택한 상한을 확인한다. task 시작 때 한 번 계산하며 교체된 worker도 동일한 상한을 사용한다. 메모리 부족 오류가 나면 다른 프로그램/중복 테스트를 정리한 뒤 다시 실행한다. 기존 `maxHeapSize`만 지워 Gradle 기본 512MB로 돌아가거나, 비율 옵션만 추가하는 방식은 사용하지 않는다. +- 동시 worker 1개, Spring context 캐시 최대 4개, 50개 테스트 클래스마다 worker 교체는 유지한다. 클래스 수 기준이므로 단일 클래스의 과도한 사용까지 방지하지는 않는다. Gradle daemon heap과 테스트 worker heap은 별개다. 같은 저장소의 전체 테스트를 IDE와 CLI/에이전트에서 동시에 시작하지 않는다. +- 실행 콘솔의 `Test class:`는 클래스 시작 위치이며 완료 또는 성공 표시가 아니다. 최종 종료 코드와 `build/test-results/test/`의 해당 실행 XML을 함께 확인한다. +- GC 로그는 `build/test-gc//gc-.log`에 기록한다. PID별 10MB 파일과 회전 로그 최대 3개를 사용한다. 오래된 실행 로그는 조사 후 정리한다. +- 후반에 진행이 멈추면 해당 worker PID의 `jstat -gcutil `와 GC 로그를 확인한다. Old 사용률이 높고 Full GC 시간만 증가하는 상태에서는 실행 제한만 늘리지 않는다. 타인이 시작한 worker는 승인 없이 종료하지 않는다. +- 힙 예산 build logic를 변경하면 `./gradlew --no-daemon -p buildSrc test --tests 'buildlogic.TestHeapPolicyTest'`로 산정·파싱 경계를 검증한다. 이 테스트는 애플리케이션의 root `test`와 별도이며, 일반 root 실행에서 buildSrc 컴파일만 됐다고 테스트까지 통과한 것으로 보지 않는다. + ## AWS 의존성 확인 기존 SDK v1은 유지하고 Comprehend/Translate만 SDK v2 BOM `2.57.11`을 사용한다. 기본 동기 HTTP runtime은 전이 의존성이다.