[코드분석도구]#2 Jacoco 적용하기

썸네일은 딱히 넣을게 없어서 젠킨스를 넣었다. 그냥 CI 도구라는 관점에서..?

참조한 레퍼런스

JaCoCo is a free code coverage library for Java, which has been created by the EclEmma team based on the lessons learned from using and integration existing libraries for many years
- JaCoCo

Jacoco는 Java Code의 코드 커버리지를 체크하는데 사용되는 오픈소스 라이브러리이다.

 

 

# Jacoco의 특징

코드 커버리지에 익숙하지 않을 때는 커버리지 기준을 낮춰서 사용하다가 점점 기준을 높이는 것을 추천한다. Jacoco는 코드 커버리지를 평가하고 프로젝트 빌드 성공/실패를 결정할 수 있게 만들어준다.

• 라인 커버리지(모든 코드가 실행되는가)와 브렌치 커버리지(모든 조건분기를 사용하는가)를 제공.
• 테스트코드를 돌리고 커버리지 기준을 만족하는지 확인할 수 있다.
• 코드 커버리지 결과를 정리된 파일(html, xml, csv등)으로 저장할 수 있다.

Jacoco를 통해 코드커버리지 결과를 csv, xml로 저장하면 이를 소나큐브(SonarQube) 같은 도구에 전달해 결과에 따라 커밋성공/실패를 결정하는 식으로 사용된다. 참고로 html을 사용하면 어느 부분이 문제인지 개발자가 한눈에 파악하기 쉽게 보고서로 만들어준다.

 

---

# Jacoco 적용하기

Java + SpringBoot + Gradle로 이루어진 프로젝트에 적용해보자. 스프링부트를 사용하면 build.gradle 설정만을 이용해서 쉽게 적용가능하다.

 

1. Jacoco를 전체 프로젝트를 하나로 일괄적용하고 싶다면 아래와 같이하면 된다.

//build.gradle

plugins {
  id 'java'
  id 'org.springframework.boot' version '2.3.1.RELEASE'
  ...
  id 'jacoco' // 추가!
}

jacoco {
  // JaCoCo 버전
  toolVersion = '0.8.6'
  
  // 테스트결과 리포트를 저장할 경로 
  // 변경하고자 하면 아래와 같이 작성 default는 "${project.reporting.baseDir}/jacoco"
  reportsDir = file("$buildDir/customJacocoReportDir")
}

 

2. 그게 아니라 각 모듈별로 따로 Jacoco를 적용하고 싶다면, 아래와 같이 설정해주자.

// build.gradle

plugins {
    id 'java'
    id 'org.springframework.boot' version '2.3.1.RELEASE'
    ...
}
allprojects {...}
subprojects {
    apply plugin: 'java'
    apply plugin: 'org.springframework.boot'
    apply plugin: 'io.spring.dependency-management'
    apply plugin: 'org.asciidoctor.convert'
    apply plugin: 'jacoco'// 여기에 추가!

    ...
}

jacoco {...}

 

그러면 아래와 같이 각 모듈의 Gradle 디렉토리에 Jacoco 의존성이 추가된다.

• jacocoTestReport : 코드 커버리지를 진행하고 그 결과를 사람이 읽기 좋은 리포트로 저장해주는 도구
• jacocoTestCoverageVerification : 원하는 커버리지 기준을 만족하는지 확인해주는 검증 도구

각 모듈별로 jacoco 코드 커버리지 추가

이 설정은 build.gradle에서 할 수 있는데, 한가지 주의할점은 jacoco는 테스트 이후 적용되는 플러그인이라는 점이다. 즉 [ Junit Test -> jacocoTestReport -> jacoco...CoverageVerification ] 순으로 실행되어야 하기 때문에 아래와 같이 테스트 설정을 고정시켜주자. 이를 생략하고 안해주면 이전 테스트결과를 반복해서 읽어 커버리지를 계속 통과 못하는 경우가 발생할 수 있다.

//build.gradle

    test {
        useJUnitPlatform() // JUnit5를 사용하기 위한 설정
        finalizedBy 'jacocoTestReport' // Test 이후 커버리지가 동작하도록 finalizedBy 추가
    }

    jacoco {
        toolVersion = '0.8.6'
    }

    jacocoTestReport {
        reports {
            html.enabled true
            csv.enabled true
            xml.enabled false
        }
        finalizedBy 'jacocoTestCoverageVerification' // 커버리지 작동 이후 검증하도록 설정
    }

 

---

# jacocoTestReport (커버리지 측정)

build.gradle에서 jacocoTestReport {...}에 설정 가능하다. 코드 커버리지 결과를 어떻게 저장할지 설정한다.

//build.gradle
...
jacoco {
    toolVersion = '0.8.6'
}
    
jacocoTestReport {
    reports {
        csv.enabled true // csv 설정
        xml.enabled false // xml 미설정
        html.enabled true // html 설정
        // 파일 형식에 따라 저장경로를 따로 지정해줄수도 있다.
        html.destination file('build/reports/myReport.html')
        ...
    }
}

 

