# Vincular pruebas de Cypress con casos

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

Cada resultado va a un caso de prueba de Probara. Una prueba que nombra su caso se vincula con é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 un `it` o un `describe` | `it('SHOP-12 pays with a card', ...)`             | La forma habitual; también con pruebas omitidas |
| `probara.id()` en la prueba o un hook    | `probara.id('SHOP-14')`, `probara.id(['A', 'B'])` | Sin tocar el título                             |

```js
// cypress/e2e/checkout.cy.js
describe('Checkout', () => {
  it('SHOP-12 pays with a card', () => {
    cy.get('.pay-card').click();
  });

  describe('SHOP-13 Vouchers', () => {
    it('pays with a voucher', () => {
      cy.get('.pay-voucher').click();
    });
  });

  it('pays with a gift card', () => {
    probara.id('SHOP-14');
    cy.get('.pay-gift').click();
  });

  it('shows the total', () => {
    // No case named: matched by its key, created the first time.
    cy.get('.total').should('be.visible');
  });
});
```

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": "cypress/e2e/checkout.cy.js > Checkout pays with a card"
  },
  {
    "caseDisplayId": "SHOP-13",
    "automationKey": "cypress/e2e/checkout.cy.js > Checkout Vouchers pays with a voucher"
  },
  {
    "caseDisplayId": "SHOP-14",
    "automationKey": "cypress/e2e/checkout.cy.js > Checkout pays with a gift card"
  },
  { "automationKey": "cypress/e2e/checkout.cy.js > Checkout shows the total" }
]
```

- **Los IDs en los títulos** son los IDs del proyecto reportado (y de
  [`projects`](https://docs.probara.net/es/developers/ci-integrations/cypress/sharding/#varios-proyectos-de-probara)) en el
  título de un `describe` o de un `it`. Un ID en un `describe` vincula todas las pruebas que contiene.
  Se quitan de la clave, así que añadir uno nunca cambia una clave. Un ID de un proyecto que el
  reporter no conoce, como `WEB-3` sin `projects: ['WEB']`, se queda en el título y en la clave como
  texto.
- **`probara.id()`** acepta un ID o una lista, y vincula la prueba en curso; en un `beforeEach`,
  vincula todas las pruebas del bloque. Necesita el plugin y el archivo de soporte. Una prueba omitida
  antes de ejecutarse (`it.skip`) 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/cypress/run-selection/) tampoco ve
  `probara.id()`: decide antes de que la prueba se ejecute.

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 asociado
([solución de problemas](https://docs.probara.net/es/developers/ci-integrations/cypress/troubleshooting/#resultados-no-registrados-unmatched)).
Varios IDs, en los títulos o en `probara.id()`, vinculan la prueba con varios casos, y la prueba se
registra una vez por caso.

## 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 del reporter `junit` de Cypress o de
cypress-junit:

```text
<ruta de la spec, relativa a la raíz del proyecto> > <el título completo de la prueba>
```

| Parte              | De dónde sale                                                                                                     | Ejemplo                  |
| ------------------ | ----------------------------------------------------------------------------------------------------------------- | ------------------------ |
| La ruta de la spec | Relativa a `rootDir` (el `projectRoot` de Cypress), con separadores `/`, mientras `keyIncludesFile` esté activado | `cypress/e2e/cart.cy.js` |
| El título completo | Los títulos de los `describe` y el del `it` unidos por un espacio, como un solo segmento, sin los IDs de caso     | `Cart Checkout pays`     |

```js
// cypress/e2e/cart.cy.js
describe('SHOP-12 Cart', () => {
  describe('Checkout', () => {
    it('pays by card', () => {
      cy.get('.pay').click();
    });
  });
});
```

```text
cypress/e2e/cart.cy.js > Cart Checkout pays by card
```

### Qué cambia una clave

| Qué                                         | Por qué                                                                     |
| ------------------------------------------- | --------------------------------------------------------------------------- |
| Renombrar una spec, un `describe` o un `it` | La ruta de la spec y los títulos son la clave                               |
| Mover una spec                              | Su ruta es la clave                                                         |
| Lanzar `cypress run` desde otro directorio  | La ruta es relativa al `projectRoot` de Cypress                             |
| Cambiar `keyIncludesFile` o `rootDir`       | Deciden si la ruta de la spec está en la clave, y respecto a qué se expresa |

Nada más llega a una clave: ni el navegador (un parámetro `browser` del resultado), ni el intento,
ni un parámetro, una etiqueta o un paso, ni el build de CI, la máquina, `--spec` o
`excludeSpecPattern`. Nombra los casos en los títulos antes de renombrar, para que las pruebas los
conserven.

### Trampas en Cypress

- **Dos pruebas con el mismo título completo son un solo caso.** Mocha permite
  `it('adds an item')` dos veces en un mismo `describe`, y `a b` › `c` junto a `a` › `b c` tiene el
  mismo título completo `a b c`. Ambas se registran en un caso, y lo que dijeron sus llamadas
  `probara.*` se omite en lugar de dárselo a la prueba equivocada. Da a cada prueba su propio título.
- **`it.only` deja fuera lo que no ejecuta.** Cypress quita las demás pruebas de su árbol antes de
  ejecutar nada, así que no se reportan en absoluto, ni siquiera como omitidas. Lo mismo vale para
  las specs que `--spec` deja fuera.
- **Un hook que falla es una prueba propia**, a la que Cypress, y también la importación, llama
  `"before each" hook for "…"`. Su clave es la que contiene un informe JUnit
  ([hooks](https://docs.probara.net/es/developers/ci-integrations/cypress/results-and-retries/#un-hook-que-falla)).
- **Una spec que Cypress no puede analizar** es un resultado llamado `Spec failed to run`
  ([specs que no se pueden ejecutar](https://docs.probara.net/es/developers/ci-integrations/cypress/results-and-retries/#una-spec-que-cypress-no-puede-ejecutar)).

## Casos que faltan

Una prueba cuya clave no coincide con ningún caso crea uno, con el nombre de la prueba (sin los
IDs), bajo `suiteUlid` (la raíz del proyecto por defecto), en una ruta de suites formada por el
archivo de la spec y los bloques `describe` que contienen la prueba:
`cypress/e2e/cart.cy.js › Cart › Checkout`. Una prueba fuera de cualquier `describe` queda solo en la
spec. Con `keyIncludesFile: false`, la spec sale también de la ruta de suites. Con
`createMissingCases: false` (`PROBARA_CREATE_MISSING_CASES=false`) una prueba así no registra nada y
se registra como no asociada: solo los casos existentes reciben resultados.
[`probara.title()` y `probara.suite()`](https://docs.probara.net/es/developers/ci-integrations/cypress/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 JUnit XML de Cypress 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.

| El informe JUnit                                                                 | Ajuste del reporter                   |
| -------------------------------------------------------------------------------- | ------------------------------------- |
| Escrito por el reporter `junit` de Cypress o cypress-junit, opciones por defecto | Nada: `keyIncludesFile` está activado |
| Escrito sin el atributo `file` de su suite raíz                                  | `keyIncludesFile: false`              |

La única diferencia visible es dónde queda un caso **creado**: el reporter lo pone bajo la spec y
sus bloques `describe`, la importación solo bajo la spec, porque un informe JUnit no puede separar los
títulos de los `describe` de un único título. Un caso existente nunca se mueve
([migrar desde la importación JUnit](https://docs.probara.net/es/developers/ci-integrations/cypress/migrating/#desde-la-importación-junit)).

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