# Selección de pruebas en Vitest

> Ejecuta solo las pruebas de Vitest de una ejecución creada en Probara con runCasesOnly, cómo se asocian las pruebas a los casos de la ejecución, qué se sigue ejecutando, y qué pasa cuando la selección no es posible.

Una persona planifica una ejecución en Probara (los casos de una versión, de un plan de pruebas, los
que fallaron ayer) y el pipeline ejecuta exactamente esas pruebas. Con `runCasesOnly`, el reporter
lee los casos de la ejecución antes de que Vitest ejecute ningún archivo de prueba, Vitest ejecuta
solo las pruebas que pertenecen a alguno de ellos, y sus resultados van a esa ejecución, que queda
abierta.

## Camino rápido

1. En el job que ejecuta las pruebas de una ejecución, define `PROBARA_RUN_CASES_ONLY=true` y
   `PROBARA_RUN_ULID` con el ULID de la ejecución (en Probara: el menú **Acciones de la ejecución**
   de la ejecución › **Copiar ULID de la ejecución**). No va nada en la configuración de Vitest: el
   archivo de setup que el reporter añade a cada proyecto de Vitest se encarga de omitir las demás.
2. Revisa la ejecución en Probara: sus casos tienen los resultados, y la ejecución queda abierta
   para quien la planificó.

```text
$ PROBARA_RUN_CASES_ONLY=true PROBARA_RUN_ULID=01J9Z3K4M5N6P7Q8R9S0T1V2W3 npx vitest run
[probara] Ran only the tests of run 01J9Z3K4M5N6P7Q8R9S0T1V2W3: 2 of 3 tests match its cases; 1 skipped and not reported
[probara] Sending 2 results of 2 tests (2 passed, 0 failed, 0 skipped, 0 blocked)
[probara] Recorded 2 results (0 new cases, 0 unmatched) in R-1 (open): https://app.probara.net/projects/SHOP/runs/R-1
```

En GitHub Actions, un workflow que se inicia a mano con el ULID de la ejecución como input:

```yaml
on:
  workflow_dispatch:
    inputs:
      run_ulid:
        description: The ULID of the Probara run to run the tests of
        required: true

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: 22
      - run: npm ci
      - name: Run the tests of a Probara run
        run: npx vitest run
        env:
          PROBARA_API_TOKEN: ${{ secrets.PROBARA_API_TOKEN }}
          PROBARA_RUN_CASES_ONLY: 'true'
          PROBARA_RUN_ULID: ${{ inputs.run_ulid }}
```

Actívalo en cada job, con las variables: `runCasesOnly: true` en la configuración de Vitest lo
activa en todos los jobs, y un job sin ULID advierte entonces y ejecuta todas las pruebas.

## Qué pruebas pertenecen a la ejecución

Una prueba pertenece a la ejecución cuando se cumple una de estas condiciones, comprobadas para cada
prueba antes de que se ejecute:

| La prueba                                                                       | Ejemplo                                                    |
| ------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Su clave de automatización es la clave de uno de los casos de la ejecución      | Un caso que creó el reporter o `probara import junit`      |
| Su título o el de uno de sus `describe` nombra uno de los casos de la ejecución | `test('SHOP-12 adds an item')`, `describe('SHOP-12 cart')` |