리포트를 작성할 때 특정 파일을 제외하고 싶다면, 아래와 같이 작성하면 된다.

jacocoTestReport {
    reports {
        html.enabled true
        csv.enabled true
        xml.enabled false
    }

    def Qdomains = []

    for (qPattern in '**/QA'..'**/QZ') { // qPattern = '**/QA', '**/QB', ... '*.QZ'
        Qdomains.add(qPattern + '*') // ~/QA* , QA로 시작하는 모든 클래스
    }

    // 여기부터
    afterEvaluate {
        classDirectories.setFrom(
                files(classDirectories.files.collect {
                    fileTree(dir: it, excludes: [] + Qdomains)
                })
        )
    }

    finalizedBy 'jacocoTestCoverageVerification' 
}

• afterEvaluate는 gradle의 빌드 라이프 사이클에 대한 메서드. 프로젝트가 평가된 후 실행할 수 있도록 도와준다.
• classDirectories는 커버리지가 리포트로 작성할 소스 파일을 말한다. (여기서는 setFrom 메서드를 통해 이를 설정)
• files는 지정된 파일을 포함하는 ConfigurableFileCollection 타입을 반환.

이런식으로 메서드를 통해 리포트에 제외할 excludes 목록을 추가로 지정해줄 수 있다.

---

# jacocoTestCoverageVerification ( 점수평가, 검증 )

최소 코드 커버리지를 설정할 수 있고, 통과하지 못할경우 해당 Task가 실패하게 된다.

jacoco...verification { violationRules{~} } 를 통해 커버리지 기준 규칙을 정할 수 있다.

• rule { ... } 규칙을 적는 공간. 여러개를 작성할 수 있고 enable 옵션으로 on/off 할 수 있다.
• element = 적용할 타입 또는 대상을 지정한다 (전체, 클래스, 메서드, 한 파일 등등..)
  
  • BUNDLE(기본값) : 패키지 번들(프로젝트 모든 파일을 합친 것)
  • CLASS : 클래스
  • GROUP : 논리적 번들 그룹
  • METHOD : 메서드
  • PACKAGE : 패키지
  • SOURCEFILE : 소스 파일
• includes, exclude = 작성하면 제외 대상/적용 대상을 클래스나 패키지 경로로 한정할 수 있다.
  - 정규표현식인 * 와 ? 를 사용할 수 있다. import 하듯이 리스트를 적으면 된다.

jacocoTestCoverageVerification {
    violationRules {
        rule { // 1번 규칙
            enable = true // 규칙 활성화여부
            element = 'CLASS' // 적용 대상을 지정한다. 기본값은 BUNDLE (전체 패키지)
            // BUNDLE, CLASS, GROUP(논리적 번들그룹), METHOD, PACKAGE, SOURCEFILE 등
            
            // 해당 규칙의 적용대상을 클래스, 패키지 단위로 지정가능
            // includes = [], 단 include는 생략하면 전체 패키지에 일괄 적용 
			// excludes = [], 제외할 패키지/클래스를 지정
            
            limit {
                counter = 'BRANCH' // 커버리지 종류
                value = 'COVEREDRATIO' // 값 (전체 비율)
                minimum = 0.90 // 최소 기준 90%
            }

            limit {
                counter = 'LINE' 
                value = 'COVEREDRATIO'
                minimum = 0.80 // 최소 기준 80%
            }

            limit {
                counter = 'LINE'
                value = 'TOTALCOUNT' // 값(전체 개수)
                maximum = 200 // 최소 기준 200줄 이하
            }
        }
        
        // 여러 rule을 생성할 수 있습니다.
        rule { // 2번 규칙
            ... 
        }
    }
}

 

• limit = 커버리지 측정 최소단위를 지정한다.

limit {
  counter = 'BRANCH' // 커버리지 종류
  value = 'COVEREDRATIO' // 값 (전체 비율)
  minimum = 0.90 // 최소 기준 90%
}

 

Counter

• BRANCH : 조건문 등의 분기 수
• CLASS : 클래스 수, 내부 메서드가 한 번이라도 실행된다면 실행된 것으로 간주한다.
• COMPLEXITY : 코드 복잡도(링크 참조)
• INSTRUCTION(기본값) : Java 바이트코드 명령 수
• METHOD : 메서드 수, 메서드가 한 번이라도 실행된다면 실행된 것으로 간주한다.
• LINE : 빈 줄을 제외한 실제 코드의 라인 수, 라인이 한 번이라도 실행되면 실행된 것으로 간주한다.

Value

• COVEREDCOUNT : 커버된 개수
• COVEREDRATIO(기본값) : 커버된 비율, 0부터 1사이의 숫자로 [1 = 100%]이다.
• MISSEDCOUNT : 커버되지 않은 개수
• MISSEDRATIO : 커버되지 않은 비율, 0부터 1사이의 숫자로 [1 = 100%]이다.
• TOTALCOUNT : 전체 개수

Minimum

