# Proyecto de Xcode generado {#generated-xcode-project-flaky-tests}

> [!IMPORTANT]
> **Requisitos**
>
> - <.localized_link href="/guides/features/test-insights/xcode">Análisis de tests de Xcode</.localized_link> configurado (los esquemas autogenerados incluyen la postacción `tuist inspect test`; los esquemas personalizados deben añadirla).

Los tests inestables son tests que producen resultados diferentes (aprobado o fallido) cuando se ejecutan varias veces con el mismo código. Minan la confianza en tu suite de tests y hacen perder tiempo a los desarrolladores al investigar fallos falsos. Tuist detecta automáticamente los tests inestables y te ayuda a hacerles seguimiento a lo largo del tiempo.


![Página de tests inestables](/images/guides/features/test-insights/flaky-tests-page.png)

## Cómo funciona la detección de inestabilidad {#how-it-works}

Tuist detecta los tests inestables de dos formas:

### Reintentos de tests {#test-retries}

Cuando ejecutas tests con reintentos, Tuist analiza los resultados de cada intento. Si un test falla en algunos intentos pero pasa en otros, se marca como inestable.

Pasa `-retry-tests-on-failure` o `-test-iterations` a través de `tuist test`:

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

![Detalle del caso de test inestable](/images/guides/features/test-insights/flaky-test-case-detail.png)

### Detección entre ejecuciones {#cross-run-detection}

Incluso sin reintentos de tests, Tuist puede detectar tests inestables comparando los resultados entre distintas ejecuciones de CI con el mismo commit, esquema y destino indicado (nombre del dispositivo, plataforma y versión del sistema operativo). Si un test pasa en una ejecución de CI coincidente pero falla en otra, la ejecución fallida se marca como inestable. Esto funciona independientemente de qué resultado llegue primero.

El mismo test puede comportarse de forma consistentemente distinta según el esquema o el destino. Por ejemplo, pasar en iOS 26 y fallar en iOS 27 no indica inestabilidad. Los resultados de esquemas, dispositivos, plataformas o versiones del sistema operativo distintos no se marcan entre sí como inestables.

Las ejecuciones sin metadatos de destino, o que cubren varios destinos, solo se comparan entre sí, por lo que las diferencias de entorno entre ellas pueden seguir reportándose como inestabilidad. La detección basada en reintentos sigue aplicándose.

Esto es especialmente útil para detectar tests inestables que no fallan con suficiente consistencia como para ser capturados por los reintentos, pero aún así provocan fallos intermitentes en la CI.


## Gestión de tests inestables {#managing-flaky-tests}

### Limpieza automática {#automatic-clearing}

La detección y la limpieza se gestionan mediante una **alerta de automatización** en el proyecto. Cada proyecto incluye una automatización predeterminada llamada "Detección de tests inestables" cuyo *disparador* marca un test como inestable y cuya *recuperación* elimina la marca cuando el test ha superado el periodo de recuperación configurado (por defecto, **14 días**) sin volver a activarse. Edítala en **Configuración → Automatizaciones** para cambiar el periodo de recuperación, modificar las acciones de recuperación (por ejemplo, liberar también el test de la cuarentena) o desactivar por completo la recuperación para que los tests permanezcan marcados como inestables hasta que los limpies manualmente.

### Gestión manual {#manual-management}

También puedes marcar o desmarcar manualmente los tests como inestables desde la página de detalles del caso de test. Esto resulta útil cuando:
- Quieres reconocer un test inestable conocido mientras trabajas en su corrección
- Un test se marcó incorrectamente debido a problemas de infraestructura


## Poner en cuarentena los tests inestables {#quarantining}

La cuarentena aísla un test inestable para que no bloquee la CI mientras lo corriges. Por defecto es una **acción manual**: pones un test en cuarentena, lo liberas y cambias de modo desde la página de detalles del caso de test en el dashboard. También puedes vincularlo a una **alerta de automatización** en **Settings → Automations** para que el test se silencie automáticamente (o se omita) cuando supere un umbral de inestabilidad, y se libere cuando se recupere. Cada transición, manual o automática, queda registrada en el registro de auditoría del caso de test.

Por defecto, la recuperación espera hasta que la condición de activación deja de cumplirse, por lo que un test permanece en cuarentena hasta que sus ejecuciones inestables anteriores salen de la ventana de activación. Para recuperarlo antes, configura **Recover when** como **No new flaky runs**: el test se recupera una vez que transcurre la ventana de recuperación (días o ejecuciones) sin ninguna nueva ejecución inestable, cada nueva ejecución inestable reinicia esa espera y, tras la recuperación, solo una nueva ejecución inestable lo vuelve a poner en cuarentena.


Un test en cuarentena está en uno de estos dos modos:

- **Silenciado**: el test sigue ejecutándose, pero `tuist test` oculta el fallo. Los fallos siguen alimentando el detector de tests inestables, así que puedes seguir vigilando el test sin romper la compilación. Elige esta opción para un test que estés investigando activamente.
- **Omitido**: xcodebuild recibe `-skip-testing <identifier>`, por lo que el test nunca se inicia. No genera nuevos resultados y desaparece del panel de tests inestables hasta que lo vuelvas a habilitar. Elige esta opción cuando el test esté roto, sea lento o tan persistentemente inestable que ejecutarlo solo desperdicie minutos de CI.

