[Spring Boot] 멀티모듈에 JaCoCo + JaCoCo Report Aggregation 적용하기

macOS
IntelliJ IDEA
Java 17
Spring Boot 3.x
Groovy

📄 JaCoCo

JaCoCo 플러그인 적용

JaCoCo :: Maven Plugin에서 JaCoCo의 최신 버전을 확인할 수 있다.

처음에는 build.gradle에 JaCoCo 태스크를 설정했으나, 너무 복잡해져서 별도로 jacoco.gradle 파일을 생성하여 스크립트를 작성하였다.

// build.gradle
apply from: 'jacoco.gradle'

// jacoco.gradle
subprojects {
    apply plugin: 'jacoco' // Jacoco Plugin 추가

    jacoco {
        toolVersion = '0.8.12'
        // reportsDir = ${project.reporting.baseDir}/jacoco
    }

    test {
        useJUnitPlatform()
    }
}

JaCoCo 플러그인을 추가하고 버전을 설정한 뒤 gradle을 새로고침 하면 JaCoCo 의존성이 추가되면서 각 모듈의 Tasks/verification에 JaCoCo의 Task가 추가된다.

reportsDir을 별도로 설정하지 않은 경우, ${project.reporting.baseDir}/jacoco 가 기본경로로 자동 설정된다.

 

보고서 파일 설정

보고서 파일을 생성하기 위해 jacoco.gradle에 아래 내용을 추가해 준다.

jacocoTestReport {
    reports {
        html.required.set(true)
        xml.required.set(false)
        csv.required.set(false)
    }
}

JaCoCo는 기본적으로 바이너리 보고서인 exec 파일을 생성한다. 이는 사람이 읽을 수 없기 때문에 Jacoco Plugin의 jacocoTestReport 태스크를 통해 exec 파일을 XML, CSV, HTML 파일 형태로 출력할 수 있다. 

 

XML과 CSV 파일은 소스 코드 분석을 위해 소나큐브 등과 연동할 때 사용되며, HTML 파일은 사람이 직접 커버리지를 확인할 때 사용된다.

subprojects {
    apply plugin: 'jacoco'

    jacoco {
        toolVersion = '0.8.12'
    }

    test {
        useJUnitPlatform()
    }

    jacocoTestReport {
        reports {
            html.required.set(true)
            xml.required.set(false)
            csv.required.set(false)
        }
    }
}

 

커버리지 기준 설정

JaCoCo 플러그인에서는 jacocoTestCoverageVerification 태스크로 최소 코드 커버리지 수준을 설정할 수 있고, 기준을 통과하지 못할 경우 태스크가 실패하도록 만들 수 있다.

 

jacocoTestCoverageVerification의 violationRules 메서드를 통해 커버리지 기준을 설정을 정의할 수 있고, 각각의 룰에 대한 설정은 violationRules 메서드에 전달할 rule 메서드를 통해 정의할 수 있다.

jacocoTestCoverageVerification {
    violationRules {
        rule {
            enabled = true
            element = "CLASS"
            limit {
                counter = "LINE"
                value = "COVEREDRATIO"
                minimum = 0.8
            }
            excludes = [
                    '*.*Application'
            ]
        }
        rule {
            // 여러개의 규칙이 가능하다
        }
    }
}

• enabled
  규칙의 활성화 여부를 boolean으로 나타낸다. 기본값은 true이다.
• element
  커버리지를 체크할 기준(단위)을 설정한다. 기본값은 BUNDLE이다.
  • BUNDLE: 패키지 번들 (전체 프로젝트)
  • CLASS: 클래스
  • GROUP: 논리적 번들 그룹
  • METHOD: 메서드
  • PACKAGE: 패키지
  • SOURCEFILE: 소스 파일
• includes
  해당하는 rule의 적용대상을 package 수준으로 정의할 수 있다. 기본값은 전체 package이다.
• counter
  코드 커버리지를 측정할 때 사용되는 지표이다. 기본값은 INSTRUCTION이다.
  • LINE: 빈 줄을 제외한 실제 코드의 라인 수, 라인이 한 번이라도 실행된다면 실행된 것으로 간주
  • BRANCH: 조건문 등의 분기 수
  • CLASS: 클래스 수, 내부 메서드가 한 번이라도 실행된다면 실행된 것으로 간주
  • METHOD: 메서드 수, 메서드가 한 번이라도 실행된다면 실행된 것으로 간주
  • COMPLEXITY: 복잡도
  • INSTRUCTION: 자바 바이트코드 명령 수
