멀티 모듈 프로젝트 CI 시 전체 Test Coverage 도출하기 (Jacoco, GitLab)

1. 개요

GitLab에는 CICD 시 프로젝트의 Test Coverage를 추출하여 표시할 수 있는 기능을 제공해준다.

Build 시 Test Coverage 수치를 로그로 찍어두면, 정규식을 활용하여 추출해낼 수 있고, 아래 사진과 같이 Readme에 표현할 수 있다.

관련 공식 문서는 여기 를 참고하면 된다.

이렇게 추출해둔 커버리지는 회사에서 각 프로젝트들의 테스트 커버리지 현황을 관리할 때 사용하고 있다. 테스트 커버리지가 높다고 장애가 없는, 리팩토링에 안전한 프로젝트라고 장담할 수 없지만 전혀 의미 없는 수치는 아니라고 생각한다.

아무튼 우리 팀은 Spring Boot Multi Module 형식으로 프로젝트를 진행하고 있었기 때문에 전체 모듈에 대한 커버리지를 하나로 표현할 방법을 모색해야 했다.

여러 방법들을 시도해보며 있었던 과정을 기록하려한다.

내가 시도해본 방법은 크게 3가지이다.

1. shell script를 통한 전체 커버리지 계산

2. Summary를 담당하는 모듈을 만들어 'jacoco-report-aggregation' 플러그인 이용

3. .gradle에 report를 merge하는 task 생성

시작하기 앞서 구글링 했을 때 나왔던 방식은 전부 2번 방식이였고,

별도의 모듈을 생성하기 싫어 시도했던 방식이 1번,

그리고 1, 2번 방법으로 구현 후 더 나은 방법이 없나 지피티랑 토론하다 구현한게 3번 방식이다.

최종적으론 3번 방식을 사용할 것 같다.

2.1 shell script를 통한 전체 커버리지 계산

그냥 가장 무식한 방법이다. 처음엔 jacoco-report-aggregation 플러그인 사용하는 방법으로 시도하다 삽질을 좀 하기도 했고, 별도의 모듈을 생성하는 것 조차 마음에 들지 않았기 때문에 시도했던 방법이다.

그냥 각 서브 모듈에 생성된 report를 gitlab ci 실행 시 find로 찾아 merge하여 하나의 파일로 만드는 방법이다.

어떻게든 커버리지를 띄우겠다는 마음으로 무식하게 머리박은 방식이라 추천하진 않는다. 2.2, 2.3 방식으로 바로 넘어가도 좋다.

build 후 사용했던 스크립트 파일은 아래와 같다.

#!/bin/bash

# JaCoCo 헤더 정의
JACOCO_HEADER="GROUP,PACKAGE,CLASS,INSTRUCTION_MISSED,INSTRUCTION_COVERED,BRANCH_MISSED,BRANCH_COVERED,LINE_MISSED,LINE_COVERED,COMPLEXITY_MISSED,COMPLEXITY_COVERED,METHOD_MISSED,METHOD_COVERED"

echo "모든 테스트 커버리지 리포트를 MERGE 시작 ..."
echo "$JACOCO_HEADER" > merged_jacoco.csv

# 프로젝트 전체에서 jacocoTestReport.csv 찾기
find "$CI_PROJECT_DIR" -type f -name "jacocoTestReport.csv" | while read file; do
  echo "📂 MERGE 중: $file"
  tail -n +2 "$file" >> merged_jacoco.csv
done

