# Сгенерированный проект Xcode {#generated-xcode-project-flaky-tests}

> [!IMPORTANT]
> **Требования**
>
> - Настроены <.localized_link href="/guides/features/test-insights/xcode">аналитика тестов Xcode</.localized_link> (автосгенерированные схемы включают пост-действие `tuist inspect test`; в пользовательские схемы его нужно добавить).

Нестабильные тесты — это тесты, которые выдают разные результаты (проходят или падают) при многократном запуске с одним и тем же кодом. Они подрывают доверие к вашему набору тестов и отнимают время разработчиков на расследование ложных сбоев. Tuist автоматически обнаруживает нестабильные тесты и помогает отслеживать их со временем.


![Страница нестабильных тестов](/images/guides/features/test-insights/flaky-tests-page.png)

## Как работает обнаружение нестабильности {#how-it-works}

Tuist обнаруживает нестабильные тесты двумя способами:

### Повторные запуски тестов {#test-retries}

Когда вы запускаете тесты с функцией повторных попыток, Tuist анализирует результаты каждой попытки. Если тест падает в одних попытках, но проходит в других, он помечается как нестабильный.

Передайте `-retry-tests-on-failure` или `-test-iterations` через `tuist test`:

```sh
tuist test MyScheme -- -retry-tests-on-failure -test-iterations 3
```

![Детали нестабильного тест-кейса](/images/guides/features/test-insights/flaky-test-case-detail.png)

### Обнаружение нестабильности между запусками {#cross-run-detection}

Даже без повторных запусков тестов Tuist может обнаруживать нестабильные тесты, сравнивая результаты разных запусков CI для одного и того же коммита, схемы и указанного назначения (имя устройства, платформа и версия ОС). Если тест проходит в одном подходящем запуске CI, но падает в другом, неудачное выполнение помечается как нестабильное. Это работает независимо от того, какой результат приходит первым.

Один и тот же тест может стабильно вести себя по-разному в зависимости от схемы или назначения. Например, успешное прохождение на iOS 26 и падение на iOS 27 не свидетельствует о нестабильности. Результаты из разных схем, устройств, платформ или версий ОС не помечают друг друга как нестабильные.

Запуски без метаданных назначения или охватывающие несколько назначений сравниваются только между собой, поэтому различия в окружении между ними всё равно могут быть отмечены как нестабильность. Обнаружение на основе повторных запусков также применяется.

Это особенно полезно для выявления нестабильных тестов, которые падают недостаточно регулярно, чтобы их поймали повторные запуски, но всё же вызывают периодические сбои в CI.


## Управление нестабильными тестами {#managing-flaky-tests}

### Автоматическая очистка {#automatic-clearing}

Обнаружение и очистка выполняются через **автоматизированное оповещение** в проекте. Каждый проект получает автоматизацию «Обнаружение нестабильных тестов» по умолчанию, чей *триггер* помечает тест как нестабильный, а *восстановление* снимает эту пометку, когда тест проходит настроенный период восстановления (по умолчанию **14 дней**) без повторного срабатывания. Отредактируйте её в разделе **Настройки → Автоматизации**, чтобы изменить период восстановления, действия при восстановлении (например, также вывести тест из карантина) или полностью отключить восстановление, чтобы тесты оставались помеченными как нестабильные, пока вы не снимете пометку вручную.

### Ручное управление {#manual-management}

Вы также можете вручную помечать тесты как нестабильные или снимать эту пометку на странице сведений о тест-кейсе. Это полезно, когда:
- Вы хотите отметить известный нестабильный тест, пока работаете над исправлением
- Тест был ошибочно помечен из-за проблем с инфраструктурой


## Карантин для нестабильных тестов {#quarantining}

Карантин изолирует нестабильный тест, чтобы он не блокировал CI, пока вы его исправляете. По умолчанию это **ручное действие**: вы помещаете тест в карантин, выводите его из карантина и переключаете режимы на странице деталей тест-кейса в дашборде. Также можно настроить **автоматическое оповещение** в разделе **Settings → Automations**, чтобы тест автоматически игнорировался (или пропускался) при превышении порога нестабильности и выводился из карантина после восстановления. Каждый переход, ручной или автоматический, записывается в журнал аудита тест-кейса.

По умолчанию восстановление ожидает, пока условие срабатывания перестанет выполняться, поэтому тест остается в карантине, пока старые нестабильные запуски не выйдут из окна срабатывания. Чтобы ускорить восстановление, установите для **Recover when** значение **No new flaky runs**: тест восстановится, если в течение окна восстановления (в днях или запускаx) не будет новых нестабильных запусков; каждый новый нестабильный запуск сбрасывает этот таймер ожидания, а после восстановления только новый нестабильный запуск снова поместит тест в карантин.


Тест в карантине может находиться в одном из двух режимов:

- **Игнорирование сбоев**: тест всё ещё запускается, но `tuist test` скрывает ошибку. Ошибки по-прежнему поступают в детектор нестабильных тестов, поэтому вы можете продолжать наблюдать за тестом, не ломая сборку. Выбирайте этот режим для теста, который вы активно исследуете.
- **Пропуск**: xcodebuild получает `-skip-testing <identifier>`, поэтому тест никогда не запускается. Он не создаёт новых результатов и исчезает с панели нестабильных тестов, пока вы не включите его снова. Выбирайте этот режим, когда тест сломан, медленный или настолько постоянно нестабилен, что его запуск просто тратит минуты CI впустую.

### Почему карантинированные тесты могут отображаться как пройденные {#quarantined-passing}