• value
  측정한 커버리지를 어떤 방식으로 보여줄 것인지를 말하며 limit 메서드를 통해 지정할 수 있다. 기본값은 COVEREDRATIO이다.
  • COVEREDCOUNT: 커버된 개수
  • COVEREDRATIO: 커버된 비율, 0-1 사이의 숫자로 1이 100%
  • MISSEDCOUNT: 커버되지 않은 개수
  • MISSEDRATIO: 커버되지 않은 비율, 0-1 사이의 숫자로 1이 100%
  • TOTALCOUNT: 전체 개수
• minimum
  counter 값을 value에 맞게 표현했을 때 최솟값을 말하며 limit 메서드를 통해 지정할 수 있다. 이 값을 통해 jacocoTestCoverageVerification의 성공 여부가 결정된다.
  해당 값은 BidDecimal 타입이고 표기한 자릿수만큼 value가 출력된다. 만약 커버리지 설정을 80%을 원했을 때, 0.80이 아닌 0.8 입력 시 커버리지가 0.87이어도 0.8로 표시된다.
• excludes
  커버리지를 측정할 때 제외할 클래스를 지정할 수 있다. 패키지 레벨의 경로로 지정하여야 하고 경로에는 *와 ?를 사용할 수 있다.

 

JaCoCo 플러그인 태스크 순서 설정

테스트 →  보고서 생성

 

JaCoCo 플러그인의 User Guide 문서를 보면 테스트는 보고서 생성(jacocoTestReport 태스크) 전에 실행되어야 하는데, jacocoTestReport 태스크는 테스트 태스크에 의존하지 않아 항상 jacocoTestReport를 생성하거나 보고서를 생성하기 전에 test 태스크를 명시적으로 실행해야 된다고 한다.

 

따라서 테스트가 끝나면 보고서를 생성하는 태스크가 자동으로 실행되도록 jacoco.gradle에 아래 내용을 추가해 준다.

test {
    useJUnitPlatform()
    finalizedBy 'jacocoTestReport'
}

 

finalizedBy 사용 시 이전 태스크(test)의 성공 여부와 관계없이 명시한 태스크(jacocoTestReport)를 이어 실행하도록 설정할 수 있다.

 

보고서 생성 → 커버리지 기준 만족 여부 확인

보고서를 생성하는 jacocoTestReport와 설정한 커버리지를 만족하는지 확인하는 jacocoTestCoverageVerification의 순서를 지정하지 않아 jacocoTestCoverageVerification 태스크가 jacocoTestReport 태스크보다 먼저 실행되어 설정한 커버리지를 통과하지 못하면 gradle 빌드가 멈추게 된다. 그렇게 되면 jacocoTestReport 태스크는 실행되지 않게 되고, 보고서가 생성되지 않아 이전 테스트에서 생성된 보고서를 보는 경우가 발생할 수 있다.

jacocoTestReport {
    reports { ... }
    afterEvaluate { ... }
    finalizedBy 'jacocoTestCoverageVerification'
}

 

따라서 finalizedBy 메서드를 사용하여 test → jacocoTestReport → jacocoTestCoverageVerification 순서로 태스크를 실행하면 모든 조건을 만족할 수 있다.

 

코드 커버리지 분석 대상 제외

테스트를 하지 않아도 되는 예외 클래스, DTO 클래스 등을 포함하여 코드 커버리지를 계산하면 코드 커버리지가 낮게 나오기 때문에 해당 특정 클래스들을 분석 대상에서 제외할 수 있다.

 

보고서에 포함될 특정 클래스 · 패키지 제외

jacocoTestReport 태스크에서 보고서에 표시되는 클래스 중 일부를 제외할 수 있다. 제외 대상 파일들은 Ant 스타일 패턴으로 작성한다.

jacocoTestReport {
    reports {
        // ...
    }
    afterEvaluate {
        classDirectories.setFrom(
                files(classDirectories.files.collect {
                    fileTree(dir: it, excludes: [
                            '**/common/**',
                            '**/config/**',
                            '**/*Application*',
                            '**/*DetailService*',
                    ])
                }))
    }
    finalizedBy 'jacocoTestCoverageVerification'
}

