# Vincular pruebas de Jest con casos

> Cómo vincula @probara/jest-reporter cada prueba de Jest con un caso de prueba de Probara — IDs de caso en los títulos, probara.id(), claves de automatización y los casos que crea.

Cada resultado va a un caso de prueba de Probara. Una prueba que nombra su caso queda vinculada a él;
una prueba que no nombra ninguno se asocia por su clave de automatización, y su caso se crea la
primera vez que se reporta. Vincula las pruebas cuando sus casos ya existen en Probara (escritos a
mano o importados).

## Dos formas de nombrar un caso

| Forma                                                 | Ejemplo                                           | Cuándo                                           |
| ----------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------ |
| Un ID de caso en el título de una prueba o `describe` | `test('SHOP-12 pays with a card', ...)`           | La forma habitual; funciona también con omitidas |
| `probara.id()` en la prueba                           | `probara.id('SHOP-14')`, `probara.id(['A', 'B'])` | IDs que solo se conocen mientras corre la prueba |

```js
// tests/checkout.test.js
const { probara } = require('@probara/jest-reporter');

describe('checkout', () => {
  test('SHOP-12 pays with a card', () => {});

  describe('SHOP-13 vouchers', () => {
    test('pays with a voucher', () => {});
  });

  test('pays with a gift card', () => {
    probara.id('SHOP-14');
  });

  test('shows the total', () => {
    // No case named: matched by its key, created the first time.
  });
});
```

Probara recibe un resultado por prueba, cada uno con su caso, y la clave que tendría sin los IDs:

```json
[
  {
    "caseDisplayId": "SHOP-12",
    "automationKey": "tests/checkout.test.js > checkout pays with a card"
  },
  {
    "caseDisplayId": "SHOP-13",
    "automationKey": "tests/checkout.test.js > checkout vouchers pays with a voucher"
  },
  {
    "caseDisplayId": "SHOP-14",
    "automationKey": "tests/checkout.test.js > checkout pays with a gift card"
  },
  { "automationKey": "tests/checkout.test.js > checkout shows the total" }
]
```

