Gradle 빌드와 테스트

수작업 컴파일의 벽과 빌드 도구의 탄생

초보 시절에는 명령 줄 터미널에서 javac Main.java를 입력해 컴파일하고 java Main으로 프로그램을 실행하는 것만으로도 충분했습니다. 소스 파일이 서너 개에 불과하고 외부 라이브러리를 쓰지 않을 때는 이 수작업 방식이 언어의 동작 원리를 이해하는 데 유익합니다.

하지만 실무 엔터프라이즈 환경이나 상용 게임 애플리케이션을 개발하게 되면 다음과 같은 거대한 현실적 장벽에 부딪히게 됩니다.

1. 대규모 파일 의존 관계: 수백 개 이상의 .java 파일이 수십 개의 패키지에 분산되어 있어 컴파일 순서를 사람이 일일이 계산하기 불가능합니다.
2. 복잡한 서드파티 라이브러리 연동: JSON 직렬화를 위해 Jackson 또는 Gson이 필요하고, 데이터베이스 통신을 위해 HikariCP와 JDBC 드라이버가 필요하며, 단위 검증을 위해 JUnit과 AssertJ가 필요합니다.
3. 전이적 의존성(Transitive Dependencies) 문제: 내가 가져온 라이브러리 A가 라이브러리 B의 특정 버전을 요구하고, 라이브러리 C는 또 다른 버전을 요구할 때 수동으로 .jar를 다운로드하면 치명적인 클래스패스 충돌(Classpath Conflict)이 일어납니다.
4. 품질 검증과 배포 자동화의 부재: 코드를 고칠 때마다 단위 테스트 수백 개를 실행해 결함을 찾아내고, 문제가 없을 때만 단일 실행 가능한 .jar 파일로 압축 패키징하는 일련의 파이프라인을 매번 손으로 반복할 수는 없습니다.

**빌드 도구(Build Tool)**는 소스 코드의 컴파일, 외부 라이브러리 다운로드와 버전 충돌 해결, 정적 분석과 단위 테스트 실행, 최종 산출물 패키징에 이르는 소프트웨어의 전체 수명주기 태스크를 코드로 정의하고 자동화하는 전문 소프트웨어입니다. 현대 Java 생태계의 표준 빌드 도구인 **Gradle(그레이들)**은 유연한 스크립트 작성과 혁신적인 증분 빌드 성능으로 전 세계 개발팀에서 사실상의 표준으로 자리 잡았습니다.

표준 프로젝트 디렉터리 구조와 관례

Gradle은 “설정보다 관례(Convention over Configuration)“라는 중요한 철학을 따릅니다. 프레임워크가 미리 정해둔 표준 디렉터리 구조를 지키면 복잡한 경로 설정을 일일이 명시하지 않아도 Gradle이 소스 코드와 리소스, 테스트 파일을 알아서 인식합니다.

my-voxel-project/
├── gradlew                  # Linux 및 macOS용 Gradle Wrapper 실행 셸 스크립트
├── gradlew.bat              # Windows용 Gradle Wrapper 실행 배치 파일
├── gradle/
│   └── wrapper/
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties  # 다운로드할 Gradle 버전 명시
├── build.gradle             # 프로젝트 핵심 빌드 명세서 (플러그인, 의존성 설정)
├── settings.gradle          # 프로젝트 루트 명칭 및 서브 모듈 정의
└── src/
    ├── main/                # 실제 배포 및 실행에 사용되는 제품 소스 코드
    │   ├── java/            # 자바 소스 파일 (.java)
    │   └── resources/       # 런타임 설정 파일 (.properties, .json 등)
    └── test/                # 소프트웨어 검증을 위한 단위 및 통합 테스트 코드
        ├── java/            # JUnit 테스트 소스 파일 (Test.java)
        └── resources/       # 테스트 전용 모의(Mock) 데이터 및 테스트 설정

이 표준 구조 덕분에 새로운 프로젝트에 합류한 개발자라도 단 1초의 망설임 없이 src/main/java에서 비즈니스 로직을 탐색하고 src/test/java에서 기능 명세서를 읽어 내려갈 수 있습니다.

build.gradle 핵심 설정 파헤치기

프로젝트 루트에 위치한 build.gradle 파일은 프로젝트의 정체성을 규정하는 설계도입니다. Java 25 환경을 기준으로 실무에서 작성되는 핵심 블록들을 자세히 살펴보겠습니다.

plugins {
    id 'java'
    id 'application'
}