# 커버리지 계산
echo "MERGE 된 파일의 테스트 커버리지 계산 중 ..."
COVERAGE=$(awk -F"," 'NR>1 { instructions += $4 + $5; covered += $5 }
END { if (instructions > 0) print 100*covered/instructions; else print 0; }' merged_jacoco.csv)

# 전체 Coverage 출력
echo "Total Coverage: $COVERAGE%"

2.2 'jacoco-report-aggregation' 플러그인 이용

분리된 jacoco coverage reports파일을 합치기 위해서, jacoco-aggregation 플러그인을 사용할 수 있다.

공식 문서는 여기를 참고하면 된다.

Jacoco Test Coverage Report파일을 합치기 위해 별도의 Module을 생성해주자.

나는 jacoco 라는 모듈을 생성해주었고, build.gradle 파일에 아래와 같이 설정해주었다.

plugins {
    id 'base'
    id 'jacoco-report-aggregation'
}

repositories {
    mavenCentral()
}

dependencies {
    jacocoAggregation project(":server1")
    jacocoAggregation project(":server2")
}

bootJar.enabled = false
jar.enabled = true

// command: ./gradlew testCodeCoverageReport

그리고 build를 하거나, ./gralde testCodeCoverageReport를 실행하면 jacoco/build 안으로 합쳐진 report 파일이 떨어진다.

2.3 실행 데이터 파일(test.exec) 및 클래스 정보들을 가져와 report 생성하는 task 생성 (최종)

- build.gradle

plugins {
	id 'java'
	id 'org.springframework.boot' version '3.4.3'
	id 'io.spring.dependency-management' version '1.1.7'
	id 'java-library'
	id 'jacoco'
}

bootJar.enabled = false;

repositories {
	mavenCentral()
}

subprojects {
	group = 'com.example'
	version = '0.0.1-SNAPSHOT'

	apply {
		plugin 'java'
		plugin 'org.springframework.boot'
		plugin 'io.spring.dependency-management'
		plugin 'java-library'
		plugin 'jacoco'
	}

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

	repositories {
		mavenCentral()
	}

	dependencies {
		implementation 'org.springframework.boot:spring-boot-starter'
		testImplementation 'org.springframework.boot:spring-boot-starter-test'
		testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
	}

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

apply from: "${rootDir}/jacoco.gradle"

tasks.named('build') {
	finalizedBy tasks.named('testCodeCoverageReport')
}

- jacoco.gralde

subprojects {
    apply plugin: 'jacoco'

    tasks.named('jacocoTestReport') {
        dependsOn test

        reports {
            xml.required = false
            csv.required = true
            html.required = true
        }

        executionData.from = fileTree(dir: "$buildDir/jacoco", includes: ["*.exec"])
    }
}

task testCodeCoverageReport(type: JacocoReport) {
    dependsOn subprojects.test  // 모든 하위 모듈의 test 실행 후 실행

    // 하위 모듈의 test.exec 를 가져옴
    executionData.from = files(subprojects.jacocoTestReport.executionData)

    // 하위 모듈의 클래스 파일 가져옴
    additionalClassDirs.setFrom(files(subprojects.sourceSets.main.output))

    // 하위 모듈의 소스 코드 경로를 가져옴
    sourceDirectories.setFrom(files(subprojects.sourceSets.main.allSource.srcDirs))

    reports {
        xml.required = false
        csv.required = true
        html.required = true
    }
}

위와 같이 설정하고 build하면 아래와 같이 최상위 모듈의 build 아래에 coverage report가 떨어진다.

html report를 열어보면 하위 모듈들의 커버리지가 전부 합쳐져 보여진다.

이제 파일을 파싱 후 build log를 찍어주고, gitlab-ci.yml 파일에서 정규식을 통해 커버리지 로그를 파싱해주면 된다.

파싱하는 스크립트 파일은 다음과 같이 작성해주었다.

- parse_jacoco_report.sh

#!/bin/bash

# JaCoCo HTML 리포트 파일 경로
REPORT_FILE="$CI_PROJECT_DIR/build/reports/jacoco/testCodeCoverageReport/html/index.html"

# 파일 존재 여부 확인
if [[ ! -f "$REPORT_FILE" ]]; then
    echo "JaCoCo 리포트 파일이 존재하지 않습니다: $REPORT_FILE"
    exit 1
fi

# JaCoCo 커버리지 파싱
COVERAGE=$(grep -oP '(?<=Total).*?\d+%' "$REPORT_FILE" | grep -oP '\d+%')

# 추출된 커버리지가 없는 경우
if [[ -z "$COVERAGE" ]]; then
    echo "커버리지 값을 찾을 수 없습니다."
    exit 1
fi

# 결과 출력
echo "Total Coverage: $COVERAGE"

- .gitlab-ci.yml

stages:
  - Build-Test

build_test:
  stage: Build-Test
  script:
    - chmod +x .buildfile/gitlab-ci-script/*.sh  # 실행 권한 부여
    - .buildfile/gitlab-ci-script/build_project.sh  # 프로젝트 빌드 및 Docker 이미지 생성
    - .buildfile/gitlab-ci-script/parse_jacoco_report.sh  # JaCoCo 커버리지 추출
  coverage: '/Total.*?([0-9]{1,3})%/'
  only:
    - develop

gitlab 에서 Jobs를 확인해보면 이런식으로 커버리지를 표현할 수 있다.

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

dto나 mapper같은 코드들도 검증하면 나쁠 건 없지만 도메인 로직에 비해선 상대적으로 덜 중요하다. 이런 클래스들을 검증 대상에서 제외시키는 방법은 아래와 같다.

- 방법 1.

classDirectories.setFrom(
        files(sourceSets.main.output)
                .filter { it.exists() }
                .asFileTree.matching {
            exclude "**/dto/**"      // DTO 패키지 제외
            exclude "**/Q*.class"    // QueryDSL Q-Class 제외
        }
)