• 위의 Value로 지정한 타입의 최소기준값을 입력하면 된다. jacocoTest의 성공여부가 결정되는 기준값이며 표기한 자릿 수만큼 value가 세밀하게 측정된다. 즉 0.80을 입력하면 소숫점 둘째자리까지, 0.8을 입력하면 첫째 자리까지만 측정하며 그 이하의 값들은 버려진다. (반올림 아님)

 

---

# Test 설정하기

모든 테스트 타입에 JacocoTaskExtension을 추가하고, test {...}에서 설정을 변경할 수 있다.

이렇게 설정한 Jacoco 커버리지는 기준을 만족하지못하면 프로젝트가 gradle에 빌드되지 않는다.

//build.gradle

test { // 각 설정값은 오버라이드가 가능하다.
    jacoco {
        enabled = true
        destinationFile = file("$buildDir/jacoco/${name}.exec")
        includes = []
        excludes = []
        excludeClassLoaders = []
        includeNoLocationClasses = false
        sessionId = "<auto-generated value>"
        dumpOnExit = true
        classDumpDir = null
        output = JacocoTaskExtension.Output.FILE
        address = "localhost"
        port = 6300
        jmx = false
    }
}

/gradlew --console verbose test 를 이용하면 아래와 같이 어떤 클래스가 문제인지 콘솔에 표시해준다.

build/reports/jacoco/test/html/index.html 에 저장된 커버리지 점수표

각 클래스를 눌러보면 친절하게 어떤 부분이 문제인지도 알려준다.

만약 코드 커버리지에 제외하고 싶은 이름규칙이 있다면, 그루비 문법을 사용해서 exclude= [...]에 적용시켜주자.

  jacocoTestCoverageVerification {
        def Qdomains = []
		
        // 직접하나하나 지정해줘도 되고, 이런식으로 패턴을 이용해도 된다.
        for (qPattern in '*.QA'..'*.QZ') { // qPattern = '*.QA', '*.QB', ... '*.QZ'
            Qdomains.add(qPattern + '*')
        }

        violationRules {
            rule {
               ...
                excludes = [] + Qdomains // 제외할 Qdomains 패턴 추가
            }
        }
    }
}

 

---

# lombok으로 생성된 코드 제외하기

그냥 lombok 설정하나 추가해주면 된다. 간단

//build.gradle
lombok.config{
	lombok.addLombokGeneratedAnnotation = true
}

 

---

# 전체 설정 한눈에 보기

참고로 모듈을 여러개 사용할 때, Jacoco가 실행도중 커버리지 기준미달인 모듈을 발견하면 바로 실행을 멈춘다. 그래서 report가 생성되지 않는 경우도 있는데 만약 실패여부와 상관없이 개별적으로 전부 돌려보고 싶다면 /gradlew test에 --continue를 추가하면 된다.

/*...*/
subprojects {
    apply plugin: 'java'
    apply plugin: 'org.springframework.boot'
    apply plugin: 'io.spring.dependency-management'
    apply plugin: 'org.asciidoctor.convert'
    apply plugin: 'jacoco' // 멀티 모듈 적용

    sourceCompatibility = '1.8'

    repositories {
        mavenCentral()
    }

    test {
        useJUnitPlatform()
        finalizedBy 'jacocoTestReport' // test 이후 커버리지 실행
    }

    jacoco {
        toolVersion = '0.8.6'
    }

    jacocoTestReport {
        reports {
            html.enabled true
            csv.enabled true
            xml.enabled false
        }

        def Qdomains = []

        for (qPattern in '**/QA'..'**/QZ') { // qPattern = '*.QA', '*.QB', ... '*.QZ'
            Qdomains.add(qPattern + '*')
        }

        afterEvaluate { // report 제외대상 지정
            classDirectories.setFrom(
                    files(classDirectories.files.collect {
                        fileTree(dir: it, excludes: [] + Qdomains)
                    })
            )
        }

        finalizedBy 'jacocoTestCoverageVerification' // 커버리지 이후 평가
    }

    jacocoTestCoverageVerification { // 커버리지 기준값 상세설정
        def Qdomains = []

        for (qPattern in '*.QA'..'*.QZ') { // qPattern = '*.QA', '*.QB', ... '*.QZ'
            Qdomains.add(qPattern + '*')
        }

        violationRules {
            rule {
                enabled = true
                element = 'CLASS'

                limit {
                    counter = 'LINE'
                    value = 'COVEREDRATIO'
                    minimum = 0.00
                }

                limit {
                    counter = 'BRANCH'
                    value = 'COVEREDRATIO'
                    minimum = 0.00
                }

                excludes = [] + Qdomains // 커버리지 평가 제외 대상
            }
        }
    }
}
/*...*/

 

다음 글에서는 Jacoco의 코드커버리지 결과를 이용해서 정적 분석 CI 도구인 SonarQube와 연동해보도록 하겠다. 정적분석도구와 Jacoco의 다른점은, Jacoco는 단순히 코드 커버리지 결과를 이용해서 빌드 성공/실패여부를 측정하는게 끝이라면 SonarQube는 코드 품질검사를 통해 버그, 유닛테스트, 주석, 복잡도, 표준 컨벤션(코드 Smell 측정)등을 분석해 취약점과 보고서를 제공한다.