테스트 커버리지 시각화
- GitLab 12.9에서 도입되었습니다.
- GitLab 13.5에서 기능 플래그가 제거되었습니다.
GitLab CI/CD를 사용하여 즐겨 사용하는 테스트 또는 커버리지 분석 도구의 테스트 커버리지 정보를 수집하고, 병합 요청(MR)의 파일 차이 보기 내에서 이 정보를 시각화할 수 있습니다. 이를 통해 MR이 병합되기 전에 어떤 라인이 테스트에 의해 처리되었는지, 어떤 라인이 아직 커버리지가 필요한지를 확인할 수 있습니다.
테스트 커버리지 시각화 작업 방식
커버리지 정보 수집은 GitLab CI/CD의 artifacts reports feature를 사용하여 수행됩니다. 와일드카드 경로를 포함하여 하나 이상의 커버리지 보고서를 수집하도록 지정할 수 있습니다. 그런 다음 GitLab은 모든 파일의 커버리지 정보를 모아서 결합합니다. 커버리지 파일은 백그라운드 작업에서 구문 분석되므로 파이프라인 완료와 페이지에 로드된 시각화 간에 지연이 발생할 수 있습니다.
커버리지 분석이 작동하려면 올바르게 서식이 지정된 Cobertura XML 보고서를 artifacts:reports:coverage_report
에 제공해야 합니다. 이 형식은 원래 Java용으로 개발되었지만, 대부분의 다른 언어에 대한 커버리지 분석 프레임워크는 이를 지원하기 위한 플러그인을 추가하는 기능을 제공합니다. 예를 들어 다음과 같은 플러그인이 있습니다.
- simplecov-cobertura (루비)
- gocover-cobertura (Go)
기타 커버리지 분석 프레임워크에서는 이 형식을 기본적으로 지원하며, 예를 들어 다음과 같습니다.
- Istanbul (자바스크립트)
- Coverage.py (파이썬)
- PHPUnit (PHP)
구성한 후에 병합 요청이 파이프라인을 트리거하고 커버리지 보고서를 수집하면 커버리지 정보가 파일 차이 보기에 표시됩니다. 이는 파이프라인의 어떤 스테이지의 어떤 작업에서든 보고서가 표시됨을 의미합니다. 각 라인의 커버리지는 다음과 같이 표시됩니다.
-
covered
(녹색): 테스트에서 최소 한 번 이상 확인된 라인 -
no test coverage
(주황색): 로드되었지만 실행되지 않은 라인 - 커버리지 정보 없음: 비계기록된 또는 로드되지 않은 라인
커버리지 막대를 가리키면 라인이 테스트에서 확인된 횟수와 같은 추가 정보가 제공됩니다.
테스트 커버리지 보고서를 업로드하더라도 다음 기능이 활성화되지 않습니다.
이러한 기능을 별도로 구성해야 합니다.
제한사항
Cobertura 형식 XML 파일의 경우 최대 100개의 <source>
노드 제한이 적용됩니다. Cobertura 보고서가 100개의 노드를 초과하는 경우, 병합 요청의 차이 보기에서 불일치 또는 일치하지 않을 수 있습니다.
단일 Cobertura XML 파일의 크기 제한은 10 MiB입니다. 큰 프로젝트의 경우 Cobertura XML을 더 작은 파일로 분할하십시오. 자세한 내용은 이 이슈를 참조하십시오. 많은 파일을 제출하는 경우, 병합 요청에 커버리지가 표시되기까지 몇 분이 걸릴 수 있습니다.
시각화는 파이프라인이 완료된 후에만 표시됩니다. 파이프라인에 차단 매뉴얼 작업이 있는 경우, 파이프라인은 계속 진행되기 전에 차단 매뉴얼 작업을 기다리고 완료로 간주되지 않습니다. 만약 차단 매뉴얼 작업이 실행되지 않았다면 시각화를 표시할 수 없습니다.
데이터 유효 기간
- GitLab 13.12에서 도입되어, 최신 데이터는 만료 시간과 상관없이 유지됩니다.
기본적으로 병합 요청의 시각화에 사용된 데이터는 생성 후 1주일 후에 만료됩니다.
자식 파이프라인에서의 커버리지 보고서
- GitLab 15.1에서
ci_child_pipeline_coverage_reports
이라는 플래그로 도입되었습니다. 기본적으로 비활성화됨.- GitLab 15.2에서
ci_child_pipeline_coverage_reports
기능 플래그가 제거되었으며 GitLab.com 및 self-managed에서 활성화됨.
부모 파이프라인에 작업이 자식 파이프라인에서 커버리지 보고서를 생성하면 해당 보고서가 부모 파이프라인의 커버리지 보고서에 포함됩니다.
child_test_pipeline:
trigger:
include:
- local: path/to/child_pipeline_with_coverage.yml
자동 클래스 경로 보정
커버리지 보고서는 class
요소의 filename
이 프로젝트 루트에 대한 전체 경로를 포함하는 경우에만 변경된 파일과 정확하게 일치합니다. 그러나 일부 커버리지 분석 프레임워크에서 생성된 Cobertura XML에는 filename
경로가 클래스 패키지 디렉터리를 기준으로 상대적인 경우가 있습니다.
Cobertura XML 파서는 프로젝트 루트에 대한 class
경로에 대한 지능적인 추측을 수행하기 위해 다음을 시도합니다:
-
sources
요소에서source
경로의 일부를 추출하고 클래스filename
경로와 결합합니다. - 후보 경로가 프로젝트에 있는지 확인합니다.
- 일치하는 후보가 있는 경우 클래스 전체 경로로 사용합니다.
경로 보정 예시
예를 들어, 다음과 같은 C# 프로젝트가 있다고 가정해 봅시다:
-
test-org/test-cs-project
의 전체 경로. -
프로젝트 루트를 기준으로 다음과 같은 파일들이 있습니다:
shell Auth/User.cs Lib/Utils/User.cs
- Cobertura XML의
sources
는 다음 형식의 경로를 가집니다:<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...
. ```xml/builds/test-org/test-cs-project/Auth</source> /builds/test-org/test-cs-project/Lib/Utils</source> ```
파서는:
-
sources
에서Auth
와Lib/Utils
를 추출하여 프로젝트 루트에 대한class
경로를 결정합니다. - 이러한 추출된
sources
및 클래스 파일 이름을 결합합니다. 예를 들어,filename
값이User.cs
인class
요소가 있는 경우, 파서는 첫 번째 일치하는 후보 경로를 채택합니다. 즉Auth/User.cs
입니다. - 각
class
요소에 대해 파일 트리에서 일치하는 경로를 찾기 위해 추출된source
경로마다 최대 100번 시도합니다. 이 제한에 도달하여 파일 트리에서 일치하는 경로를 찾지 못하면 해당 클래스는 최종 커버리지 보고서에 포함되지 않습니다.
Java 프로젝트에서도 자동 클래스 경로 보정이 작동합니다. 예를 들어:
-
test-org/test-java-project
의 전체 경로. -
프로젝트 루트를 기준으로 다음과 같은 파일이 있습니다:
shell src/main/java/com/gitlab/security_products/tests/App.java
- Cobertura XML의
sources
: ```xml/builds/test-org/test-java-project/src/main/java/</source> ```
-
filename
값이com/gitlab/security_products/tests/App.java
인class
요소: ```xml```
참고:
자동 클래스 경로 보정은 <CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...
형식의 source
경로에서만 작동합니다. 이 패턴을 따르지 않는 경로는 무시됩니다. 또한 파서는 class
요소의 filename
이 프로젝트 루트에 대한 전체 경로를 포함한다고 가정합니다.
예시 테스트 커버리지 구성
이 섹션에서는 각 프로그래밍 언어에 대한 테스트 커버리지 구성 예시를 제공합니다. 또한 coverage-report
데모 프로젝트에서 작동하는 예시를 확인할 수 있습니다.
JavaScript 예시
다음 .gitlab-ci.yml
예시는 Mocha JavaScript 테스팅 및 nyc 커버리지 도구를 사용하여 커버리지 아티팩트를 생성합니다.
yaml
test:
script:
- npm install
- npx nyc --reporter cobertura mocha
artifacts:
reports:
coverage_report:
coverage_format: cobertura
path: coverage/cobertura-coverage.xml
Java 및 Kotlin 예시
Maven 예시
다음 Java 또는 Kotlin을 위한 .gitlab-ci.yml
예시는 Maven을 사용하여 프로젝트를 빌드하고 JaCoCo 커버리지 도구를 사용하여 커버리지 아티팩트를 생성합니다. 자체 이미지를 빌드하려면 Docker 이미지 구성 및 스크립트를 확인할 수 있습니다.
GitLab은 Cobertura 형식의 아티팩트를 예상하므로 업로드하기 전에 몇 가지 스크립트를 실행해야 합니다. test-jdk11
작업은 코드를 테스트하고 XML 아티팩트를 생성합니다. coverage-jdk-11
작업은 아티팩트를 Cobertura 보고서로 변환합니다.
```yaml
test-jdk11:
stage: test
image: maven:3.6.3-jdk-11
script:
- mvn $MAVEN_CLI_OPTS clean org.jacoco:jacoco-maven-plugin:prepare-agent test jacoco:report
artifacts:
paths:
- target/site/jacoco/jacoco.xml
coverage-jdk11:
# test-jdk11
작업의 stage보다 뒤에 있어야 합니다.
# visualize
stage는 기본적으로 존재하지 않습니다.
# 먼저 정의하거나 deploy
와 같은 기존 stage를 선택해야 합니다.
stage: visualize
image: registry.gitlab.com/haynes/jacoco2cobertura:1.0.9
script:
# jacoco 보고서를 프로젝트의 상대적인 경로를 사용하여 cobertura로 변환합니다.
- python /opt/cover2cover.py target/site/jacoco/jacoco.xml $CI_PROJECT_DIR/src/main/java/ > target/site/cobertura.xml
needs: [“test-jdk11”]
artifacts:
reports:
coverage_report:
coverage_format: cobertura
path: target/site/cobertura.xml
```
Gradle 예시
다음의 .gitlab-ci.yml
예시는 Java 또는 Kotlin을 위해 Gradle을 사용하여 프로젝트를 빌드하고, JaCoCo 커버리지 도구를 사용하여 커버리지 artifact를 생성합니다.
자체 Docker 이미지를 빌드하려면 Docker 이미지 구성 및 스크립트를 확인할 수 있습니다.
GitLab은 Cobertura 형식의 artifact를 기대하기 때문에 업로드하기 전에 몇 가지 스크립트를 실행해야 합니다. test-jdk11
작업은 코드를 테스트하고 XML artifact를 생성합니다. coverage-jdk-11
작업은 artifact를 Cobertura 보고서로 변환합니다.
test-jdk11:
stage: test
image: gradle:6.6.1-jdk11
script:
- 'gradle test jacocoTestReport' # jacoco must be configured to create an xml report
artifacts:
paths:
- build/jacoco/jacoco.xml
coverage-jdk11:
# test-jdk11의 stage보다 나중에 있어야 합니다.
# `visualize` stage는 기본적으로 존재하지 않습니다.
# 먼저 정의하거나 `deploy`와 같은 기존 stage를 선택하세요.
stage: visualize
image: registry.gitlab.com/haynes/jacoco2cobertura:1.0.7
script:
# jacoco에서 cobertura로 보고서 변환, 상대 프로젝트 경로 사용
- python /opt/cover2cover.py build/jacoco/jacoco.xml $CI_PROJECT_DIR/src/main/java/ > build/cobertura.xml
needs: ["test-jdk11"]
artifacts:
reports:
coverage_report:
coverage_format: cobertura
path: build/cobertura.xml
Python 예시
다음의 .gitlab-ci.yml
예시는 pytest-cov를 사용하여 테스트 커버리지 데이터를 수집합니다.
run tests:
stage: test
image: python:3
script:
- pip install pytest pytest-cov
- pytest --cov --cov-report term --cov-report xml:coverage.xml
coverage: '/(?i)total.*? (100(?:\.0+)?\%|[1-9]?\d(?:\.\d+)?\%)$/'
artifacts:
reports:
coverage_report:
coverage_format: cobertura
path: coverage.xml
PHP 예시
다음의 .gitlab-ci.yml
예시는 PHP를 위해 PHPUnit을 사용하여 테스트 커버리지 데이터를 수집하고 보고서를 생성합니다.
최소한의 phpunit.xml
파일과 함께 이 예제 저장소를 참조하면 테스트를 실행하고 coverage.xml
을 생성할 수 있습니다.
run tests:
stage: test
image: php:latest
variables:
XDEBUG_MODE: coverage
before_script:
- apt-get update && apt-get -yq install git unzip zip libzip-dev zlib1g-dev
- docker-php-ext-install zip
- pecl install xdebug && docker-php-ext-enable xdebug
- php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
- php composer-setup.php --install-dir=/usr/local/bin --filename=composer
- composer install
- composer require --dev phpunit/phpunit phpunit/php-code-coverage
script:
- php ./vendor/bin/phpunit --coverage-text --coverage-cobertura=coverage.cobertura.xml
artifacts:
reports:
coverage_report:
coverage_format: cobertura
path: coverage.cobertura.xml
Codeception은 PHPUnit을 통해 Cobertura 보고서를 생성하는 것을 지원하며, 생성된 파일에 대한 경로는 --coverage-cobertura
옵션에 따라 다르며 단위 테스트 스위트의 paths 구성에 따라 달라집니다. .gitlab-ci.yml
을 구성하여 적절한 경로에서 Cobertura를 찾도록 설정하세요.
C/C++ 예시
다음의 .gitlab-ci.yml
예시는 gcc
또는 g++
컴파일러를 사용하는 C/C++를 위해 gcovr
을 사용하여 Cobertura XML 형식의 커버리지 출력 파일을 생성합니다.
이 예에서는 다음을 전제로 합니다:
-
Makefile
이cmake
에 의해 이전 stage의 다른 작업 내에서build
디렉토리에 생성되었음 (automake
를 사용하여Makefile
을 생성하는 경우make test
대신make check
를 호출해야 함). -
cmake
(또는automake
)가 컴파일러 옵션--coverage
를 설정했음.
run tests:
stage: test
script:
- cd build
- make test
- gcovr --xml-pretty --exclude-unreachable-branches --print-summary -o coverage.xml --root ${CI_PROJECT_DIR}
coverage: /^\s*lines:\s*\d+.\d+\%/
artifacts:
name: ${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}-${CI_COMMIT_SHA}
expire_in: 2 days
reports:
coverage_report:
coverage_format: cobertura
path: build/coverage.xml
Go 예시
다음과 같은 Go의 .gitlab-ci.yml
예시는 다음을 사용합니다:
- 테스트를 실행하기 위해
go test
를 사용합니다. - Go의 커버리지 프로파일을 Cobertura XML 형식으로 변환하기 위해
gocover-cobertura
를 사용합니다.
이 예시는 Go 모듈을 사용한다고 가정합니다. -covermode count
옵션은 -race
플래그와 함께 작동하지 않습니다. -race
플래그를 사용하면서 코드 커버리지를 생성하려면 -covermode atomic
으로 전환해야 하며, 이는 -covermode count
보다 느립니다. 자세한 내용은 이 블로그 포스트를 참조하십시오.
테스트 실행:
stage: test
image: golang:1.17
script:
- go install
- go test ./... -coverprofile=coverage.txt -covermode count
- go get github.com/boumenot/gocover-cobertura
- go run github.com/boumenot/gocover-cobertura < coverage.txt > coverage.xml
artifacts:
reports:
coverage_report:
coverage_format: cobertura
path: coverage.xml
Ruby 예시
다음의 Ruby의 .gitlab-ci.yml
예시는 다음을 사용합니다
- 테스트를 실행하기 위해
rspec
를 사용합니다. - 커버리지 프로필을 기록하고 Cobertura XML 형식의 보고서를 생성하기 위해
simplecov
및simplecov-cobertura
를 사용합니다.
이 예시는 다음을 전제로 합니다:
- 의존성 관리를 위해
bundler
가 사용되고 있습니다.rspec
,simplecov
,simplecov-cobertura
젬들이Gemfile
에 추가되어 있습니다. -
CoberturaFormatter
가SimpleCov.formatters
구성에spec_helper.rb
파일 내에서 추가되었습니다.
테스트 실행:
stage: test
image: ruby:3.1
script:
- bundle install
- bundle exec rspec
artifacts:
reports:
coverage_report:
coverage_format: cobertura
path: coverage/coverage.xml
문제 해결
테스트 커버리지 시각화가 표시되지 않음
테스트 커버리지 시각화가 차이점 보기에서 표시되지 않는 경우, 커버리지 보고서를 확인하여 다음을 검토할 수 있습니다:
- 차이점 보기에서 보고 있는 파일이 커버리지 보고서에 언급되어 있는지 확인합니다.
- 보고서의
source
및filename
노드가 귀하의 저장소 파일과 일치하도록 예상 구조를 따르는지 확인합니다. - 파이프라인이 완료되었는지 확인합니다. 파이프라인이 수동 작업으로 차단되어 있는 경우, 파이프라인은 완료된 것으로 간주되지 않습니다.
- 커버리지 보고서 파일이 제한을 초과하지 않았는지 확인합니다.
보고서 아티팩트는 기본적으로 다운로드할 수 없습니다. 작업 세부 정보 페이지에서 보고서를 다운로드할 수 있도록 하려면 보고서를 아티팩트 paths
에 추가하십시오:
artifacts:
paths:
- coverage/cobertura-coverage.xml
reports:
coverage_report:
coverage_format: cobertura
path: coverage/cobertura-coverage.xml