- 방법 2.

jacocoTestReport {
    reports {
        html.required  = true
        xml.required  = false
        csv.required  = false
    }
    excludedClassFilesForReport(classDirectories)
    dependsOn test
    finalizedBy 'jacocoTestCoverageVerification'
}

private excludedClassFilesForReport(classDirectories) {
    classDirectories.setFrom(
            files(classDirectories.files.collect {
                fileTree(dir: it, exclude: [
                        "com/konggogi/veganlife/global/**/*",
                        "com/konggogi/veganlife/**/dto/**",
                        "**/OauthService.class",
                        "**/*domain*/**",
                        "**/*Dto*",
                        "**/*Request*",
                        "**/*Response*",
                        "**/*Interceptor*",
                        "**/*Application*",
                        "**/*Mapper*",
                        "**/*Exception*"
                ])
            })
    )
}

방법은 되게 많으니 각자 편한대로 설정하면 될 것 같다. 참고로 나는 1번 방식으로 구현해뒀다.

+ 4. report 병합 시 커버리지 측정 대상 제외한 클래스도 포함되는 문제 해결

구글링 해보니 여러 사람들이 겪었던 문제였다.

2.2 플러그인 방식에서도 커버리지 측정 대상에서 제외한 클래스가 병합 시 포함되는 문제가 발생하는듯 했다. (참고)

나는 testCodeCoverageReport task 실행 시 클래스 파일과 소스 코드를 가져오는 코드가 있는데 여기서 filter를 걸어 해결할 수 있었다.

task testCodeCoverageReport(type: JacocoReport) {

    // service 하위 모듈들에 대해서만
    def microserviceModules = subprojects.findAll { it.path.startsWith(":service:") }

    // 테스트 끝난 후 실행
    dependsOn microserviceModules.test

    // test.exec 가져오기
    executionData.from = files(microserviceModules.jacocoTestReport.executionData)

    // 클래스 파일 가져오기
    additionalClassDirs.setFrom(
            files(microserviceModules*.sourceSets.main.output)
                    .filter { it.exists() }
                    .asFileTree.matching(excludePatternRules())
    )

    // 소스 코드 가져오기
    sourceDirectories.setFrom(
            files(microserviceModules*.sourceSets.main.allSource.srcDirs)
                    .filter { it.exists() }
                    .asFileTree.matching(excludePatternRules())
    )

    reports {
        xml.required = false
        csv.required = true
        html.required = true
    }
}

def excludePatternRules() {
    return {
        exclude "**/dto/**"      // DTO 패키지 제외
        exclude "**/Q*.class"    // QueryDSL Q-Class 제외
    }
}

'devOps 💡' 카테고리의 다른 글

Pinpoint로 APM 구축하기 With SpringBoot (0)	2025.01.09
[Zipkin] 분산 추적을 위한 Zipkin, Kafka 통신 시 TraceId 안 찍히는 문제 해결 (1)	2024.12.20
Blue/Green 무중단 배포 시 구버전의 애플리케이션은 언제 종료해야 할까? (graceful shutdown) (2)	2024.07.28
AWS RDS에 안전하게 접근해보자 (EC2 터널링) (1)	2024.06.08
성능 테스트, 부하 테스트, 스트레스 테스트 차이 (0)	2024.05.15