# Покрытие кода Elixir {#elixir-code-coverage}

Покрытие кода показывает, какие строки вашего кода выполнили тесты. Пакет Hex загружает покрытие по строкам каждого запуска `mix test --cover`, а Tuist объединяет запуски коммита в одну метрику для проекта, каждого OTP-приложения и каждого файла. На странице **Code Coverage** дашборда она отображается по коммитам и в виде тренда для каждой ветки.

> [!IMPORTANT]
> **Требования**
>
> - Выполните <.localized_link href="/guides/get-started/elixir-project">общую настройку Elixir</.localized_link>, которая направляет `mix test` через пакет

## Настройка {#setup}

### Запуск тестов с покрытием {#run-your-tests}

Передайте `--cover`, как вы бы это сделали для `mix test` без Tuist:

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

Пакет загружает покрытие вместе с результатами тестов запуска. Когда набор тестов завершается, он также выполняет действия инструмента покрытия Mix, настроенного с теми же опциями `test_coverage`:

- **Сводка.** Выводится покрытие каждого модуля и общее покрытие. `summary: false` отключает эту функцию.
- **Порог.** Запуск завершается с ошибкой (код выхода 3), если общее покрытие падает ниже порога, который по умолчанию составляет 90%, если вы не задали иное:

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

Как и в Mix, порог относится к сводке, поэтому `summary: false` отключает обе функции. Чтобы вывести сводку без прерывания запуска, установите `threshold: 0`. Модули, перечисленные в `test_coverage: [ignore_modules: [...]]`, исключаются из сводки и загрузки.

Tuist отслеживает покрытие по коммитам, поэтому ваш проект должен находиться в репозитории Git: запуск вне репозитория загрузит результаты тестов, но не покрытие.

Покрытие опирается на <.localized_link href="/guides/features/test-insights/elixir#git-history">историю Git</.localized_link>, которую загружает пакет, размещая коммит в его ветке. Запуски в непрерывной интеграции всегда загружают её, а запуски `--cover` загружают её на любой машине. С помощью `--cover` пакет также определяет точку ответвления пул-реквеста: он получает базовую ветку и углубляет поверхностный клон по мере необходимости. Установите `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
```

На новом раннере используйте команду bootstrap из раздела <.localized_link href="/guides/features/test-sharding/elixir#test-phase">фаза тестирования</.localized_link> руководства по шардированию, которая предотвращает компиляцию всех зависимостей Mix до того, как шард загрузит свою сборку, и добавьте к ней `--cover`.

Шард сообщает только своё собственное покрытие и не проверяет порог, так как выполняет часть набора тестов. 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` 체크아웃a; передайте `--commit <sha>`, чтобы указать другой коммит. Пока коммит не завершён, его покрытие отображается как **В процессе** и не включается в тренд ветки.

## Как это работает {#how-it-works}

### Нативные счётчики строк {#native-line-counters}

Инструмент покрытия Mix перекомпилирует каждый модуль для `cover` Erlang в начале каждого запуска, что замедляет работу на больших проектах. Вместо этого пакет использует нативные счётчики строк среды выполнения. Он перекомпилирует только те модули, которые были изменены с последнего запуска, переключает среду выполнения на эти счётчики и считывает их по завершении набора тестов. Инструмент покрытия Mix не используется, но его сводка и порог сохраняются.

Пакет возвращается к инструменту покрытия Mix с той же загрузкой в следующих случаях:

- Корень umbrella-проекта. Запускайте тесты внутри каждого приложения для нативного подсчёта.
- Проект, который устанавливает свой собственный `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` или указывают файлы или строки тестов, покрытие коммита будет **Неполным**, если не был выполнен также запуск той же вариации, ничего не исключающий. Два запуска, каждый из которых исключает тесты, например `--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` ещё не выполнен для этого коммита. |
| Завершён | Все тесты запусков коммита выполнились или были намеренно пропущены. |
| Неполный | Некоторые данные о покрытии не удалось определить, поэтому показатель является нижней границей. |
| Не измерено | Ни один запуск не сообщил о покрытии для этого коммита. |

Тренд ветки включает только завершённые коммиты. Коммит считается неполным, например, когда:

- Каждый запуск вариации исключал тесты своими аргументами.
- В каждом запуске вариации отсутствовали некоторые шарды.
- Покрытие вариации получено только из запусков 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> покрытием считается результат первой попытки. Эта попытка уже выполнила упавшие тесты, поэтому отсутствуют только те строки, которые нестабильный тест достигает при повторной попытке, но не при первой.
- **Нет покрытия из пул-реквестов из форков.** Покрытие загружается только запусками, прошедшими аутентификацию в Tuist, а CI обычно скрывает секреты и токены идентификации от пул-реквестов, открытых из форков, поэтому такие запуски не сообщают о покрытии. После слияния коммит выполняется в вашей ветке с учётными данными и сообщает о своём покрытии как обычно.

## Запрос данных о покрытии {#querying}

На странице **Покрытие кода** панели отображается показатель каждого коммита, его приложения и файлы со строками, покрытыми каждым запуском. Те же данные доступны агентам через <.localized_link href="/guides/features/agentic-coding/mcp">сервер Model Context Protocol</.localized_link>.