- **`probara.id()` no cuenta**: se ejecuta en el cuerpo de la prueba, después de la selección.
  Nombra el caso en un título
  ([vincular](https://docs.probara.net/es/developers/ci-integrations/vitest/linking/)).
- **Las claves son las del reporter**: con el mismo
  [`keyIncludesFile`](https://docs.probara.net/es/developers/ci-integrations/vitest/linking/#sin-el-archivo) y el mismo
  `rootDir` que el informe que vinculó los casos. También cuentan los IDs en el título de los
  proyectos de
  [`projects`](https://docs.probara.net/es/developers/ci-integrations/vitest/sharding/#varios-proyectos-de-probara).
- **Un caso de la ejecución sin prueba** simplemente no recibe resultado: el registro solo cuenta
  las pruebas.

En el ejemplo de arriba, la ejecución tiene dos casos: `SHOP-12`, nombrado en el título de una
prueba del carrito, y `SHOP-30`, cuya clave es la de la prueba de inicio de sesión. La tercera
prueba no pertenece a ninguno, así que Vitest la omite, y solo se envían las otras dos:

```json
[
  { "caseDisplayId": "SHOP-12", "automationKey": "tests/cart.test.ts > cart > adds an item" },
  { "automationKey": "tests/login.test.ts > login > logs in with a valid password" }
]
```

## Qué se reporta

| Prueba                                                                                     | Se ejecuta | Se reporta                                      |
| ------------------------------------------------------------------------------------------ | ---------- | ----------------------------------------------- |
| Pertenece a la ejecución                                                                   | Sí         | Sí, en la ejecución, con cada intento           |
| Pertenece a la ejecución, pero es `test.skip`, `test.todo` o está en un `describe` omitido | No         | Sí, como omitida (un todo con la nota `Todo`)   |
| No pertenece a ningún caso de la ejecución                                                 | No         | No: el resumen de Vitest la cuenta como omitida |

Vitest sigue cargando todos los archivos de prueba. El archivo de setup omite una prueba que no
pertenece a ningún caso en un hook `beforeEach` que se ejecuta antes que los tuyos:

| De una prueba que no pertenece a ningún caso                                 | Se ejecuta                                      |
| ---------------------------------------------------------------------------- | ----------------------------------------------- |
| Sus hooks `beforeEach` y su cuerpo                                           | No                                              |
| Sus hooks `afterEach`                                                        | Sí                                              |
| Los hooks `beforeAll` y `afterAll` de su archivo y de sus bloques `describe` | Sí, aunque no se ejecute ninguna de sus pruebas |

Así que escribe un `afterEach` que funcione cuando su `beforeEach` no se ejecutó, o devuelve la
limpieza desde el propio `beforeEach`: Vitest solo ejecuta esa limpieza después de un `beforeEach`
que se ejecutó. Cuando cargar un archivo es costoso (una base de datos, un servidor), pasa también a
Vitest un filtro que lo deje fuera:

```bash
PROBARA_RUN_CASES_ONLY=true PROBARA_RUN_ULID=01J9Z3K4M5N6P7Q8R9S0T1V2W3 npx vitest run tests/cart
```

## Cuando no puede seleccionar

La selección nunca rompe la ejecución de pruebas: cuando no puede saber qué pruebas pertenecen a la
ejecución, todas las pruebas se ejecutan y se reportan, con una advertencia.

| Qué pasa                                                  | La advertencia                                                                                                                                             |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No hay `run.ulid` ni `PROBARA_RUN_ULID`                   | `runCasesOnly needs the run whose tests to run: set run.ulid or PROBARA_RUN_ULID. Every test runs and is reported`                                         |
| No se pueden leer los casos de la ejecución (404, 403...) | `runCasesOnly: could not read the cases of the run <ULID> (<why>). Every test runs and is reported`                                                        |
| Un proyecto de navegador (`browser.enabled`)              | `runCasesOnly does not apply in browser mode yet: the tests of project "<name>" run and are reported (first seen in the run; repeats are logged at debug)` |
| Un shard que escribe un blob para `--merge-reports`       | `runCasesOnly does not apply to a sharded run with the blob reporter: every test runs, and vitest --merge-reports reports them all`                        |
| Un proyecto al que el reporter no pudo añadir su setup    | `runCasesOnly needs the setup file in project "<name>": its tests run and are reported (first seen in the run; repeats are logged at debug)`               |
| Un proyecto que no pudo recibir los casos de la ejecución | `could not give project "<name>" the cases of the run (<why>): its tests all run and are reported`                                                         |
| Ninguna prueba coincide con ningún caso de la ejecución   | `No test matches the cases of the run <ULID>: every test was skipped, and none is reported`                                                                |

Con el envío desactivado (sin token, `enabled: false`), todas las pruebas se ejecutan y no se envía
nada. Si además hay un `resultsFile`, el reporter advierte de que no pudo leer los casos
`(reporting to Probara is off)`, y el archivo recibe todas las pruebas.

Los casos no se pueden leer, por ejemplo, cuando el token no puede leer esa ejecución:

```text
$ PROBARA_RUN_CASES_ONLY=true PROBARA_RUN_ULID=01J9Z3K4M5N6P7Q8R9S0T1V2W3 npx vitest run
[probara] runCasesOnly: could not read the cases of the run 01J9Z3K4M5N6P7Q8R9S0T1V2W3 (Probara answered 403 forbidden: <message from Probara>). Every test runs and is reported
[probara] Sending 3 results of 3 tests (3 passed, 0 failed, 0 skipped, 0 blocked)
[probara] Recorded 3 results (1 new case, 0 unmatched) in R-1 (open): https://app.probara.net/projects/SHOP/runs/R-1
```

Una ejecución cuyos casos no nombra ni encuentra ninguna prueba:

```text
$ PROBARA_RUN_CASES_ONLY=true PROBARA_RUN_ULID=01J9Z3K4M5N6P7Q8R9S0T1V2W3 npx vitest run
[probara] No test matches the cases of the run 01J9Z3K4M5N6P7Q8R9S0T1V2W3: every test was skipped, and none is reported
```

Entonces no se envía nada, y la ejecución queda como estaba: comprueba que el ULID es el de la
ejecución que querías.

## Configuraciones

- **Proyectos de Vitest**: cada proyecto recibe los casos de la ejecución, y la línea `Ran only`
  cuenta las pruebas de todos ellos. Un proyecto de navegador es la excepción de arriba: todas sus
  pruebas se ejecutan y se reportan
  ([modo navegador](https://docs.probara.net/es/developers/ci-integrations/vitest/browser-mode/#aún-no-disponible)).
- **Shards** (`--shard`) sin el reporter `blob`: cada shard lee los casos de la ejecución y ejecuta
  su parte de las pruebas seleccionadas
  ([patrón 2](https://docs.probara.net/es/developers/ci-integrations/vitest/sharding/#patrón-2-crea-la-ejecución-reporta-desde-cada-shard-y-ciérrala)).
- **Shards que escriben un blob**: la selección no se aplica, porque la ejecución de
  `vitest --merge-reports` reportaría también las pruebas omitidas. Todas las pruebas se ejecutan,
  y la fusión las reporta todas
  ([sharding](https://docs.probara.net/es/developers/ci-integrations/vitest/sharding/#selección-de-pruebas)).
- **Modo watch**: los casos de la ejecución se vuelven a leer antes de cada nueva ejecución de las
  pruebas, así que un caso que se añade a la ejecución en Probara selecciona su prueba a partir de
  la siguiente ([modo watch](https://docs.probara.net/es/developers/ci-integrations/vitest/configuration/#modo-watch)).
- **Una petición más**: leer los casos es un `GET` antes de que empiecen las pruebas, 200 casos por
  página. Es la única lectura que puede hacer un token de aplicación
  ([listar las claves de casos de una ejecución](https://docs.probara.net/es/developers/api/run-cases/#listar-las-claves-de-casos-de-una-ejecución)).

Relacionado: [Configuración](https://docs.probara.net/es/developers/ci-integrations/vitest/configuration/#runcasesonly) ·
[Una ejecución existente](https://docs.probara.net/es/developers/ci-integrations/vitest/results-and-retries/#una-ejecución-existente) ·
[Solución de problemas](https://docs.probara.net/es/developers/ci-integrations/vitest/troubleshooting/#la-selección-ejecutó-todas-las-pruebas) ·
Fuente: [run-selection.md](https://github.com/cynch-me/probara-sdk/blob/main/packages/vitest-reporter/docs/run-selection.md)