# Vincular pruebas de Playwright con casos

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

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 busca por su clave de automatización, y su caso se crea la
primera vez que se envía. Vincula las pruebas por ID cuando sus casos ya existen en Probara,
escritos a mano o importados.

## Tres formas de nombrar un caso

| Forma                        | Ejemplo                                                                               | Cuándo                                                   |
| ---------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| Una anotación `probara_case` | `test('pays', { annotation: { type: 'probara_case', description: 'SHOP-12' } }, ...)` | La forma habitual; funciona también con pruebas omitidas |
| Un ID de caso en el título   | `test('SHOP-12 pays with a card', ...)`                                               | Rápida, y visible en todos los informes                  |
| `probara.id()` en la prueba  | `probara.id('SHOP-14')`                                                               | IDs que solo se conocen en tiempo de ejecución           |

```ts
// tests/checkout.spec.ts
import { test } from '@playwright/test';
import { probara } from '@probara/playwright-reporter';

test.describe('checkout', () => {
  test(
    'pays with a card',
    { annotation: { type: 'probara_case', description: 'SHOP-12' } },
    async () => {
      // ...
    },
  );

  test('SHOP-13 pays with a voucher', async () => {
    // ...
  });

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

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

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

```json
[
  {
    "caseDisplayId": "SHOP-12",
    "automationKey": "checkout.spec.ts > checkout > pays with a card",
    "title": "pays with a card"
  },
  {
    "caseDisplayId": "SHOP-13",
    "automationKey": "checkout.spec.ts > checkout > pays with a voucher",
    "title": "pays with a voucher"
  },
  {
    "caseDisplayId": "SHOP-14",
    "automationKey": "checkout.spec.ts > checkout > pays with a gift card"
  },
  { "automationKey": "checkout.spec.ts > checkout > shows the total" }
]
```

### Anotaciones

Una anotación acepta un ID o una lista separada por comas (`'SHOP-12, SHOP-13'`), y varias
anotaciones se suman. Desde Playwright 1.42 van en los detalles de la prueba; una prueba también
puede añadir una en tiempo de ejecución:

```ts
test.info().annotations.push({ type: 'probara_case', description: 'SHOP-12' });
```

### IDs de caso en los títulos

Un ID en el título es un ID del proyecto al que se envía (o de uno de los
[`projects`](https://docs.probara.net/es/developers/ci-integrations/playwright/sharding/#varios-proyectos-de-probara)) dentro
del título de un `describe` o de una prueba, escrito `SHOP-12` o `SHOP_12`, en cualquier parte del
título. Se quita del título y de la clave, así que añadir uno nunca cambia una clave. Un ID de un
proyecto que el reporter no conoce se queda en el título, como texto.

### `probara.id()`

`probara.id()` acepta un ID o una lista, y añade una anotación `probara_case` al intento en curso.
Una prueba que se omite antes de ejecutarse (`test.skip('title', ...)`, o un `describe` omitido)
nunca ejecuta su cuerpo: vincúlala con una anotación o con un ID en el título.

### Qué es un ID

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, y el registro lo nombra como sin
coincidencia
([solución de problemas](https://docs.probara.net/es/developers/ci-integrations/playwright/troubleshooting/#hay-resultados-que-no-se-registraron-sin-coincidencia)).

## Varios casos y varias fuentes

Todas las fuentes cuentan: primero las anotaciones (en orden, `probara.id()` entre ellas) 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 adjuntos se suben a cada resultado:

```ts
// tests/login.spec.ts
import { test } from '@playwright/test';