- **Тесты с игнорированием сбоев** всё равно выполняются. Если такой тест завершается ошибкой, она фиксируется как **неудачная** в рамках запуска тест-кейса и помечается как нестабильная; статус отдельного теста не перезаписывается. Переопределяется только **общий результат запуска тестов**: если все неудачные тест-кейсы в запуске имеют игнорирование сбоев, весь запуск считается успешным, поэтому такие сбои не ломают CI.
- **Пропущенные тесты** вообще не выполняются, поэтому на панели управления продолжает отображаться статус последнего фактического выполнения теста. Этот снимок может быть недельной давности.


### Запуск тестов {#running-tests}

`tuist test` автоматически учитывает оба режима:

```sh
tuist test
```

Пропущенные тесты передаются в xcodebuild как `-skip-testing` и никогда не запускаются. Тесты с игнорированием сбоев запускаются нормально; если они падают, ошибка скрывается в итоговом статусе сборки.

Чтобы полностью обойти карантин и запустить всё, включая тесты с игнорированием сбоев и пропущенные тесты:

```sh
tuist test --skip-quarantine
```

## Стресс-тестирование новых тестов {#stress-testing-new-tests}

Стресс-тест повторно запускает тесты, добавленные вашей веткой, по несколько раз в отдельном процессе и сообщает о тех, которые оказываются нестабильными. Вы увидите новый нестабильный тест в том же pull request, где он появился, а не спустя недели.


Тест-кейс считается новым, если он не запускался в CI за последние 90 дней на основной ветке проекта или на коммите, который уже вошёл в неё. При использовании очереди слияния тест-кейс, запущенный очередью, становится известным после того, как коммит очереди попадает в ветку, и остаётся новым, если очередь его отбрасывает. Коммиты сопоставляются через <.localized_link href="/guides/features/test-insights/xcode#git-history">историю Git</.localized_link>, которую Tuist собирает в CI.

### Включение {#enabling-stress-testing}

По умолчанию шлюз отключён. Задайте режим:

- **`report`**: предупреждает о каждом нестабильном тест-кейсе. Запуск завершается с собственным кодом возврата.
- **`enforce`**: нестабильный тест-кейс приводит к сбою запуска с тем же кодом выхода, что и при обычном падении теста.

Начните с `report` на пару недель, чтобы понять, что бы заблокировал `enforce`.


В обоих режимах <.localized_link href="/guides/features/selective-testing/generated-xcode-project">выборочное тестирование</.localized_link> не пропускает таргет теста с нестабильным новым тест-кейсом при следующем запуске. Таргет запускается снова, и гейт повторно проводит стресс-тестирование тест-кейса, пока он не пройдёт все свои повторные запуски.

Передайте это перед сквозными аргументами или установите `TUIST_TEST_STRESS_NEW_TESTS`, чтобы менять режим для каждого этапа CI:

```sh
tuist test --stress-new-tests report
```

### Сколько раз каждый тест перезапускается {#stress-reruns}

Зависит от того, сколько времени занял тест-кейс при первом проходе:

| Первый проход | Перезапуски |
| --- | --- |
| До 5 с | 10 |
| До 10 с | 5 |
| До 30 с | 3 |
| До 5 мин | 2 |
| Более 5 мин | Не перезапускается |

Проход останавливается после 200 тест-кейсов или 10 минут — в зависимости от того, что наступит раньше, и указывает, какой лимит был достигнут.


Повторные запуски используют то, что было собрано при первом проходе.

### Когда проверка не запускается {#when-the-gate-does-not-run}

- Первый прогон уже завершился с ошибкой. Сначала исправьте эти тесты.
- В проекте нет ветки по умолчанию, или в CI на ней ещё ничего не запускалось.
- Более 30% тест-кейсов проекта выглядят новыми. Повторный запуск такого количества займёт больше времени, чем это оправдано. Это нормально для проекта, который только начал отправлять отчёты в Tuist, или после переименования, при котором одновременно перемещается много тестов.


## Уведомления в Slack {#slack-notifications}

Получайте уведомления, когда тест становится нестабильным, настроив <.localized_link href="/guides/integrations/slack#flaky-test-alerts">оповещения о нестабильных тестах</.localized_link> в вашей интеграции со Slack.


## Запрос состояния нестабильных и изолированных тестов {#querying}

### CLI {#querying-cli}

Дерево команд `tuist test case` предоставляет всю информацию, которую Tuist отслеживает о тест-кейсе:

```sh
tuist test case list --flaky                       # only flaky test cases
tuist test case list --quarantined                 # only muted or skipped test cases
tuist test case show <test_case_id>                # detail: flakiness rate, last status, run counts
tuist test case events <test_case_id>              # audit log: marked_flaky, muted, skipped, ...
tuist test case run list <test_case_id>            # run history with status and duration
tuist test case run show <test_case_run_id>        # single run, including failure breakdown
```

Все эти команды поддерживают `--json` для использования в скриптах.

### REST API {#querying-rest-api}

Те же данные доступны по HTTP. См. [эндпоинты тест-кейсов](https://tuist.dev/api/docs#tag/test-cases) в справочнике API для получения полного списка маршрутов, фильтров и полей ответа. Чтобы изменить состояние тест-кейса (отметить или снять отметку о нестабильности, игнорировать, пропустить), отправьте запрос `PATCH /api/projects/{account_handle}/{project_handle}/tests/test-cases/{test_case_id}` с параметрами `is_flaky` или `state`. Это же изменение доступно через команду `tuist test case update` и инструмент MCP `update_test_case`.

