커버리지 시각화

커버리지 시각화 (Coverage visualization)

MR diff에 라인별 커버리지 주석을 표시하고 싶다면, artifacts:reports:coverage_report 키워드를 사용해요. 다만 이 키워드는 diff 주석만 표시하고, MR 위젯에 커버리지 백분율을 보여주거나 이력 그래프를 채우지는 않아요. 백분율을 표시하려면 coverage 키워드를 별도로 구성하세요.

출처: 문서

본문

  • 티어(Tier): Free, Premium, Ultimate
  • 제공 방식(Offering): GitLab.com, GitLab Self-Managed, GitLab Dedicated

파이프라인이 완료되면 GitLab이 리포트를 백그라운드에서 처리하고 MR diff의 라인을 주석 처리해요:

  • 초록(Green): 라인이 테스트로 커버됨.
  • 빨강(Red): 라인이 테스트로 커버되지 않음.
  • 주황(Orange, Cobertura 전용): 라인이 로드되었지만 실행되지 않음.

주석은 MR diff에서 변경된 파일에만 나타나요. MR에서 변경되지 않은 파일은 리포트에 커버리지 데이터가 있더라도 주석이 붙지 않습니다.

커버리지 시각화 구성하기

커버리지 시각화를 구성하려면 job에 artifacts:reports:coverage_report를 추가해요:

test:
  script:
    - run tests with coverage
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura  # or jacoco
        path: coverage/coverage.xml

언어별 예시는 다음을 참고하세요:

여러 리포트를 모으려면 아티팩트 경로에 와일드카드를 사용하세요. GitLab이 결과를 단일 리포트로 병합합니다.

자식 파이프라인의 커버리지 리포트도 MR diff 주석에 나타나요.

제한 사항

제한 값
최대 Cobertura XML 파일 크기 10 MiB
Cobertura XML 파일의 최대 <source> 노드 수 100

Cobertura 리포트가 100개가 넘는 <source> 노드를 포함하면 diff 뷰에서 주석이 누락되거나 어긋날 수 있어요. 큰 프로젝트에서는 리포트를 더 작은 파일로 나누세요. 자세한 내용은 issue 328772을 참고하세요.

시각화는 파이프라인이 완료된 후에만 나타나요. 파이프라인에 차단형 수동 job이 있으면, 그 job이 실행되기 전까지 시각화를 사용할 수 없습니다.

job 세부 정보 페이지에서 커버리지 리포트를 다운로드하려면 아티팩트 paths와 reports에 추가하세요:

artifacts:
  paths:
    - coverage/cobertura-coverage.xml
  reports:
    coverage_report:
      coverage_format: cobertura
      path: coverage/cobertura-coverage.xml

경로 해석

커버리지 리포트는 상대 파일 경로를 사용해요. GitLab은 이 경로를 MR에서 변경된 파일과 대조해서 절대 리포지토리 경로로 해석합니다.

JaCoCo의 경우 일치 과정은 다음과 같아요:

  1. 같은 파이프라인 ref에 대한 모든 MR을 찾아요.
  2. 변경된 모든 파일에 대해 절대 경로를 수집해요.
  3. 리포트의 각 상대 경로에 대해 처음 일치하는 절대 경로를 사용해요.

Cobertura의 경우 GitLab은 <sources> 요소로 경로를 재구성하기도 해요:

  1. 각 <source> 항목에서 경로 세그먼트를 추출해요.
  2. 각 세그먼트를 각 <class> 요소의 filename 속성과 결합해요.
  3. 후보 경로가 리포지토리에 존재하는지 확인해요.
  4. 첫 번째 일치 항목을 절대 경로로 사용해요.

이 자동 보정은 <source> 경로가 <CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/... 형식을 따를 때만 동작해요.

경로 해석 예시

전체 경로가 test-org/test-cs-project인 C# 프로젝트에 다음 파일이 프로젝트 루트 기준으로 있다고 해볼게요:

Auth/User.cs
Lib/Utils/User.cs

Cobertura XML에 다음 sources가 있다면:

<sources>
  <source>/builds/test-org/test-cs-project/Auth</source>
  <source>/builds/test-org/test-cs-project/Lib/Utils</source>
</sources>

파서는 sources에서 Auth와 Lib/Utils를 추출한 뒤 각각을 각 <class> 요소의 filename 속성과 결합해요. filename="User.cs"인 클래스의 경우 리포지토리의 파일과 일치하는 첫 번째 후보는 Auth/User.cs입니다.

각 <class> 요소에 대해 파서는 최대 100회 반복을 시도해요. 일치 항목이 없으면 그 클래스는 최종 커버리지 리포트에 포함되지 않습니다.

문제 해결 (Troubleshooting)

커버리지 시각화를 다룰 때 다음 문제가 생길 수 있어요.

Diff 주석이 나타나지 않아요

주석이 나타나지 않는 이유는 다음과 같아요:

  • 파이프라인이 아직 완료되지 않았어요. 주석은 파이프라인이 끝난 뒤 생성돼요. 파이프라인이 완료될 때까지 기다렸다가 MR diff를 다시 로드하세요.
  • 파일이 MR diff에 없어요. 주석은 MR에서 변경된 파일에만 나타나요. 리포트에 다른 파일의 커버리지 데이터가 있더라도 마찬가지예요.
  • 리포트의 파일 경로가 리포지토리 경로와 일치하지 않아요. 경로 해석이 실패하면 주석은 조용히 건너뛰어져요. 진단하려면 커버리지 XML 아티팩트를 다운로드해서 <class> 요소의 filename 속성과 프로젝트 루트 기준 리포지토리의 파일 경로를 비교해 보세요.
  • 프로젝트에 상대 경로가 중복된 모듈이 여러 개 있어요. 모듈 간 경로가 유일하지 않으면 GitLab은 주석이 어떤 파일에 속하는지 해석할 수 없어요. 모듈 간 상대 경로가 유일하도록 하세요: src/main/java/org/acme/DemoExample.java - src/main/other-module/org/acme/DemoExample.java + src/main/other-module/org/acme/OtherDemoExample.java
  • coverage 키워드가 구성되지 않았어요. artifacts:reports:coverage_report는 MR 위젯에 백분율을 만들지 않아요. 커버리지 백분율을 표시하려면 coverage 키워드를 별도로 구성하세요.

일부 변경 파일에만 메트릭이 표시돼요

이 문제는 같은 소스 브랜치에서 다른 대상 브랜치로 새 MR을 만들 때 발생해요. 파이프라인이 이전 MR의 diff를 사용해서, 그 diff에 없는 파일에는 주석을 표시하지 않습니다.

이 문제를 해결하려면 새 MR이 생성될 때까지 기다렸다가 파이프라인을 다시 실행하세요.

더 알아보기 (Learn more)