### Por qué los tests en cuarentena pueden aparecer como aprobados {#quarantined-passing}

- Los **tests silenciados** siguen ejecutándose. Un test silenciado que falla se registra como **fallido** en la ejecución del caso de test y se marca como inestable; el estado por test no se sobrescribe. Lo que se sobrescribe es la **ejecución de tests completa**: si todos los casos de test que fallan en la ejecución están silenciados, la ejecución en su conjunto se informa como aprobada, de modo que los fallos silenciados no rompen la CI.
- Los **tests omitidos** no se ejecutan en absoluto, por lo que el panel sigue mostrando el estado de la última ejecución real del test. Esa instantánea puede tener semanas de antigüedad.


### Ejecutar tests {#running-tests}

`tuist test` respeta ambos modos automáticamente:

```sh
tuist test
```

Los tests omitidos se pasan a xcodebuild como `-skip-testing` y nunca se inician. Los tests silenciados se ejecutan con normalidad; si fallan, el fallo se oculta en el estado de la compilación resultante.

Para omitir por completo la cuarentena y ejecutar todo, incluidos los tests silenciados y omitidos:

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

## Someter a estrés los tests nuevos {#stress-testing-new-tests}

La puerta de estrés vuelve a ejecutar los casos de prueba que añade tu rama, varias veces cada uno en un proceso nuevo, e informa de aquellos que resultan inestables. Verás una nueva prueba inestable en la pull request que la introdujo, no semanas después.


Un caso de test se considera nuevo cuando no se ha ejecutado en CI en los últimos 90 días en la rama predeterminada del proyecto, o en un commit que ya se haya integrado en ella. Con una cola de merges, un caso de test que la cola haya ejecutado se conoce una vez que el commit de la cola se integra, y sigue siendo nuevo si la cola lo descarta. Los commits se emparejan a través del <.localized_link href="/guides/features/test-insights/xcode#git-history">historial de Git</.localized_link> que Tuist recopila en CI.

### Habilitarlo {#enabling-stress-testing}

La protección está desactivada de forma predeterminada. Establece un modo:

- **`report`**: advierte sobre cada caso de test inestable. La ejecución finaliza según su propio resultado.
- **`enforce`**: un caso de test inestable hace fallar la ejecución, con el mismo código de salida que un test fallido.

Comienza con `report` durante un par de semanas para ver qué habría bloqueado `enforce`.


En ambos modos, los <.localized_link href="/guides/features/selective-testing/generated-xcode-project">tests selectivos</.localized_link> no omiten un destino de test que tenga un caso de test nuevo e inestable en la siguiente ejecución. El destino se vuelve a ejecutar y la barrera somete a estrés el caso de test de nuevo, hasta que pasa todos sus reintentos.

Pásalo antes de los argumentos de paso directo, o establece `TUIST_TEST_STRESS_NEW_TESTS` para variar el modo según la línea de CI:

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

### Cuántas veces se vuelve a ejecutar cada test {#stress-reruns}

Depende de cuánto tardó el caso de test en la primera pasada:

| Primera pasada | Reejecuciones |
| --- | --- |
| Hasta 5 s | 10 |
| Hasta 10 s | 5 |
| Hasta 30 s | 3 |
| Hasta 5 min | 2 |
| Más de 5 min | No se reejecuta |

La pasada se detiene al alcanzar los 200 casos de test o los 10 minutos, lo que ocurra primero, e indica qué límite se ha alcanzado.


Los reintentos reutilizan lo que construyó la primera pasada.

### Cuando la puerta no se ejecuta {#when-the-gate-does-not-run}

- La primera pasada ya falló. Corrige esos tests primero.
- El proyecto no tiene una rama predeterminada, o aún no se ha ejecutado nada en CI sobre ella.
- Más del 30% de los casos de test del proyecto parecen nuevos. Volver a ejecutar tantos llevaría más tiempo del que vale la pena. Esto es habitual en un proyecto que acaba de empezar a enviar informes a Tuist, o después de un cambio de nombre que mueve muchos tests a la vez.


## Notificaciones de Slack {#slack-notifications}

Recibe notificaciones cuando un test se vuelva inestable configurando <.localized_link href="/guides/integrations/slack#flaky-test-alerts">alertas de tests inestables</.localized_link> en tu integración con Slack.


## Consulta del estado de tests inestables y en cuarentena {#querying}

### CLI {#querying-cli}

El árbol de comandos `tuist test case` expone toda la información que Tuist rastrea sobre un caso de test:

```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
```

Todos ellos aceptan `--json` para su uso en scripts.

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

Los mismos datos están disponibles a través de HTTP. Consulta los [endpoints de casos de test](https://tuist.dev/api/docs#tag/test-cases) en la referencia de la API para obtener la lista completa de rutas, filtros y campos de respuesta. Para cambiar el estado de un caso de test (marcar o desmarcar como inestable, silenciar, omitir), envía `PATCH /api/projects/{account_handle}/{project_handle}/tests/test-cases/{test_case_id}` con `is_flaky` o `state`. El mismo cambio está disponible como `tuist test case update` y como la herramienta MCP `update_test_case`.

