단위 테스트 보고서(Unit test reports)

단위 테스트 보고서(Unit test reports)

단위 테스트 결과를 머지 리퀘스트와 파이프라인 세부 정보에 직접 표시해 주는 기능이에요. 작업 로그를 뒤지는 일 없이 실패를 바로 파악할 수 있게 하는 것이 핵심이에요.

JUnit XML 형식을 사용하며, 테스트 실패 여부가 작업 상태에는 영향을 주지 않는다는 점을 기억하면 좋아요. 파일 형식 요구 사항, 구성 방법, 테스트 결과 보기, 스크린샷 첨부, 문제 해결까지 옆에서 설명해 주는 방식으로 정리했어요.

출처: 문서

본문

단위 테스트 보고서는 테스트 결과를 머지 리퀘스트와 파이프라인 세부 정보에 직접 표시하므로, 작업 로그를 뒤질 필요 없이 실패를 파악할 수 있어요.

단위 테스트 보고서는 다음과 같은 경우에 사용하세요.

• 머지 리퀘스트에서 테스트 실패를 즉시 확인.
• 브랜치 간 테스트 결과 비교.
• 오류 세부 정보와 스크린샷으로 실패한 테스트 디버깅.
• 시간 경과에 따른 테스트 실패 패턴 추적.

단위 테스트 보고서는 JUnit XML 형식을 요구하며 작업 상태에는 영향을 주지 않아요. 테스트가 실패할 때 작업을 실패하게 하려면 작업의 script가 0이 아닌 상태로 종료해야 해요.

GitLab Runner는 테스트 결과를 JUnit XML 형식으로 artifacts로 업로드해요. 머지 리퀘스트에 가면 테스트 결과가 소스 브랜치(head)와 대상 브랜치(base) 사이에서 비교되어 무엇이 바뀌었는지 보여줘요.

파일 형식 및 크기 제한

단위 테스트 보고서는 올바른 구문 분석과 표시를 위해 특정 요구 사항을 가진 JUnit XML 형식을 사용해야 해요.

파일 요구 사항

테스트 보고서 파일은 다음을 충족해야 해요.

• .xml 파일 확장자를 가진 JUnit XML 형식 사용.
• 개별 파일당 30MB 미만.
• 작업의 모든 JUnit 파일 총 크기가 100MB 미만.
• 중복 테스트 이름이 있으면 첫 번째 테스트만 사용되고 같은 이름의 다른 테스트는 무시돼요.

테스트 케이스 제한에 대해서는 단위 테스트 보고서당 최대 테스트 케이스를 참고하세요.

JUnit XML 형식 사양

GitLab은 UI에 테스트 결과를 표시하기 위해 JUnit XML 요소와 속성의 일부를 구문 분석해요.

XML 요소	XML 속성	설명
testsuites	time	모든 테스트 스위트의 총 실행 시간. 테스트 실행 시간 계산에 사용.
testsuite	name	테스트 스위트 이름. 내부 그룹화를 위해 구문 분석.
testsuite	time	개별 테스트 스위트의 실행 시간. 테스트 실행 시간 계산에 사용.
testcase	classname	테스트 클래스 또는 카테고리 이름. UI에서 스위트 이름으로 표시.
testcase	name	개별 테스트 이름.
testcase	file	테스트가 정의된 파일 경로.
testcase	time	초 단위 테스트 실행 시간.
failure	요소 콘텐츠	실패 메시지와 스택 트레이스.
error	요소 콘텐츠	오류 메시지와 스택 트레이스.
skipped	요소 콘텐츠	테스트를 건너뛴 이유.
system-out	요소 콘텐츠	시스템 출력과 첨부 태그. testcase 요소에서만 구문 분석.
system-err	요소 콘텐츠	시스템 오류 출력. testcase 요소에서만 구문 분석.

다음 요소와 속성은 구문 분석되지 않아요.

• testsuite 속성 (tests, failures, errors, timestamp)
• testcase 속성 (assertions, line, status)
• properties 요소
• testsuite 수준의 system-out 및 system-err

XML 구조 예시

   name="Authentication Tests" tests="1" failures="1">
     classname="LoginTest" name="test_invalid_password" file="spec/auth_spec.rb" time="0.23">
      Expected authentication to fail
      [[ATTACHMENT|screenshots/failure.png]]

이 XML은 GitLab에서 다음과 같이 표시돼요.

• 스위트: LoginTest (testcase classname에서)
• 이름: test_invalid_password (testcase name에서)
• 파일: spec/auth_spec.rb (testcase file에서)
• 시간: 0.23s (testcase time에서)
• 스크린샷: 테스트 세부 정보 대화상자에서 사용 가능 (testcase system-out에서)
• 표시되지 않음: "Authentication Tests" (testsuite name에서)

테스트 결과 유형

테스트 결과는 머지 리퀘스트의 소스와 대상 브랜치 사이에서 비교되어 무엇이 바뀌었는지 보여줘요.

