# Elixir 코드 커버리지 {#elixir-code-coverage}

코드 커버리지는 테스트가 코드의 어떤 줄을 실행했는지 보여줍니다. Hex 패키지는 `mix test --cover` 실행마다 줄 단위 커버리지를 업로드하며, Tuist는 커밋의 여러 실행 결과를 프로젝트 전체, 각 OTP 애플리케이션 및 각 파일별로 하나의 수치로 집계합니다. 대시보드의 **코드 커버리지** 페이지에서는 이를 커밋별 결과와 브랜치별 추이로 확인할 수 있습니다.

> [!IMPORTANT]
> **필수 조건**
>
> - 패키지를 통해 `mix test`를 라우팅하는 <.localized_link href="/guides/get-started/elixir-project">공유 Elixir 설정</.localized_link>을 완료하세요.

## 설정 {#setup}

### 커버리지와 함께 테스트 실행하기 {#run-your-tests}

Tuist 없이 `mix test`에 전달하듯이 `--cover` 옵션을 추가하세요:

```sh
mix test --cover
```

패키지는 실행의 테스트 결과와 함께 커버리지를 업로드합니다. 테스트 스위트가 끝나면 Mix의 커버리지 도구와 동일한 동작을 수행하며, 이때 동일한 `test_coverage` 옵션으로 구성됩니다:

- **요약.** 각 모듈과 전체 커버리지를 출력합니다. `summary: false` 옵션은 이 기능을 비활성화합니다.
- **임계값.** 전체 커버리지가 임계값(기본값 90%, 직접 설정 가능) 미만이면 실행이 종료 상태 3으로 실패합니다:

```elixir
def project do
  [
    test_coverage: [summary: [threshold: 80]]
  ]
end
```

Mix와 마찬가지로 임계값은 요약 기능에 속하므로 `summary: false` 옵션은 둘 다 비활성화합니다. 실행을 실패시키지 않고 요약을 출력하려면 `threshold: 0`로 설정하세요. `test_coverage: [ignore_modules: [...]]`에 나열된 모듈은 요약 및 업로드에서 제외됩니다.

Tuist는 커밋별로 커버리지를 추적하므로 프로젝트가 Git 리포지토리에 있어야 합니다. Git 리포지토리 외부에서 실행하면 테스트 결과는 업로드되지만 커버리지는 업로드되지 않습니다.

커버리지는 패키지가 업로드하는 <.localized_link href="/guides/features/test-insights/elixir#git-history">Git 히스토리</.localized_link>에 의존하며, 이를 통해 커밋이 해당 브랜치에 배치됩니다. 지속적 통합(CI)에서의 실행은 항상 이를 업로드하며, `--cover` 실행은 모든 머신에서 이를 업로드합니다. `--cover` 옵션을 사용하면 패키지는 풀 리퀘스트가 분기된 지점도 찾습니다. 베이스 브랜치를 가져오고 필요에 따라 얕은 복제(shallow clone)의 깊이를 늘립니다. 원격 저장소와의 통신을 방지하려면 `TUIST_GIT_UNSHALLOW_ENABLED=false`로 설정하세요.

### 샤딩된 실행 {#sharded-runs}

<.localized_link href="/guides/features/test-sharding/elixir">테스트를 샤딩</.localized_link>할 때는 각 샤드를 `--cover` 옵션과 함께 실행하세요:

```sh
MIX_ENV=test TUIST_SHARD_INDEX=0 mix tuist.test --cover
```

새로운 러너에서는 샤딩 가이드의 <.localized_link href="/guides/features/test-sharding/elixir#test-phase">테스트 단계</.localized_link>에 있는 부트스트랩 명령어를 사용하고 `--cover` 옵션을 추가하세요. 이렇게 하면 샤드가 빌드를 다운로드하기 전에 Mix가 모든 의존성을 컴파일하는 것을 방지할 수 있습니다.

각 샤드는 자신의 커버리지만 보고하며 임계값을 확인하지 않습니다. 이는 테스트 스위트의 일부만 실행하기 때문입니다. Tuist는 한 번의 실행에 포함된 여러 샤드 결과를 하나의 수치로 병합합니다.

각 샤드는 다운로드한 빌드에 커버리지 카운터를 추가합니다. 대신 한 번만 처리하려면 빌드 단계에도 `--cover` 옵션을 전달하세요:

```sh
MIX_ENV=test mix tuist.test.build --shard-max 5 --cover
```

파이프라인 실행 간에 빌드 디렉터리를 유지하고 커버리지를 수집하지 않는 실행에서 재사용하여 해당 빌드가 카운터 없이 유지되도록 하려면 이 옵션을 생략하세요.