group = 'com.toolpado.voxel'
version = '1.0.0'

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(25)
    }
}

repositories {
    mavenCentral()
}

dependencies {
    // 실무 데이터 처리를 위한 Gson 라이브러리
    implementation 'com.google.code.gson:gson:2.11.0'

    // 단위 테스트를 위한 최신 JUnit 5 프레임워크
    testImplementation platform('org.junit:junit-bom:5.11.0')
    testImplementation 'org.junit.jupiter:junit-jupiter'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}

application {
    mainClass = 'com.toolpado.voxel.Main'
}

tasks.named('test') {
    useJUnitPlatform()
}

tasks.named('jar') {
    manifest {
        attributes(
            'Implementation-Title': project.name,
            'Implementation-Version': project.version,
            'Main-Class': 'com.toolpado.voxel.Main'
        )
    }
}

각 설정 블록의 역할

• plugins 블록: Java 애플리케이션 빌드에 필요한 표준 태스크들(compileJava, processResources, classes, test, jar)을 프로젝트에 주입합니다. application 플러그인은 터미널에서 즉시 메인 클래스를 구동할 수 있는 run 태스크를 제공합니다.
• java.toolchain 블록: 개발자 컴퓨터나 배포 서버의 환경 변수에 어떤 자바 버전이 깔려 있든 상관없이, Gradle이 프로젝트에 필요한 Java 25 LTS JDK를 로컬에서 직접 찾아 컴파일러로 지정합니다. 필요하다면 공인 OpenJDK 바이너리를 인터넷에서 자동으로 다운로드하기도 합니다.
• repositories 블록: 외부 라이브러리를 어디서 가져올지 원격 창고를 등록합니다. mavenCentral()은 전 세계 수백만 개의 검증된 오픈소스 자바 라이브러리가 호스팅되는 공인 중앙 리포지토리입니다.
• dependencies 블록: 내 프로젝트가 의존하는 라이브러리 목록을 선언합니다. implementation은 제품 코드와 테스트 모두에서 사용하는 라이브러리이며, testImplementation은 오직 단위 테스트를 돌릴 때만 포함되는 의존성입니다.

의존성 선언 스코프의 차이

Gradle은 빌드 산출물의 불필요한 비대화를 막고 모듈 간 캡슐화를 보호하기 위해 정교한 의존성 스코프(Configuration)를 제공합니다.

스코프 (Scope)	컴파일 시점 노출	런타임 클래스패스 포함	주 사용 목적
implementation	현재 모듈 컴파일에 노출	포함됨	내부 구현에 쓰이는 핵심 서드파티 라이브러리
compileOnly	현재 모듈 컴파일에 노출	포함 안 됨	Lombok, Servlet API처럼 컴파일 시점에만 필요한 애노테이션이나 도구
runtimeOnly	컴파일에 노출 안 됨	포함됨	MySQL/PostgreSQL JDBC 드라이버, 로깅 구현체(Logback)
testImplementation	테스트 코드 컴파일에만 노출	테스트 런타임에만 포함	JUnit 5, Mockito, AssertJ 등 테스트 검증 프레임워크

초보 개발자들은 모든 라이브러리를 무심코 implementation으로 선언하는 실수를 저지릅니다. 하지만 테스트 프레임워크나 컴파일 전용 도구를 배포 패키지에 불필요하게 포함하면 .jar 용량이 수십 메가바이트 이상 낭비되고 보안 취약점 노출 면적이 넓어집니다. 따라서 목적에 맞는 정확한 스코프 선택이 실무의 기본 소양입니다.

Gradle Wrapper(gradlew)의 마법과 동작 원리

새로운 동료가 팀에 합류했을 때 “공식 웹사이트에서 Gradle 8.10을 다운로드받아 PATH 환경변수를 설정하라”고 가이드하는 것은 대단히 원시적인 방식입니다. 각 팀원의 Gradle 마이너 버전이 다르면 빌드 캐시가 깨지거나 예기치 않은 스크립트 파싱 에러가 발생합니다.

Gradle은 프로젝트 초기화 시 Gradle Wrapper라는 가벼운 부트스트랩 스크립트(gradlew, gradlew.bat)와 래퍼 바이너리(gradle-wrapper.jar)를 함께 생성합니다.

# Linux 및 macOS 환경에서의 실행
./gradlew build

# Windows 환경에서의 실행
gradlew.bat build

