Elixir 코드 커버리지
코드 커버리지는 테스트가 코드의 어떤 줄을 실행했는지 보여줍니다. Hex 패키지는 mix test --cover 실행마다 줄 단위 커버리지를 업로드하며, Tuist는 커밋의 여러 실행 결과를 프로젝트 전체, 각 OTP 애플리케이션 및 각 파일별로 하나의 수치로 집계합니다. 대시보드의 코드 커버리지 페이지에서는 이를 커밋별 결과와 브랜치별 추이로 확인할 수 있습니다.
- 패키지를 통해
mix test를 라우팅하는 공유 Elixir 설정을 완료하세요.
설정#
커버리지와 함께 테스트 실행하기#
Tuist 없이 mix test에 전달하듯이 --cover 옵션을 추가하세요:
mix test --cover
패키지는 실행의 테스트 결과와 함께 커버리지를 업로드합니다. 테스트 스위트가 끝나면 Mix의 커버리지 도구와 동일한 동작을 수행하며, 이때 동일한 test_coverage 옵션으로 구성됩니다:
- 요약. 각 모듈과 전체 커버리지를 출력합니다.
summary: false옵션은 이 기능을 비활성화합니다. - 임계값. 전체 커버리지가 임계값(기본값 90%, 직접 설정 가능) 미만이면 실행이 종료 상태 3으로 실패합니다:
def project do
[
test_coverage: [summary: [threshold: 80]]
]
end
Mix와 마찬가지로 임계값은 요약 기능에 속하므로 summary: false 옵션은 둘 다 비활성화합니다. 실행을 실패시키지 않고 요약을 출력하려면 threshold: 0로 설정하세요. test_coverage: [ignore_modules: [...]]에 나열된 모듈은 요약 및 업로드에서 제외됩니다.
Tuist는 커밋별로 커버리지를 추적하므로 프로젝트가 Git 리포지토리에 있어야 합니다. Git 리포지토리 외부에서 실행하면 테스트 결과는 업로드되지만 커버리지는 업로드되지 않습니다.
커버리지는 패키지가 업로드하는 Git 히스토리에 의존하며, 이를 통해 커밋이 해당 브랜치에 배치됩니다. 지속적 통합(CI)에서의 실행은 항상 이를 업로드하며, --cover 실행은 모든 머신에서 이를 업로드합니다. --cover 옵션을 사용하면 패키지는 풀 리퀘스트가 분기된 지점도 찾습니다. 베이스 브랜치를 가져오고 필요에 따라 얕은 복제(shallow clone)의 깊이를 늘립니다. 원격 저장소와의 통신을 방지하려면 TUIST_GIT_UNSHALLOW_ENABLED=false로 설정하세요.
샤딩된 실행#
테스트를 샤딩할 때는 각 샤드를 --cover 옵션과 함께 실행하세요:
MIX_ENV=test TUIST_SHARD_INDEX=0 mix tuist.test --cover
새로운 러너에서는 샤딩 가이드의 테스트 단계에 있는 부트스트랩 명령어를 사용하고 --cover 옵션을 추가하세요. 이렇게 하면 샤드가 빌드를 다운로드하기 전에 Mix가 모든 의존성을 컴파일하는 것을 방지할 수 있습니다.
각 샤드는 자신의 커버리지만 보고하며 임계값을 확인하지 않습니다. 이는 테스트 스위트의 일부만 실행하기 때문입니다. Tuist는 한 번의 실행에 포함된 여러 샤드 결과를 하나의 수치로 병합합니다.
각 샤드는 다운로드한 빌드에 커버리지 카운터를 추가합니다. 대신 한 번만 처리하려면 빌드 단계에도 --cover 옵션을 전달하세요:
MIX_ENV=test mix tuist.test.build --shard-max 5 --cover
파이프라인 실행 간에 빌드 디렉터리를 유지하고 커버리지를 수집하지 않는 실행에서 재사용하여 해당 빌드가 카운터 없이 유지되도록 하려면 이 옵션을 생략하세요.
CI에서 각 커밋 완료하기#
커밋의 커버리지는 종종 여러 작업(샤드별, 데이터베이스 버전별 또는 애플리케이션별)에서 생성됩니다. Tuist는 마지막 작업이 언제 보고되었는지 알 수 없으므로 직접 알려주어야 합니다. 커밋의 모든 테스트 작업이 완료되면, 해당 작업들에 종속된 작업에서 다음 명령어를 실행하세요:
MIX_ENV=test mix tuist.coverage.complete
이 작업은 GIT_COMMIT 또는 체크아웃의 HEAD에서 커밋을 읽습니다. 다른 커밋을 지정하려면 --commit <sha>를 전달하세요. 커밋이 완료될 때까지 해당 커버리지는 진행 중으로 표시되며 브랜치 추이에 포함되지 않습니다.
작동 방식#
네이티브 줄 카운터#
Mix의 커버리지 도구는 각 실행 시작 시 Erlang의 cover를 위해 모든 모듈을 다시 컴파일하므로 대규모 프로젝트에서는 속도가 느려집니다. 대신 이 패키지는 런타임의 네이티브 줄 카운터를 사용하여 계산합니다. 마지막 실행 이후 컴파일된 모듈만 다시 컴파일하고, 런타임을 해당 카운터로 전환한 후 테스트 스위트가 끝나면 값을 읽습니다. Mix의 커버리지 도구는 사용되지 않지만 요약 및 임계값 기능은 유지됩니다.
다음의 경우 패키지는 동일한 업로드 방식으로 Mix의 커버리지 도구를 폴백으로 사용합니다:
- 엄브렐라 프로젝트의 루트. 네이티브 계산을 위해 각 애플리케이션 내부에서 테스트를 실행하세요.
- 자체
test_coverage: [tool: ...]를 설정한 프로젝트. - JIT가 없는 런타임은 네이티브 계산을 지원하지 않습니다.
Tuist가 측정하는 항목#
- 애플리케이션. 각 OTP 애플리케이션은 대시보드에서 자체 커버리지를 가진 대상으로 표시됩니다.
- 프로덕션 코드만. 테스트 경로 아래의 파일은 테스트 코드로 간주됩니다. Tuist는 이를 저장하지만 모든 수치 계산에서는 제외합니다.
- 파일별 줄 수. 줄은 소속된 모듈 수와 상관없이 파일당 한 번만 계산됩니다.
- 함수. 각 줄은 바로 위에서 시작하는 절을 가진 함수에 속합니다. 컴파일러나 매크로가 생성한 함수(
__info__/1또는__schema__/1등)는 목록에 표시되지 않지만, 해당 줄은 여전히 파일 계산에 포함됩니다.
따라서 Tuist의 수치는 Mix의 자체 커버리지 보고서와 몇 가지 차이가 있습니다. 테스트 코드를 제외하고 모듈별이 아닌 파일별로 줄을 계산합니다. 또한 네이티브 계산은 애플리케이션 시작 중에 실행되는 코드를 포함하며, 컴파일러가 절대 실행되지 않음을 증명해 낸 줄은 제외합니다(Mix 도구는 이를 '커버되지 않음'으로 보고합니다).
스킵된 테스트#
Tuist는 실행에서 제외된 테스트의 커버리지를 이어갈 수 없습니다. 패키지는 각 테스트가 실행한 내용이 아니라 전체 실행이 수행한 내용을 기록하기 때문입니다. 따라서 --only, --exclude, --failed, --stale, --name-pattern, --max-failures 옵션이나 특정 테스트 파일/줄을 사용하여 실행 인수가 테스트를 제외하면, 아무것도 제외하지 않은 동일 변형(variant)의 실행이 함께 수행되지 않는 한 해당 커밋의 커버리지는 불완전으로 표시됩니다. --exclude slow와 --only slow처럼 각각 테스트를 제외하는 두 실행은 함께 모든 테스트를 실행하더라도 커밋을 불완전하게 만듭니다.
일부 테스트는 의도적으로 제외되며 커밋을 불완전하게 만들지 않습니다:
- 테스트 헬퍼의 제외 항목.
ExUnit.start(exclude: [...])가 기본적으로 제외하는 테스트는 프로젝트가 기본적으로 실행하기로 선택한 스위트 범위이므로 Tuist는 이를 누락된 것으로カウント하지 않습니다.--include또는--only옵션을 사용하여 다른 작업에서 이를 실행하면 해당 커버리지가 커밋에 추가됩니다. - 코드에서 스킵된 테스트:
@tag :skip태그 사용. - 격리가 스킵한 테스트. 제거된 것과 동일하게 취급되어 제외되므로, 해당 테스트만 커버했던 줄은 커버되지 않은 것으로 계산됩니다.
완료 및 불완전 커밋#
대시보드의 각 커밋에는 상태가 표시됩니다:
| 상태 | 의미 |
|---|---|
| 진행 중 | 실행에서 커버리지가 보고되었지만, 아직 해당 커밋에 대해 mix tuist.coverage.complete가 실행되지 않았습니다. |
| 완료 | 커밋의 모든 실행에서 테스트가 수행되었거나 의도적으로 제외되었습니다. |
| 불완전 | 일부 커버리지를 확인할 수 없어 수치가 하한선으로 표시됩니다. |
| 측정되지 않음 | 해당 커밋에 대해 커버리지를 보고한 실행이 없습니다. |
브랜치의 추세에는 완료된 커밋만 포함됩니다. 예를 들어 다음과 같은 경우 커밋이 불완전합니다:
- 변형(variant)의 모든 실행이 자체 인수로 테스트를 제외했습니다.
- 변형의 모든 실행에서 일부 샤드가 누락되었습니다.
- 변형의 커버리지가 커밋되지 않은 변경 사항이 있는 체크아웃에서의 CI 실행에서만 발생했습니다.
변형은 --scheme로 전달하는 라벨(예: 데이터베이스 버전)입니다. 라벨이 없는 실행은 하나의 변형으로 간주됩니다. 커밋 수치는 모든 실행을 병합하지만, Tuist는 각 변형의 완전성을 개별적으로 확인하므로 각 변형에는 아무것도 제외하지 않은 실행이 필요합니다.
성능 영향#
커버리지 수집에는 오버헤드가 추가되므로 --cover 옵션을 사용한 실행은 사용하지 않은 실행보다 시간이 더 걸립니다. 첫 번째 실행에서는 줄 카운터를 사용하여 모듈을 다시 컴파일하지만, 이후 실행에서는 변경된 부분만 다시 컴파일하므로 비용이 훨씬 적게 듭니다. 대규모 프로젝트에서는 네이티브 계산이 Mix의 커버리지 도구보다 훨씬 빠릅니다.
제한 사항#
- HTML 보고서 없음. 네이티브 계산은
test_coverage: [output: ...]디렉터리에 보고서를 작성하지 않으며, 해당 디렉터리가 설정되어 있으면 실행 시 경고가 표시됩니다. 대신 대시보드의 파일 페이지에서 커버된 줄을 확인할 수 있습니다. - 재시도로 커버리지 추가 안 됨. 테스트 재시도 기능 사용 시 커버리지는 첫 번째 시도 기준으로 기록됩니다. 해당 시도에서 이미 실패한 테스트가 실행되었으므로, 누락되는 줄은 불안정한(flaky) 테스트가 재시도에서는 도달하지만 첫 번째 시도에서는 도달하지 못한 줄뿐입니다.
- 포크된 풀 리퀘스트에서는 커버리지 없음. 커버리지는 Tuist로 인증된 실행에서만 업로드되며, CI는 일반적으로 포크에서 열린 풀 리퀘스트에 대한 비밀 키와 신원 토큰을 제공하지 않으므로 해당 실행에서는 커버리지가 보고되지 않습니다. 병합되면 커밋이 자격 증명을 사용하여 브랜치에서 실행되고 평소대로 커버리지를 보고합니다.
커버리지 조회#
대시보드의 코드 커버리지 페이지에는 각 커밋의 수치, 애플리케이션, 파일 및 각 실행이 커버한 줄이 표시됩니다. 동일한 데이터는 Model Context Protocol 서버를 통해 에이전트에서도 사용할 수 있습니다.