# Informes desde CI con Cypress

> Crea el token de aplicación con el que se autentica el reporter de Probara para Cypress, regístralo en tu configuración de Cypress y consulta qué envía.

La aplicación **Cypress** envía a Probara los resultados de tus pruebas de Cypress desde cualquier
pipeline de CI, con el reporter de Probara para Cypress. Cada ejecución de Cypress se convierte en
una ejecución automatizada con sus resultados, los casos de prueba que nombra y sus adjuntos.

El reporter se autentica con un **token de aplicación**: un token que pertenece a la organización,
no a una persona. No ocupa ningún puesto y sigue funcionando cuando la persona que lo creó se va.
Esta guía cubre la tarjeta en Probara y la configuración; la
[documentación del reporter](https://docs.probara.net/es/developers/ci-integrations/cypress/) cubre cada
[opción del reporter](https://docs.probara.net/es/developers/ci-integrations/cypress/configuration/) y los helpers de prueba.

## Antes de empezar

| Necesitas                                                    | Por qué                                                                                                                                                |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Un plan de pago (**Pro** o **Enterprise**, o una prueba Pro) | El envío de resultados desde CI no forma parte del plan Free. En Free, su diálogo muestra **Ver planes** en lugar de **Crear un token de aplicación**. |
| Un **propietario** o **administrador** de Probara            | Solo los propietarios y administradores pueden crear y gestionar tokens de aplicación. Los demás miembros ven la tarjeta sin sus tokens.               |
| Un proyecto de Cypress que se ejecuta en CI                  | El reporter se ejecuta con tus specs, en el mismo comando `npx cypress run`.                                                                           |

## Configurarla

1. En **Workspace › Integraciones**, selecciona la tarjeta **Cypress**. El diálogo muestra qué puede
   hacer la aplicación y enlaza a esta guía.
2. Abre la pestaña **Tokens de acceso** y selecciona **Crear un token de aplicación**.
3. Escribe un **Nombre del token** y selecciona **Crear token**. Ponle el nombre de lo que lo usa —
   el repositorio o el pipeline — para saber después cuál revocar.
4. Selecciona **Copiar token** en **Copia tu nuevo token**. Es la única vez que Probara lo muestra:
   guárdalo en tu CI como un secreto llamado `PROBARA_API_TOKEN` antes de seleccionar **Listo**.
5. Instala el reporter en tu proyecto de Cypress:

   ```bash
   npm install --save-dev @probara/cypress-reporter
   ```

6. Añádelo a `cypress.config.js` como el reporter de `e2e` y dale el helper `setupNodeEvents`,
   sustituyendo `<PROJECT_CODE>` por el ID del Proyecto, por ejemplo `SHOP`:

   ```js
   // cypress.config.js
   const { defineConfig } = require('cypress');
   const { probaraNodeEvents } = require('@probara/cypress-reporter/setup');

   module.exports = defineConfig({
     e2e: {
       reporter: '@probara/cypress-reporter',
       reporterOptions: { projectId: '<PROJECT_CODE>' },
       setupNodeEvents(on, config) {
         return probaraNodeEvents(on, config);
       },
     },
   });
   ```

7. Importa una sola vez el archivo de soporte del reporter, al principio de
   `cypress/support/e2e.js`, para que cualquier spec pueda usar sus helpers de prueba:

   ```js
   // cypress/support/e2e.js
   import '@probara/cypress-reporter/support';
   ```

8. Pasa el secreto a tus pruebas como la variable de entorno `PROBARA_API_TOKEN` y ejecútalas. Por
   ejemplo, en GitHub Actions:

   ```yaml
   - name: Run Cypress tests
     run: npx cypress run
     env:
       PROBARA_API_TOKEN: ${{ secrets.PROBARA_API_TOKEN }}
   ```

El token nunca va en `cypress.config.js`: el reporter lo lee del entorno. La tarjeta de la página de
Integraciones muestra cuántos tokens activos tiene la aplicación.

## Qué envía el reporter

| Qué                                 | Cómo lo registra Probara                                                                                                                                                                                                                                                                     |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Resultados                          | Un resultado por intento: cada reintento de Cypress de una prueba envía su propio resultado, en orden, y el caso de la ejecución conserva el último. Cada intento queda en el historial del caso.                                                                                            |
| Pruebas omitidas                    | Las pruebas omitidas, incluida una que la propia spec omite con `it.skip`, se registran como omitidas.                                                                                                                                                                                       |
| Errores                             | El error de un intento fallido, en las notas de su resultado.                                                                                                                                                                                                                                |
| Pasos                               | Los pasos que ejecutó un intento con `probara.step()`, como un árbol con su estado, su duración y su error, debajo del resultado.                                                                                                                                                            |
| Adjuntos                            | Los archivos que adjuntó un intento con `probara.attach()`, en su resultado — o en el paso en el que se adjuntaron — y la captura de pantalla de cada prueba fallida que el reporter adjunta por defecto.                                                                                    |
| Enlaces                             | Los enlaces que añadió un intento con `probara.link()`, junto al resultado. Las incidencias que nombró con `probara.issue()` solo se convierten en enlaces cuando la opción del reporter `issueUrlTemplate`, una URL con `%s` donde va el id de la incidencia, convierte sus ids en enlaces. |
| Parámetros                          | El navegador en el que se ejecutó la spec, por ejemplo `chrome`, como parámetro del resultado. Selecciona un caso de ejecución solo cuando el caso declara un parámetro `browser`; si no, se muestra solo con el resultado, como contexto.                                                   |
| Casos de prueba nuevos              | Una prueba sin caso crea uno, en una suite con el nombre de su spec, bajo los bloques `describe` que la envuelven.                                                                                                                                                                           |
| Casos de prueba existentes          | Un caso archivado al que la prueba reporta se restaura. Un caso encontrado por su clave de automatización se mueve a la suite en la que está ahora la prueba; un caso vinculado por su ID conserva su suite. Su título, sus pasos y sus campos nunca cambian.                                |
| Responsables de resultados fallidos | Con la opción `assignFailedTo` del reporter, un resultado fallido se asigna por turnos a las personas que nombra — solo cuando su caso de la ejecución aún no tiene responsable, y solo a miembros que pueden trabajar en el proyecto. Un responsable existente nunca se reemplaza.          |

Un campo o una opción que Probara no conoce, o que se elimina mientras se procesa el informe, se
omite y se devuelve como advertencia, nunca como un error: el informe registra igualmente cada
resultado. Un campo con el valor vacío se omite sin advertencia. Un correo de `assignFailedTo` que no
corresponde a ningún miembro que pueda trabajar en el proyecto también se omite, con una advertencia
que solo dice cuántos se omitieron. Los helpers están disponibles dentro de una spec `cypress`:

```js
it('adds an item to the cart', () => {
  probara.step('open the product page', () => {
    cy.visit('/products/boots');
  });
  probara.attach({ name: 'cart', path: 'reports/cart.json' });
  probara.link('https://shop.example.com/cart', 'Cart page');
});
```

## Los mismos casos que una importación JUnit

Si ya envías los resultados de Cypress con `probara import junit` sobre el informe de `cypress-junit`,
el reporter encuentra los mismos casos de prueba: para la misma suite, sus claves de automatización
son iguales a las de esa importación — la ruta de la spec relativa a la raíz del proyecto más el
título completo de la prueba. Por eso, al pasar al reporter cada prueba sigue vinculada a su caso y
a su historial. Vale la pena conocer una diferencia: el reporter envía **cada intento**, mientras que
la importación conserva solo el último.

## Ejecutar solo las pruebas de una ejecución

Para ejecutar solo las pruebas de una ejecución creada en Probara, añade la opción del reporter
`runCasesOnly` a los `reporterOptions` de `cypress.config.js`:

```js
// cypress.config.js
const { defineConfig } = require('cypress');
const { probaraNodeEvents } = require('@probara/cypress-reporter/setup');

module.exports = defineConfig({
  e2e: {
    reporter: '@probara/cypress-reporter',
    reporterOptions: { projectId: '<PROJECT_CODE>', runCasesOnly: true },
    setupNodeEvents(on, config) {
      return probaraNodeEvents(on, config);
    },
  },
});
```

Después, solo en el job que ejecuta las pruebas de esa ejecución, define `PROBARA_RUN_ULID` con el
ULID de la ejecución. Por ejemplo, en un workflow de GitHub Actions que inicias a mano con un input
`run_ulid`:

```yaml
- name: Run the tests of a Probara run
  run: npx cypress run
  env:
    PROBARA_API_TOKEN: ${{ secrets.PROBARA_API_TOKEN }}
    PROBARA_RUN_ULID: ${{ inputs.run_ulid }}
```

El reporter envía los resultados a esa ejecución y la deja abierta.

Para obtener el ULID, abre la ejecución, selecciona **Acciones de la ejecución** (el menú de la
cabecera de la ejecución) y elige **Copiar ULID de la ejecución**; la misma opción está en el menú de
cada ejecución de la lista de ejecuciones. La opción activa la misma selección en cada ejecución de
specs: mientras reporta, cada job sin ULID muestra entonces una advertencia y ejecuta y envía todas
las pruebas.

Antes de que se ejecuten las specs, el reporter lee los casos de la ejecución. Una prueba pertenece
a la ejecución cuando su clave de automatización es la de uno de los casos de la ejecución, o cuando
su título o uno de sus bloques `describe` nombra uno de los casos de la ejecución, por ejemplo
`SHOP-12`. Una llamada a `probara.id()` no cuenta: se ejecuta con la prueba, después de la
selección. Leer las claves de casos es la única lectura que puede hacer un token de aplicación.

Una prueba que la ejecución no incluye se omite: no se ejecuta y no se envía. Su archivo de spec se
carga igualmente, así que el código de nivel superior del archivo sí se ejecuta. Cuando el archivo
de soporte no está en `cypress/support/e2e.js`, el reporter no puede omitir pruebas: se ejecutan y
se envían todas, con una advertencia. La
[referencia de la selección de pruebas](https://docs.probara.net/es/developers/ci-integrations/cypress/run-selection/)
cubre las reglas de coincidencia y cada alternativa.

Para enviar varios jobs a una misma ejecución, créala primero con `probara run create`, pasa su
ULID a cada job en `PROBARA_RUN_ULID` y ciérrala al final con `probara run close`. En GitHub Actions los
jobs de un mismo workflow ya comparten una ejecución: los jobs en paralelo definen
`PROBARA_CLOSE_RUN: false`, y un job final ejecuta `probara run close`
([jobs en paralelo](https://docs.probara.net/es/developers/ci-integrations/cypress/ci-providers/#jobs-en-paralelo-una-ejecución-cerrada-por-el-job-final)).
La
[CLI](https://docs.probara.net/es/developers/cli/) también puede reenviar los resultados que un reporter guardó cuando no
pudo enviar un informe, con `probara import results`.

## Gestionar los tokens

En **Tokens de aplicación**, la pestaña **Tokens de acceso** lista cada token activo con quién lo
creó (o **Creado por un usuario eliminado**), cuándo y cuándo se usó por última vez (**Nunca** hasta
su primer informe).

Selecciona **Revocar** en un token, y confírmalo, cuando pueda haberse filtrado o cuando alguien que
podía leerlo deje tu equipo: los pipelines que lo usan dejan de enviar resultados al momento, y no se
puede deshacer. Crea antes un token nuevo para ellos. Como un token de aplicación sobrevive a la
persona que lo creó, rotarlo es decisión tuya: Probara nunca lo revoca por su cuenta.

## Qué puede hacer un token de aplicación

Solo lo que hace el reporter: crear ejecuciones automatizadas, enviar informes (que pueden crear los
casos de prueba y las suites que nombran), añadir adjuntos a sus resultados, cerrar ejecuciones y
leer las claves de casos de una ejecución. No puede leer nada más, no puede eliminar adjuntos y no
sirve para [Probara MCP](https://docs.probara.net/es/developers/mcp/) ni para ninguna otra llamada a la API. Para scripts y
otros clientes de la API, usa un [token API](https://docs.probara.net/es/developers/authentication/) personal.

Las ejecuciones, las entradas de actividad y los adjuntos que creó un token de aplicación muestran el
logotipo y el nombre de la aplicación junto al nombre del token — por ejemplo **Cypress · smoke-ci** —
en la lista de ejecuciones, los resúmenes de la ejecución y del hito, la
[actividad del workspace](https://docs.probara.net/es/guides/workspace/activity/) y la lista de adjuntos.

## Cuando cambia el plan

Si tu organización pasa al plan Free, sus tokens de aplicación se conservan pero Probara los rechaza,
así que los pipelines dejan de enviar resultados; su diálogo lo indica y ofrece **Ver planes**. Aún
puedes ver y revocar los tokens. Vuelven a funcionar en cuanto la organización vuelve a un plan de
pago, sin nada que configurar de nuevo. Las ejecuciones manuales no se ven afectadas.

## Siguiente paso

- [Documentación del reporter](https://docs.probara.net/es/developers/ci-integrations/cypress/) —
  [opciones](https://docs.probara.net/es/developers/ci-integrations/cypress/configuration/),
  [helpers de prueba](https://docs.probara.net/es/developers/ci-integrations/cypress/metadata/), pasos y capturas, y
  [selección de pruebas](https://docs.probara.net/es/developers/ci-integrations/cypress/run-selection/).
- [Integraciones de CI](https://docs.probara.net/es/developers/ci-integrations/) — cómo se compara el reporter de Cypress
  con la [CLI](https://docs.probara.net/es/developers/cli/) y los reporters de
  [Playwright](https://docs.probara.net/es/guides/integrations/playwright/) y
  [Jest](https://docs.probara.net/es/guides/integrations/jest/).
- [API de casos de una ejecución](https://docs.probara.net/es/developers/api/run-cases/#listar-las-claves-de-casos-de-una-ejecución)
  — las claves de casos que lee el reporter para ejecutar solo las pruebas de una ejecución.
- [API de reportes](https://docs.probara.net/es/developers/api-reference/#reportes-de-ci) — el endpoint al que llama el
  reporter, para tus propias herramientas.