test(
  'SHOP-21 logs in',
  { annotation: { type: 'probara_case', description: 'SHOP-20, SHOP-21' } },
  async () => {
    // ...
  },
);
```

```json
[
  { "caseDisplayId": "SHOP-20", "automationKey": "login.spec.ts > logs in" },
  { "caseDisplayId": "SHOP-21", "automationKey": "login.spec.ts > logs in" }
]
```

## Claves de automatización

Una prueba que no nombra ningún caso se busca 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 se
construye con:

| Parte                  | De dónde sale                                                                       | Ejemplo            |
| ---------------------- | ----------------------------------------------------------------------------------- | ------------------ |
| Archivo                | El archivo de la prueba, relativo a `rootDir` (el de Playwright, por defecto)       | `checkout.spec.ts` |
| Ruta de títulos        | Los títulos de `describe` y después el de la prueba, sin los IDs de caso            | `checkout > pays`  |
| Proyecto de Playwright | No forma parte de la clave. Se envía con cada resultado como su parámetro `project` | `project=chromium` |

Así, `checkout.spec.ts > checkout > pays` es la clave de esa prueba en todos los proyectos. Los
proyectos comparten una clave, así que comparten un caso, con un resultado por cada ejecución de
proyecto. El proyecto viaja con cada resultado como su parámetro `project`, y un caso que declare un
parámetro `project` obtiene un caso de ejecución por proyecto. El proyecto es contexto: se muestra en el resultado y nunca se convierte en un parámetro de un caso que un reporte crea.

Las versiones anteriores del reporter ponían el proyecto en la clave. Este comportamiento necesita la versión del reporter que envía los parámetros aparte de la clave; un caso reportado con una clave anterior no coincide con ella.

El algoritmo es la clave de automatización v1 de
`@probara/core`, congelada y compartida por todas las herramientas de Probara.

| Cambia la clave (crea un caso nuevo)                                    | No cambia la clave                                                    |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------- |
| Renombrar una prueba, un `describe` o un archivo                        | Añadir o quitar un ID de caso                                         |
| Mover un archivo                                                        | `probara.title()` y `probara.suite()`                                 |
| Renombrar un proyecto de Playwright                                     | `probara.parameters()`                                                |
| Cambiar `rootDir`, o `testDir`, al que sigue el `rootDir` de Playwright | La versión de Playwright, el CI o el directorio desde el que ejecutas |

Para conservar un caso tras un cambio de nombre, vincula la prueba por ID. Para revisar las claves
antes de una refactorización, consulta
[comprobar qué se enviaría](https://docs.probara.net/es/developers/ci-integrations/playwright/troubleshooting/#comprobar-qué-se-enviaría).

## Casos que faltan

Una prueba cuya clave no coincide con ningún caso crea uno, con el nombre de la prueba, en una ruta
de suites construida a partir del archivo y de los títulos de `describe`, bajo `suiteUlid` (la raíz
del proyecto por defecto).
[`probara.title()` y `probara.suite()`](https://docs.probara.net/es/developers/ci-integrations/playwright/metadata/#título-y-suite)
eligen el nombre y la suite de un caso creado.

Con `createMissingCases: false` (`PROBARA_CREATE_MISSING_CASES=false`), una prueba así no registra
nada y aparece en el registro como sin coincidencia: solo los casos existentes reciben resultados.

## Las mismas claves que `probara import junit`

El reporter construye las claves que la [CLI de Probara](https://docs.probara.net/es/developers/cli/) asigna al reporter
JUnit de Playwright (`--reporter=junit`), y lee los mismos vínculos: las anotaciones `probara_case`
(que el reporter JUnit escribe como propiedades) y los IDs de caso en los títulos. Un proyecto que
importaba el JUnit XML de Playwright con `probara import junit` puede pasarse al reporter y
conservar cada caso; los pasos están en
[migrar desde `probara import junit`](https://docs.probara.net/es/developers/ci-integrations/playwright/migrating/#desde-probara-import-junit).

Siguiente: [nombra los casos que crea un informe](https://docs.probara.net/es/developers/ci-integrations/playwright/metadata/),
o envía a [varios proyectos](https://docs.probara.net/es/developers/ci-integrations/playwright/sharding/#varios-proyectos-de-probara).