📌 jacocoTestReport에서는 경로를 '/'로 구분하고, 아래의 jacocoTestCoverageVerification은 경로를 '.'로 구분했을 때 올바르게 적용된다.

 

코드 커버리지 검증 대상에서 특정 클래스 · 패키지 제외

jacocoTestCoverageVerification 태스크에서는 코드 커버리지를 만족하는지 확인할 대상 중 일부 패키지를 제외할 수 있다. 제외 대상 파일들은 점(.)으로 구분된 자바 클래스와 패키지 이름을 사용한다.

jacocoTestCoverageVerification {
    violationRules {
        rule {
            // ...
            excludes = [
                    "**.common.*",
                    "**.config.*",
                    '**.infra.**',
                    '**.*Application*',
                    '**.*DetailService*',
            ]
        }
    }
}

 

보고서가 생성되는 위치를 따로 설정해주지 않은 경우 기본 경로인 build/reports/jacoco/test/html/index.html에 저장되며 생성된 html 보고서는 각 커버리지 항목마다 총 개수와 놓친 개수를 표시해 준다. 

 

Element를 타고 들어가면 어떤 메서드가 테스트되지 않았는지도 확인할 수 있다.

 

제외 클래스 자동화

프로젝트 루트 디렉토리 하위에 coverage-exclude.asap 파일을 생성하고 JaCoCo에서 제외할 파일이나 패키지를 입력한다.