Wrapper 스크립트가 실행되면 내부적으로 다음 세 단계를 거칩니다.

1. gradle/wrapper/gradle-wrapper.properties 파일에 기재된 distributionUrl의 버전을 읽습니다.
2. 사용자 홈 디렉터리의 캐시 폴더(~/.gradle/wrapper/dists)를 검사하여 해당 버전의 Gradle 바이너리가 이미 존재하는지 확인합니다.
3. 로컬에 없다면 공식 서버에서 즉시 압축 파일을 안전하게 다운로드하여 압축을 푼 뒤, 프로젝트 빌드 태스크를 실행합니다.

즉, 모든 개발자와 자동화된 CI/CD 배포 서버가 한 줄의 환경 설정도 없이 완전히 동일한 Gradle 버전으로 빌드를 재현할 수 있게 됩니다. 이것이 gradlew 스크립트를 Git 저장소에 반드시 포함해야 하는 이유입니다.

제품 코드와 JUnit 5 단위 테스트 작성 실습

이제 Gradle 환경에서 실제로 작동하는 voxel 게임의 장비 내구도와 데미지 계산 서비스를 구현하고, 이를 자동으로 검증하는 JUnit 5 단위 테스트를 작성해 보겠습니다.

1. 제품 소스 코드 (src/main/java/com/toolpado/voxel/CombatService.java)

package com.toolpado.voxel;

public class CombatService {
    public record CombatResult(int finalDamage, int absorbedDamage, int remainingArmor) {}

    public CombatResult resolveDamage(int rawDamage, int currentArmorDurability) {
        if (rawDamage < 0) {
            throw new IllegalArgumentException("피해 수치는 음수일 수 없습니다: " + rawDamage);
        }
        if (currentArmorDurability < 0) {
            currentArmorDurability = 0;
        }

        // 방어구가 데미지의 절반을 흡수하되 잔여 내구도를 초과할 수 없음
        int maxAbsorb = rawDamage / 2;
        int actualAbsorb = Math.min(maxAbsorb, currentArmorDurability);

        // 공격력이 방어구를 뚫더라도 최소 1의 피해는 무조건 발생
        int finalDamage = Math.max(1, rawDamage - actualAbsorb);
        int remainingArmor = currentArmorDurability - actualAbsorb;

        return new CombatResult(finalDamage, actualAbsorb, remainingArmor);
    }
}

2. 메인 실행 애플리케이션 (src/main/java/com/toolpado/voxel/Main.java)

package com.toolpado.voxel;

public class Main {
    public static void main(String[] args) {
        CombatService combatService = new CombatService();

        System.out.println("=== Voxel Combat Engine (Java 25 + Gradle) ===");
        var result1 = combatService.resolveDamage(40, 30);
        System.out.println("공격력 40, 방어구 30 결과: " + result1);

        var result2 = combatService.resolveDamage(10, 2);
        System.out.println("공격력 10, 방어구 2 결과: " + result2);

        var result3 = combatService.resolveDamage(2, 50);
        System.out.println("공격력 2, 방어구 50 결과 (최소 데미지 보장): " + result3);
    }
}

예상 출력

=== Voxel Combat Engine (Java 25 + Gradle) ===
공격력 40, 방어구 30 결과: CombatResult[finalDamage=20, absorbedDamage=20, remainingArmor=10]
공격력 10, 방어구 2 결과: CombatResult[finalDamage=8, absorbedDamage=2, remainingArmor=0]
공격력 2, 방어구 50 결과 (최소 데미지 보장): CombatResult[finalDamage=1, absorbedDamage=1, remainingArmor=49]

3. JUnit 5 단위 테스트 (src/test/java/com/toolpado/voxel/CombatServiceTest.java)

사람이 매번 콘솔 출력창을 쳐다보며 숫자가 맞는지 확인하는 것은 실수가 생기기 마련입니다. 기댓값을 단언문(Assertion)으로 명문화하여 자동 검증합니다.

package com.toolpado.voxel;

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

class CombatServiceTest {
    private final CombatService combatService = new CombatService();

    @Test
    @DisplayName("방어구 내구도가 넉넉하면 피해의 절반을 흡수하고 내구도가 차감된다")
    void shouldAbsorbHalfDamageWhenArmorIsSufficient() {
        var result = combatService.resolveDamage(50, 40);

        assertEquals(25, result.finalDamage(), "최종 피해는 원 데미지(50)에서 흡수량(25)을 뺀 25여야 합니다.");
        assertEquals(25, result.absorbedDamage(), "흡수량은 원 데미지의 절반인 25여야 합니다.");
        assertEquals(15, result.remainingArmor(), "잔여 방어구는 40에서 25를 차감한 15여야 합니다.");
    }