- **Los IDs del título** son los IDs del proyecto al que se reporta (y de los de
  [`projects`](https://docs.probara.net/es/developers/ci-integrations/jest/sharding/#varios-proyectos-de-probara)) en el
  título de un `describe` o de una prueba, como `SHOP-12` o `SHOP_12`, en cualquier posición. Un ID
  en un `describe` vincula todas las pruebas que contiene. Se eliminan de la clave, así que añadir uno
  nunca cambia una clave. Un ID de un proyecto que el reporter no conoce queda en el título, como
  texto.
- **`probara.id()`** acepta un ID o una lista, y vincula el intento en curso. Una prueba omitida antes
  de ejecutarse (`test.skip`, un `describe` omitido, `test.todo`) nunca ejecuta su cuerpo:
  vincúlala con un ID en el título. La
  [selección de pruebas](https://docs.probara.net/es/developers/ci-integrations/jest/run-selection/) tampoco ve
  `probara.id()`: decide antes de que se ejecute la prueba.

Los IDs son el ID visible del caso: el ID del Proyecto, un guion y el número que muestra Probara
(`SHOP-12`). Un ID que Probara no conoce no se registra: el registro lo nombra como no encontrado
([solución de problemas](https://docs.probara.net/es/developers/ci-integrations/jest/troubleshooting/#resultados-no-registrados-unmatched)).

## Varios casos

Cuentan todas las fuentes: primero `probara.id()` (en el orden de las llamadas) y después los IDs de
los títulos, cada ID una vez. Una prueba vinculada a varios casos se envía una vez por caso, con la
misma clave, y sus archivos se suben a cada resultado:

```js
// tests/login.test.js
const { probara } = require('@probara/jest-reporter');

test('SHOP-21 logs in', () => {
  probara.id('SHOP-20');
});
```

```json
[
  { "caseDisplayId": "SHOP-20", "automationKey": "tests/login.test.js > logs in" },
  { "caseDisplayId": "SHOP-21", "automationKey": "tests/login.test.js > logs in" }
]
```

## Claves de automatización

Una prueba que no nombra ningún caso se asocia por su clave de automatización: la misma clave
encuentra el mismo caso en cada ejecución, y una clave nueva crea un caso nuevo. La clave es la que
`probara import junit` da a la prueba en el informe de jest-junit:

| Parte   | De dónde sale                                                                                             | Ejemplo                  |
| ------- | --------------------------------------------------------------------------------------------------------- | ------------------------ |
| Archivo | El archivo de prueba, relativo a `rootDir` (la ruta real del directorio en el que se ejecuta `jest`)      | `tests/checkout.test.js` |
| Nombre  | Los títulos de los `describe` y el de la prueba, unidos por espacios, como los nombra jest-junit; sin IDs | `checkout pays`          |

Así, `tests/checkout.test.js > checkout pays` es la clave de `test('pays')` dentro de
`describe('checkout')`. Con
[`keyIncludesFile: false`](https://docs.probara.net/es/developers/ci-integrations/jest/configuration/#keyincludesfile) se
omite el archivo (`checkout pays`), como en el informe de jest-junit sin su atributo de archivo. El
algoritmo de la clave es la
[clave de automatización v1](https://github.com/cynch-me/probara-sdk/blob/main/packages/core/README.md#the-automation-key-v1)
de `@probara/core`, congelada y compartida por todas las herramientas de Probara.

| Cambia la clave, y por tanto crea un caso nuevo                                  | No cambia la clave                                                       |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Renombrar una prueba, un `describe` o un archivo                                 | Añadir o quitar un ID de caso en un título                               |
| Mover un archivo                                                                 | `probara.title()` y `probara.suite()` (solo dan nombre a un caso creado) |
| Ejecutar `jest` desde otro directorio (define `rootDir` para mantener las rutas) | `probara.parameters()`                                                   |
| Cambiar `keyIncludesFile`                                                        | La versión de Jest, una entrada de `projects` de Jest, el CI             |

### Nombres tal como los escribe jest-junit

El nombre es el de jest-junit, con sus plantillas por defecto, así que una clave nunca depende de
cuál de las dos herramientas reportó la prueba:

- **Las filas de `test.each`** son pruebas propias, con sus valores en el nombre: cada fila es un
  caso. Una tabla cuyas filas dan el mismo nombre (sin marcador en el título) produce pruebas que
  comparten una clave: se registran en el mismo caso.
- **`$` en un título** se interpreta como lo hacen las plantillas de jest-junit: `$$` se convierte en
  `$`, y `$&` en el marcador que sustituyó. `costs $$5` tiene la clave `... costs $5`.
- **`{displayName}` en un título** se convierte en el nombre del proyecto de Jest que ejecuta la
  prueba, como lo rellena jest-junit
  ([proyectos de Jest](https://docs.probara.net/es/developers/ci-integrations/jest/sharding/#proyectos-de-jest)).
- **`›`** (con sus espacios) en un título lo divide en dos segmentos de la clave, igual que la
  importación JUnit divide los nombres de jest-junit.

```js
// tests/prices.test.js
describe('prices', () => {
  test.each([
    ['EUR', '€'],
    ['USD', '$'],
  ])('shows %s as %s', () => {});

  test('costs $$5 with a voucher', () => {});
});
```

```json
[
  { "automationKey": "tests/prices.test.js > prices shows EUR as €" },
  { "automationKey": "tests/prices.test.js > prices shows USD as $" },
  { "automationKey": "tests/prices.test.js > prices costs $5 with a voucher" }
]
```

Dos pruebas de un mismo archivo con el mismo nombre completo (los mismos títulos de `describe` y el
mismo título, o `a b` › `c` y `a` › `b c`) comparten una clave: Probara registra ambas en un caso, y
lo que dijeron sus llamadas `probara.*` se omite, con una advertencia, en lugar de atribuirlo a la
prueba equivocada
([solución de problemas](https://docs.probara.net/es/developers/ci-integrations/jest/troubleshooting/#una-prueba-perdió-sus-pasos-o-archivos)).

## Casos que faltan

Una prueba cuya clave no coincide con ningún caso crea uno, con el nombre de la prueba (sin IDs), bajo
`suiteUlid` (la raíz del proyecto por defecto), en una suite con el nombre de su archivo de prueba;
con `keyIncludesFile: false`, con el de su `describe` más externo, si lo tiene. Con
`createMissingCases: false` (`PROBARA_CREATE_MISSING_CASES=false`), una prueba así no registra nada y
aparece como no encontrada: solo los casos existentes reciben resultados.
[`probara.title()` y `probara.suite()`](https://docs.probara.net/es/developers/ci-integrations/jest/metadata/#título-y-suite)
eligen el nombre y la suite de un caso creado.

## Las mismas claves que `probara import junit`

Un proyecto que enviaba el informe de jest-junit con `probara import junit` puede pasar al reporter y
conservar cada caso: el reporter construye las mismas claves y lee los mismos IDs de los títulos.

| Informe de jest-junit                                     | Ajuste del reporter                       |
| --------------------------------------------------------- | ----------------------------------------- |
| Escrito con `JEST_JUNIT_ADD_FILE_ATTRIBUTE=true`          | Nada: `keyIncludesFile` está activado     |
| Escrito sin el atributo de archivo (su valor por defecto) | `keyIncludesFile: false`                  |
| Escrito con otras plantillas (`classNameTemplate`...)     | Claves distintas: vincula por IDs de caso |

Sigue ejecutando `jest` desde el mismo directorio que antes: el archivo de una clave es relativo a él.
La [guía de migración desde JUnit](https://docs.probara.net/es/developers/ci-integrations/jest/migrating/#desde-la-importación-junit)
tiene los pasos, cómo comparar las claves antes de cambiar, y qué registra el reporter de forma
distinta.

Relacionado: [Metadatos y enlaces](https://docs.probara.net/es/developers/ci-integrations/jest/metadata/) ·
[Sharding y proyectos](https://docs.probara.net/es/developers/ci-integrations/jest/sharding/) ·
[Actualizar el reporter](https://docs.probara.net/es/developers/ci-integrations/jest/migrating/#actualizar-el-reporter) ·
Fuente: [linking.md](https://github.com/cynch-me/probara-sdk/blob/main/packages/jest-reporter/docs/linking.md)