### CI에서 각 커밋 완료하기 {#complete-each-commit}

커밋의 커버리지는 종종 여러 작업(샤드별, 데이터베이스 버전별 또는 애플리케이션별)에서 생성됩니다. Tuist는 마지막 작업이 언제 보고되었는지 알 수 없으므로 직접 알려주어야 합니다. 커밋의 모든 테스트 작업이 완료되면, 해당 작업들에 종속된 작업에서 다음 명령어를 실행하세요:

```sh
MIX_ENV=test mix tuist.coverage.complete
```

이 작업은 `GIT_COMMIT` 또는 체크아웃의 `HEAD`에서 커밋을 읽습니다. 다른 커밋을 지정하려면 `--commit <sha>`를 전달하세요. 커밋이 완료될 때까지 해당 커버리지는 **진행 중**으로 표시되며 브랜치 추이에 포함되지 않습니다.

## 작동 방식 {#how-it-works}

### 네이티브 줄 카운터 {#native-line-counters}

Mix의 커버리지 도구는 각 실행 시작 시 Erlang의 `cover`를 위해 모든 모듈을 다시 컴파일하므로 대규모 프로젝트에서는 속도가 느려집니다. 대신 이 패키지는 런타임의 네이티브 줄 카운터를 사용하여 계산합니다. 마지막 실행 이후 컴파일된 모듈만 다시 컴파일하고, 런타임을 해당 카운터로 전환한 후 테스트 스위트가 끝나면 값을 읽습니다. Mix의 커버리지 도구는 사용되지 않지만 요약 및 임계값 기능은 유지됩니다.

다음의 경우 패키지는 동일한 업로드 방식으로 Mix의 커버리지 도구를 폴백으로 사용합니다:

- 엄브렐라 프로젝트의 루트. 네이티브 계산을 위해 각 애플리케이션 내부에서 테스트를 실행하세요.
- 자체 `test_coverage: [tool: ...]`를 설정한 프로젝트.
- JIT가 없는 런타임은 네이티브 계산을 지원하지 않습니다.

### Tuist가 측정하는 항목 {#what-tuist-measures}

- **애플리케이션.** 각 OTP 애플리케이션은 대시보드에서 자체 커버리지를 가진 대상으로 표시됩니다.
- **프로덕션 코드만.** 테스트 경로 아래의 파일은 테스트 코드로 간주됩니다. Tuist는 이를 저장하지만 모든 수치 계산에서는 제외합니다.
- **파일별 줄 수.** 줄은 소속된 모듈 수와 상관없이 파일당 한 번만 계산됩니다.
- **함수.** 각 줄은 바로 위에서 시작하는 절을 가진 함수에 속합니다. 컴파일러나 매크로가 생성한 함수(`__info__/1` 또는 `__schema__/1` 등)는 목록에 표시되지 않지만, 해당 줄은 여전히 파일 계산에 포함됩니다.

따라서 Tuist의 수치는 Mix의 자체 커버리지 보고서와 몇 가지 차이가 있습니다. 테스트 코드를 제외하고 모듈별이 아닌 파일별로 줄을 계산합니다. 또한 네이티브 계산은 애플리케이션 시작 중에 실행되는 코드를 포함하며, 컴파일러가 절대 실행되지 않음을 증명해 낸 줄은 제외합니다(Mix 도구는 이를 '커버되지 않음'으로 보고합니다).

### 스킵된 테스트 {#skipped-tests}

Tuist는 실행에서 제외된 테스트의 커버리지를 이어갈 수 없습니다. 패키지는 각 테스트가 실행한 내용이 아니라 전체 실행이 수행한 내용을 기록하기 때문입니다. 따라서 `--only`, `--exclude`, `--failed`, `--stale`, `--name-pattern`, `--max-failures` 옵션이나 특정 테스트 파일/줄을 사용하여 실행 인수가 테스트를 제외하면, 아무것도 제외하지 않은 동일 변형(variant)의 실행이 함께 수행되지 않는 한 해당 커밋의 커버리지는 **불완전**으로 표시됩니다. `--exclude slow`와 `--only slow`처럼 각각 테스트를 제외하는 두 실행은 함께 모든 테스트를 실행하더라도 커밋을 불완전하게 만듭니다.

일부 테스트는 의도적으로 제외되며 커밋을 불완전하게 만들지 않습니다:

- **테스트 헬퍼의 제외 항목.** `ExUnit.start(exclude: [...])`가 기본적으로 제외하는 테스트는 프로젝트가 기본적으로 실행하기로 선택한 스위트 범위이므로 Tuist는 이를 누락된 것으로カウント하지 않습니다. `--include` 또는 `--only` 옵션을 사용하여 다른 작업에서 이를 실행하면 해당 커버리지가 커밋에 추가됩니다.
- **코드에서 스킵된 테스트**: `@tag :skip` 태그 사용.
- **<.localized_link href="/guides/features/test-insights/flaky-tests/elixir#quarantining">격리</.localized_link>가 스킵한 테스트.** 제거된 것과 동일하게 취급되어 제외되므로, 해당 테스트만 커버했던 줄은 커버되지 않은 것으로 계산됩니다.

### 완료 및 불완전 커밋 {#commit-status}

대시보드의 각 커밋에는 상태가 표시됩니다:

| 상태 | 의미 |
| --- | --- |
| 진행 중 | 실행에서 커버리지가 보고되었지만, 아직 해당 커밋에 대해 `mix tuist.coverage.complete`가 실행되지 않았습니다. |
| 완료 | 커밋의 모든 실행에서 테스트가 수행되었거나 의도적으로 제외되었습니다. |
| 불완전 | 일부 커버리지를 확인할 수 없어 수치가 하한선으로 표시됩니다. |
| 측정되지 않음 | 해당 커밋에 대해 커버리지를 보고한 실행이 없습니다. |

브랜치의 추세에는 완료된 커밋만 포함됩니다. 예를 들어 다음과 같은 경우 커밋이 불완전합니다:

- 변형(variant)의 모든 실행이 자체 인수로 테스트를 제외했습니다.
- 변형의 모든 실행에서 일부 샤드가 누락되었습니다.
- 변형의 커버리지가 커밋되지 않은 변경 사항이 있는 체크아웃에서의 CI 실행에서만 발생했습니다.

변형은 `--scheme`로 전달하는 라벨(예: 데이터베이스 버전)입니다. 라벨이 없는 실행은 하나의 변형으로 간주됩니다. 커밋 수치는 모든 실행을 병합하지만, Tuist는 각 변형의 완전성을 개별적으로 확인하므로 각 변형에는 아무것도 제외하지 않은 실행이 필요합니다.

## 성능 영향 {#performance-impact}

커버리지 수집에는 오버헤드가 추가되므로 `--cover` 옵션을 사용한 실행은 사용하지 않은 실행보다 시간이 더 걸립니다. 첫 번째 실행에서는 줄 카운터를 사용하여 모듈을 다시 컴파일하지만, 이후 실행에서는 변경된 부분만 다시 컴파일하므로 비용이 훨씬 적게 듭니다. 대규모 프로젝트에서는 네이티브 계산이 Mix의 커버리지 도구보다 훨씬 빠릅니다.

## 제한 사항 {#limitations}

- **HTML 보고서 없음.** 네이티브 계산은 `test_coverage: [output: ...]` 디렉터리에 보고서를 작성하지 않으며, 해당 디렉터리가 설정되어 있으면 실행 시 경고가 표시됩니다. 대신 대시보드의 파일 페이지에서 커버된 줄을 확인할 수 있습니다.
- **재시도로 커버리지 추가 안 됨.** <.localized_link href="/guides/features/test-insights/flaky-tests/elixir#test-retries">테스트 재시도</.localized_link> 기능 사용 시 커버리지는 첫 번째 시도 기준으로 기록됩니다. 해당 시도에서 이미 실패한 테스트가 실행되었으므로, 누락되는 줄은 불안정한(flaky) 테스트가 재시도에서는 도달하지만 첫 번째 시도에서는 도달하지 못한 줄뿐입니다.
- **포크된 풀 리퀘스트에서는 커버리지 없음.** 커버리지는 Tuist로 인증된 실행에서만 업로드되며, CI는 일반적으로 포크에서 열린 풀 리퀘스트에 대한 비밀 키와 신원 토큰을 제공하지 않으므로 해당 실행에서는 커버리지가 보고되지 않습니다. 병합되면 커밋이 자격 증명을 사용하여 브랜치에서 실행되고 평소대로 커버리지를 보고합니다.

## 커버리지 조회 {#querying}

대시보드의 **코드 커버리지** 페이지에는 각 커밋의 수치, 애플리케이션, 파일 및 각 실행이 커버한 줄이 표시됩니다. 동일한 데이터는 <.localized_link href="/guides/features/agentic-coding/mcp">Model Context Protocol 서버</.localized_link>를 통해 에이전트에서도 사용할 수 있습니다.