    @Test
    @DisplayName("방어구 내구도가 부족하면 남은 방어구 내구도만큼만 흡수한다")
    void shouldAbsorbOnlyRemainingArmorWhenDurabilityIsLow() {
        var result = combatService.resolveDamage(50, 10);

        assertEquals(40, result.finalDamage(), "최종 피해는 50에서 잔여 내구도 10을 뺀 40이어야 합니다.");
        assertEquals(10, result.absorbedDamage(), "흡수량은 방어구 잔여 내구도인 10이어야 합니다.");
        assertEquals(0, result.remainingArmor(), "방어구는 모두 소모되어 0이어야 합니다.");
    }

    @Test
    @DisplayName("아무리 방어력이 높아도 최소 1의 피해는 항상 관통한다")
    void shouldDealAtLeastOneDamageEvenWithHighArmor() {
        var result = combatService.resolveDamage(2, 100);

        assertEquals(1, result.finalDamage(), "최소 1의 데미지가 보장되어야 합니다.");
        assertEquals(1, result.absorbedDamage());
        assertEquals(99, result.remainingArmor());
    }

    @Test
    @DisplayName("음수 피해량이 주어지면 IllegalArgumentException이 발생한다")
    void shouldThrowExceptionWhenDamageIsNegative() {
        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, () -> {
            combatService.resolveDamage(-10, 30);
        });

        assertTrue(ex.getMessage().contains("음수일 수 없습니다"));
    }
}

증분 빌드(Incremental Build)와 빌드 캐시의 위력

대규모 상용 시스템에서 전체 코드를 매번 처음부터 컴파일하면 빌드 시간이 10분, 30분 이상으로 늘어납니다. Gradle은 이 문제를 극복하기 위해 혁신적인 최적화 기술들을 내장하고 있습니다.

1. 증분 빌드 (Incremental Build): Gradle은 각 태스크의 입력(Input 파일)과 출력(Output 산출물)의 해시값을 추적합니다. 이전 빌드 이후 입력 파일에 아무런 변경이 없다면 태스크 실행을 생략하고 콘솔에 UP-TO-DATE 표시를 띄웁니다.
2. Gradle 데몬 (Daemon): 백그라운드에 상주하는 긴 수명의 JVM 프로세스로, JIT 컴파일러가 이미 최적화해 둔 웜업(Warm-up) 상태를 유지하여 빌드 시작 오버헤드를 획기적으로 줄여줍니다.
3. 태스크 병렬 실행 (Parallel Execution): 서로 의존 관계가 없는 독립된 서브 프로젝트나 태스크들을 CPU 멀티 코어를 활용해 동시에 병렬 빌드합니다.

터미널에서 테스트를 실행해 보면 다음과 같이 산출물이 검증됩니다.

./gradlew test

모든 테스트가 통과하면 Gradle은 빌드 성공 메시지를 출력하며, 만약 테스트 중 하나라도 실패하면 즉시 빨간색 에러 로그와 함께 상세한 HTML 리포트 경로(build/reports/tests/test/index.html)를 안내합니다.

BUILD SUCCESSFUL in 1s
4 actionable tasks: 4 executed

직접 해보기

Gradle의 의존성 관리와 빌드 검증 파이프라인을 직접 손으로 익혀 봅시다.

미션 과제

1. 새 작업 폴더에서 gradle init --type java-application 명령어로 새 Gradle 프로젝트를 초기화하세요.
2. build.gradle 파일의 dependencies에 com.google.code.gson:gson:2.11.0 의존성을 추가하고 ./gradlew dependencies 명령을 실행해 의존성 트리 그래프를 확인하세요.
3. CombatService.java와 CombatServiceTest.java를 각각 src/main/java와 src/test/java 경로에 배치하세요.
4. 테스트 코드의 단언문 하나를 의도적으로 실패하도록 수정(assertEquals(999, result.finalDamage());)한 뒤 ./gradlew test를 실행하여 Gradle이 빌드를 차단하고 에러를 보고하는 모습을 관찰하세요.
5. 코드를 다시 정상으로 돌려놓고 ./gradlew clean build를 실행하여 최종 .jar 파일이 build/libs/ 폴더에 올바르게 생성되는지 확인하세요.