exclude com/chaewsstore/core/infra/*
exclude com/chaewsstore/*/common/*
exclude com/chaewsstore/*/common/*/*
exclude com/chaewsstore/*/config/*
exclude com/chaewsstore/*/config/*/*
exclude com/chaewsstore/*/*Application*
exclude com/chaewsstore/*/apis/*/service/*DetailService*

 

jacoco.gradle에 coverage-exclude.asap 파일의 내용을 excludeFromCoverage 리스트에 저장하는 코드를 추가한다.

import java.util.stream.Collectors

def excludeFromCoverage = new ArrayList<String>()
file('coverage-exclude.asap').withInputStream() { it ->
    excludeFromCoverage.addAll(new BufferedReader(new InputStreamReader(it))
            .lines()
            .parallel()
            .map(s -> s.substring(7).strip())
            .collect(Collectors.toList()))
}

 

 jacocoTestReport와 jacocoTestCoverageVerification의 excludes 부분을 아래와 같이 수정한다.

jacocoTestReport {
    reports { ... }
    afterEvaluate {
        classDirectories.setFrom(
                files(classDirectories.files.collect {
                    fileTree(dir: it, excludes: excludeFromCoverage.stream()
                            .map(s -> s + ".class")
                            .collect(Collectors.toList()))
                })
        )
    }
    finalizedBy 'jacocoTestCoverageVerification'
}

jacocoTestCoverageVerification {
    violationRules {
        rule {
            ...
            excludes += excludeFromCoverage.stream()
                    .map(s -> s.replace("/", "."))
                    .collect(Collectors.toList())
        }
    }
}

 

JaCoCo 설정 전체 코드

import java.util.stream.Collectors

def excludeFromCoverage = new ArrayList<String>()
file('coverage-exclude.asap').withInputStream() { it ->
    excludeFromCoverage.addAll(new BufferedReader(new InputStreamReader(it))
            .lines()
            .parallel()
            .map(s -> s.substring(7).strip())
            .collect(Collectors.toList()))
}

subprojects {
    apply plugin: 'jacoco'

    jacoco {
        toolVersion = '0.8.12'
    }

    test {
        useJUnitPlatform()
        finalizedBy 'jacocoTestReport'
    }

    jacocoTestReport {
        reports {
            html.required.set(true)
            xml.required.set(false)
            csv.required.set(false)
        }
        afterEvaluate {
            classDirectories.setFrom(
                    files(classDirectories.files.collect {
                        fileTree(dir: it, excludes: Qdomains + excludeFromCoverage.stream()
                                .map(s -> s + ".class")
                                .collect(Collectors.toList()))
                    })
            )
        }
        finalizedBy 'jacocoTestCoverageVerification'
    }

    jacocoTestCoverageVerification {
        violationRules {
            rule {
                enabled = true
                element = "CLASS"
                limit {
                    counter = "LINE"
                    value = "COVEREDRATIO"
                    minimum = 0.80
                }
                excludes += excludeFromCoverage.stream()
                        .map(s -> s.replace("/", "."))
                        .collect(Collectors.toList())
            }
        }
    }
}

 

📑 JaCoCo Report Aggregation

멀티 모듈로 애플리케이션을 개발할 때, 루트 build.gradle의 allProjects 혹은 subProjects로 모든 모듈에 JaCoCo 플러그인을 적용할 경우 JaCoCo의 test code coverage reports가 모듈별로 생성된다. 이렇게 되면 특정 모듈의 커버리지 보고서를 보기 위해서는 해당 모듈의 build를 열어봐야 한다는 단점이 있다. 따라서 이렇게 분리된 jacoco coverage reports 파일을 합치기 위해서 jacoco-aggregation 플러그인을 사용할 수 있다.

 

Report Aggregation 플러그인 적용

루트 디렉토리 하위에 support/jacoco 모듈을 만들어 :support:jacoco 프로젝트에서 JaCoCo 리포트 집계를 설정한다.

project(':support:jacoco') {
    apply plugin: 'jacoco-report-aggregation'
}

├── chaewsstore-admin  
├── chaewsstore-app
├── chaewsstore-core
├── global-utils
├── support
│       └── jacoco
│
├── build.gradle
└── jacoco.gradle

 

코드 커버리지 리포트 설정

JaCoCo 설정 중 jacocoTestReport의 afterEvaluate를 통해 보고서에 표시되는 클래스 중 원하는 클래스를 제외할 수 있었는데, jacoco-aggregation으로 통합된 report에는 여전히 exclude 한 클래스들이 보이는 문제가 생긴다.

 

이는 jacoco.gradle 파일에서 아래 설정을 추가해 jacoco-aggregation에서도 클래스를 제거할 수 있다.

testCodeCoverageReport {
    getClassDirectories().setFrom(files(allProjects
            .collect {
                it.fileTree(dir: "${it.buildDir}/classes/java/main", exclude:
                        excludeFromCoverage.stream()
                                .map(s -> s + ".class")
                                .collect(Collectors.toList()))
            }
    ))
}

 

종속성 추가

support/jacoco 모듈에서 다른 하위 모듈들을 종속성으로 추가해 jacoco-report-aggregation이 이 하위 모듈들의 테스트 커버리지 리포트를 수집하고 집계할 수 있다.

dependencies {
    implementation project(':chaewsstore-admin')
    implementation project(':chaewsstore-app')
    implementation project(':chaewsstore-core')
}

 

종속성 추가 자동화

위에서처럼 종속성을 하드코딩할 경우 새로운 모듈이 생성될 때마다 jacoco-aggregation에 추가를 해주어야 하는 단점이 있다. 따라서 새로운 모듈 생성 시 자동으로 감지해 jacoco-aggregation 대상으로 등록해 주는 코드를 추가해 주었다.

def allProjects = getAllprojects().stream()
        .filter(p -> !p.getDisplayName().contains('root project'))
        .collect(Collectors.toList())

project(':support:jacoco') {
    apply plugin: 'jacoco-report-aggregation'

    testCodeCoverageReport { ... }

    def allProjectsExcludeJacoco = allProjects.stream()
            .filter(p -> !p.getDisplayName().contains('jacoco')
                    && !p.getDisplayName().contains('root project'))
            .collect(Collectors.toList())

    dependencies {
        allProjectsExcludeJacoco.each { project ->
            implementation project
        }
    }
}

 

JaCoCo Aggregation 설정 전체 코드

def allProjects = getAllprojects().stream()
        .filter(p -> !p.getDisplayName().contains('root project'))
        .collect(Collectors.toList())

project(':support:jacoco') {
    apply plugin: 'jacoco-report-aggregation'

    testCodeCoverageReport {
        getClassDirectories().setFrom(files(allProjects
                .collect {
                    it.fileTree(dir: "${it.buildDir}/classes/java/main", exclude:
                            excludeFromCoverage.stream()
                                    .map(s -> s + ".class")
                                    .collect(Collectors.toList()))
                }
        ))
    }

    def allProjectsExcludeJacoco = allProjects.stream()
            .filter(p -> !p.getDisplayName().contains('jacoco')
                    && !p.getDisplayName().contains('root project'))
            .collect(Collectors.toList())

    dependencies {
        allProjectsExcludeJacoco.each { project ->
            implementation project
        }
    }
}

 

🔏 추가적인 코드 커버리지 분석 대상 제외

QClass

JPQ와 QueryDSL을 사용하면 Q domain이 생기는데 해당 부분은 코드 커버리지 분석 대상에서 제외해야 한다.

jacoco.gradle에 아래 코드를 추가하고, excludes에 Qdomains를 추가해 준다.

def Qdomains = []
for(qPattern in "**/QA" .. "**/QZ"){
    Qdomains.add(qPattern+"*")
}

 