• 새로 실패한 테스트(Newly failed tests): 대상 브랜치에서는 통과했지만 여러분의 브랜치에서는 실패한 테스트.
• 새로 발견된 오류(Newly encountered errors): 대상 브랜치에서는 통과했지만 여러분의 브랜치에서는 오류가 발생한 테스트.
• 기존 실패(Existing failures): 두 브랜치 모두에서 실패한 테스트.
• 해결된 실패(Resolved failures): 대상 브랜치에서는 실패했지만 여러분의 브랜치에서는 통과한 테스트.

브랜치를 비교할 수 없을 때(예: 대상 브랜치 데이터가 아직 없을 때)는 여러분의 브랜치에서 실패한 테스트만 표시돼요.

기본 브랜치에서 지난 14일 동안 실패한 테스트의 경우 Failed {n} time(s) in {default_branch} in the last 14 days와 같은 메시지를 볼 수 있어요. 이 수치는 완료된 파이프라인의 실패한 테스트를 포함하지만 차단된 파이프라인(blocked pipelines)은 포함하지 않아요. 차단된 파이프라인 지원은 이슈 431265에서 제안되고 있어요.

단위 테스트 보고서 구성

머지 리퀘스트와 파이프라인에 테스트 결과를 표시하도록 단위 테스트 보고서를 구성하세요.

단위 테스트 보고서를 구성하려면:

1. 테스트 작업이 JUnit XML 형식 테스트 보고서를 출력하도록 구성하세요. 구성 세부 정보는 테스팅 프레임워크 문서를 확인하세요.
2. .gitlab-ci.yml 파일에서 테스트 작업에 artifacts:reports:junit을 추가하세요.
3. XML 테스트 보고서 파일 경로를 지정하세요. junit 속성은 다음을 허용해요.
   • 단일 파일 이름: junit: report.xml
   • 파일 이름 패턴: junit: test-results/**/*.xml
   • 파일 이름 배열: junit: [rspec-1.xml, rspec-2.xml, rspec-3.xml]
   • 둘의 조합: junit: [rspec.xml, test-results/TEST-*.xml]
   • 디렉터리는 지원되지 않아요 (예: junit: test-results 또는 junit: test-results/**).
4. 선택 사항. 보고서 파일을 탐색 가능하게 하려면 artifacts:paths에 포함하세요.
5. 선택 사항. 작업이 실패해도 보고서를 업로드하려면 artifacts:when:always를 사용하세요.

RSpec을 사용하는 Ruby 예시 구성:

ruby:
  stage: test
  script:
    - bundle install
    - bundle exec rspec --format progress --format RspecJunitFormatter --out rspec.xml
  artifacts:
    when: always
    paths:
      - rspec.xml
    reports:
      junit: rspec.xml

테스트 결과를 볼 수 있는 곳:

• 테스트 작업이 완료된 후 파이프라인 세부 정보의 Tests 탭.
• 파이프라인이 완료된 후 머지 리퀘스트의 Test summary 패널.

머지 리퀘스트에서 테스트 결과 보기

머지 리퀘스트에서 테스트 실패에 대한 자세한 정보를 확인하세요.

Test summary 패널은 테스트 결과의 개요를 보여주며, 실패/통과한 테스트 수를 포함해요.

테스트 실패 세부 정보를 보려면:

1. 머지 리퀘스트에서 Test summary 패널로 이동하세요.
2. Test summary 패널을 펼치려면 Show details(^)를 선택하세요.
3. 실패한 테스트 옆에 있는 View details를 선택하세요.
4. 대화상자에 테스트 이름, 파일 경로, 실행 시간, 스크린샷 첨부(구성된 경우), 오류 출력이 표시돼요.

모든 테스트 결과를 보려면:

• Test summary 패널에서 Full report를 선택해 파이프라인 세부 정보의 Tests 탭으로 이동하세요.

실패한 테스트 이름 복사하기

디버깅을 위해 로컬에서 다시 실행할 수 있도록 테스트 이름을 복사하세요.

전제 조건:

• JUnit 보고서에 실패한 테스트의 <file> 속성이 포함되어야 해요.

모든 실패한 테스트 이름을 복사하려면:

• Test summary 패널에서 Copy failed tests(copy)를 선택하세요. 실패한 테스트가 공백으로 구분된 문자열로 복사돼요.

단일 실패한 테스트 이름을 복사하려면:

1. Test summary 패널을 펼치려면 Show details(^)를 선택하세요.
2. 복사할 테스트 옆에 있는 View details를 선택하세요.
3. 대화상자에서 Copy test name to rerun locally(copy)를 선택하세요.
4. 테스트 이름이 클립보드에 복사돼요.

파이프라인에서 테스트 결과 보기

하위 파이프라인의 결과를 포함해 파이프라인 세부 정보에서 모든 테스트 스위트와 케이스를 보세요.

파이프라인 테스트 결과를 보려면:

1. 파이프라인 세부 정보 페이지로 이동하세요.
2. Tests 탭을 선택하세요.
3. 개별 테스트 케이스를 보려면 테스트 스위트를 선택하세요.

Pipelines API로 테스트 보고서를 가져올 수도 있어요.

테스트 타이밍 지표

테스트 결과에는 서로 다른 타이밍 지표가 표시돼요.

• Pipeline duration: 파이프라인이 시작된 시점부터 완료될 때까지의 경과 시간.
• Test execution time: 모든 작업을 통틀어 모든 테스트를 실행하는 데 소요된 총 시간을 합산한 것.
• Queue time: 작업이 사용 가능한 러너를 기다리며 보낸 시간.

작업이 병렬로 실행되면 누적 테스트 실행 시간이 파이프라인 기간을 초과할 수 있어요.

파이프라인 기간은 결과를 기다리는 데 걸리는 시간을 보여주는 반면, 테스트 실행 시간은 사용된 컴퓨팅 리소스를 보여줘요.

예를 들어 81분 만에 완료되는 파이프라인이 여러 러너에서 많은 테스트 작업을 병렬로 실행한다면 9시간 10분의 테스트 실행 시간을 보여줄 수 있어요.

테스트 보고서에 스크린샷 추가

테스트 실패 디버깅을 돕기 위해 테스트 보고서에 스크린샷을 추가하세요.

테스트 보고서에 스크린샷을 추가하려면:

1. JUnit XML 파일에서 $CI_PROJECT_DIR에 상대적인 스크린샷 경로와 함께 첨부 태그를 추가하세요.

    time="1.00" name="Test">
     [[ATTACHMENT|/path/to/some/file]]
   

2. .gitlab-ci.yml 파일에서 작업이 스크린샷을 artifacts로 업로드하도록 구성하세요.
   • 스크린샷 파일 경로를 지정하세요.
   • 선택 사항. 테스트가 실패할 때 스크린샷을 업로드하려면 artifacts:when: always를 사용하세요.
   • 예를 들어:

     ruby:
       stage: test
       script:
         - bundle install
         - bundle exec rspec --format progress --format RspecJunitFormatter --out rspec.xml
         - # Your test framework should save screenshots to a directory
       artifacts:
         when: always
         paths:
           - rspec.xml
           - screenshots/
         reports:
           junit: rspec.xml
     

3. 파이프라인을 실행하세요.
4. Test summary 패널에서 실패한 테스트에 View details를 선택하면 테스트 세부 정보 대화상자에서 스크린샷 링크에 접근할 수 있어요.

문제 해결

테스트 보고서가 비어 있는 경우

머지 리퀘스트에서 빈 Test summary 패널을 볼 수 있어요.

이 문제는 다음 경우에 발생해요.

• 보고서 artifacts가 만료되었을 때.
• JUnit 파일이 크기 제한을 초과했을 때.

이 문제를 해결하려면 보고서 artifact에 더 긴 expire_in 값을 설정하거나, 새 보고서를 생성하기 위해 새 파이프라인을 실행하세요.

JUnit 파일이 크기 제한을 초과했다면 다음을 확인하세요.

• 개별 JUnit 파일이 30MB 미만인지.
• 작업의 모든 JUnit 파일 총 크기가 100MB 미만인지.

사용자 지정 제한 지원은 epic 16374에서 제안되고 있어요.

테스트 결과가 누락된 경우

보고서에서 예상보다 적은 테스트 결과를 볼 수 있어요.

JUnit XML 파일에 중복 테스트 이름이 있을 때 발생할 수 있어요. 각 이름에 대해 첫 번째 테스트만 사용되고 중복은 무시돼요.

이 문제를 해결하려면 모든 테스트 이름과 클래스가 고유한지 확인하세요.

머지 리퀘스트에 테스트 보고서가 표시되지 않는 경우

머지 리퀘스트에서 Test summary 패널이 전혀 보이지 않을 수 있어요.

이 문제는 대상 브랜치에 비교할 테스트 데이터가 없을 때 발생할 수 있어요.

이 문제를 해결하려면 대상 브랜치에서 파이프라인을 실행해 기준(baseline) 테스트 데이터를 생성하세요.

JUnit XML 구문 분석 오류

파이프라인에서 작업 이름 옆에 구문 분석 오류 표시가 보일 수 있어요.

JUnit XML 파일에 포맷 오류나 잘못된 요소가 포함될 때 발생할 수 있어요.

이 문제를 해결하려면:

• JUnit XML 파일이 표준 형식을 따르는지 확인하세요.
• 모든 XML 요소가 제대로 닫혔는지 확인하세요.
• 속성 이름과 값이 올바르게 포맷되었는지 확인하세요.

그룹화된 작업의 경우 그룹의 첫 번째 구문 분석 오류만 표시돼요.

더 알아보기

프레임워크별 JUnit 출력 구성 예시를 더 보고 싶다면 단위 테스트 보고서 예시 문서를 살펴보세요. 테스트 실패를 잡아내도록 파이프라인 자체를 구성하는 방법도 함께 익히면 좋아요.