Generated 어노테이션 추가

lombok 관련 메서드

lombok으로 자동 생성되는 Getter, NoArgsConstructor, Builder 등의 메서드도 테스트 커버리지에 측정되어 빌드에 실패할 수 있다. 따라서 lombok 관련 메서드들을 측정에서 제외했다.

 

프로젝트 루트 디렉토리 하위에 lombok.config 파일을 생성하고 아래의 설정을 해주면 된다.

lombok.addLombokGeneratedAnnotation = true

이 설정은 모든 lombok으로 생성된 메서드에 대해 'Generated' 어노테이션을 붙인다는 설정이다.

 

이외 메서드

프로젝트에서 재정의한 equals와 hasoCode는 테스트할 필요가 없어 테스트 케이스에 추가하지 않았는데, 이도 마찬가지로 테스트 커버리지에 측정되어 빌드가 실패할 수 있게 된다. 테스트 커버리지를 위해 불필요하게 해당 메서드를 테스트하는 것보다 메서드를 측정에서 제외하는 것이 낫다고 생각했다.

 

JaCoCo 설정에서 exclude 가능한 항목은 element에서 정의된 CLASS이다. 하지만 JaCoCo 0.8.2부터는

1. 'Generated'라는 단어가 이름에 포함
2. RetentionPolicy가 'CLASS' 또는 'Runtime'

을 충족하는 어노테이션이 있으면 해당 타겟은 JaCoCo 측정에서 제외할 수 있다고 한다. 따라서 위 기준을 충족하는 어노테이션을 만들고, 테스트가 불필요한 메서드에 해당 어노테이션을 추가해 주었다.

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Generated {

}

@Override
@Generated
public final boolean equals(Object o) {
    ...
}

@Override
@Generated
public final int hashCode() {
    ...
}

이 방법은 필요한 테스트 케이스만 커버리지 측정을 함으로써 정확한 커버리지 분석을 할 수 있게 해 주지만 서비스 코드에 테스트 코드 로직이 들어간다는 단점이 있다.

 

🤔 Generated 어노테이션이 붙으면 왜 report에서 제외될까?

lombok 관련 메서드와 테스트가 불필요한 메서드에 @Generated 어노테이션을 붙여 측정에서 제외할 수 있는 이유는 lombok의 메서드 생성 시점과 JaCoCo의 코드 커버리지 측정 방식에 있다.

 

🫧 lombok 메서드 생성 시점

lombok 메서드는 컴파일 시 생성(annotation processing)된다. 즉, 소스 코드가 컴파일될 때 lombok이 자동으로 메서드를 추가하는데, 이때 이 메서드에 @Generated 어노테이션을 붙인다.

 

🫧 JaCoCo 코드 커버리지 측정 방식

JaCoCo는 Java Agent로 실행되어 바이트 코드를 직접 관리하고, 테스트 실행 중 어떤 코드 라인이 수행되었는지 확인하며 커버리지를 측정한다. JaCoCo는 실행되는 바이트 코드의 각 라인을 추적하여 커버리지 비율을 계산하는데, 이 과정에서 @Generated가 붙은 메서드를 인식하고 이를 측정 대상에서 제외할 수 있다.

 

 

 

📚 참고

The JaCoCo Plugin

Jacoco 보고서에서 제외

좌충우돌 Jacoco 적용기

코드 분석 도구 적용기 - 2편, JaCoCo 적용하기

코드 커버리지 툴 적용기(feat. JaCoCo)

[Jacoco] 멀티 모듈의 Jacoco report 를 하나로 합치기

JaCoCo 활용해보기