# Configuración del reporter de Cypress

> Los tres registros de @probara/cypress-reporter, cada opción con su variable de entorno, su tipo y su valor por defecto, cómo se combinan, la red, y por qué cypress open no reporta nada.

Cada ajuste de `@probara/cypress-reporter` es una opción del reporter en la configuración de
Cypress (`reporterOptions`), y la mayoría tiene también una variable de entorno `PROBARA_*`. Guarda
el token en el entorno, el proyecto en la configuración (o en el entorno), y define el resto donde
mejor encaje en tu pipeline.

## Camino rápido

1. Crea un token de aplicación desde la tarjeta **Cypress** en **Workspace › Integraciones**
   ([primeros pasos](https://docs.probara.net/es/developers/ci-integrations/cypress/#1-crea-un-token-de-aplicación)) y
   guárdalo como un secreto de CI llamado `PROBARA_API_TOKEN`.
2. Define el ID del Proyecto: `projectId` en `reporterOptions`, o `PROBARA_PROJECT`. Un ID del
   Proyecto es una letra mayúscula y después mayúsculas o dígitos (`SHOP`, `E2E`): cualquier otro
   valor desactiva el envío con un error.
3. Registra el reporter, el plugin y el archivo de soporte ([registro](#registro)). Todo lo demás
   tiene un valor por defecto. La ejecución recibe el nombre del build de CI, y su rama, su commit y
   la URL del build llegan solos desde el CI.

No pongas el token en la configuración de Cypress: la configuración se sube al repositorio.
`apiToken` existe para el código que lee el token de su propio almacén de secretos.

## Registro

El reporter se registra en tres lugares, cada uno con su función:

```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: 'SHOP' },
    setupNodeEvents(on, config) {
      return probaraNodeEvents(on, config);
    },
  },
});
```

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

| Registro                                                    | Qué es                                                  | Qué activa                                                                                               |
| ----------------------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `reporter` y `reporterOptions`                              | El reporter de Mocha que Cypress construye en cada spec | Cada evento de prueba: un resultado por intento, las claves, las capturas de cada intento                |
| `setupNodeEvents` (`@probara/cypress-reporter/setup`)       | El plugin, en el proceso que carga la configuración     | La ejecución de Probara (creada y cerrada al final), las capturas y el vídeo, el parámetro del navegador |
| El archivo de soporte (`@probara/cypress-reporter/support`) | El lado del navegador, junto a tus specs                | Los helpers `probara.*`, `captureOutput` y la selección de pruebas                                       |

El plugin lee los mismos `reporterOptions` que Cypress entrega al reporter, así que no necesita
ajustes propios. Devuelve desde `setupNodeEvents` la configuración que devuelve él, como hace
`probaraNodeEvents(on, config)`: esa configuración es la vía por la que sus ajustes llegan al
navegador.

| Qué falta             | Qué pasa                                                                                                                                                                                           |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nada                  | Todo: una ejecución para todo el `cypress run`, cerrada al final, con las capturas de cada intento fallido, el vídeo y los helpers `probara.*`                                                     |
| El plugin             | Se sigue enviando cada resultado, pero en **una ejecución por spec**, cada una cerrada al terminar su spec. Sin capturas, sin vídeo y sin helpers `probara.*`. Una advertencia nombra lo que falta |
| El archivo de soporte | Resultados, capturas y vídeo como siempre. Cada llamada `probara.*` no hace nada, `captureOutput` no captura nada y la selección de pruebas no omite nada                                          |
| El reporter           | No se reporta nada: Cypress nunca construye este reporter                                                                                                                                          |

### Con otros plugins

Cypress guarda **un** manejador por evento: cuando dos plugins registran `after:run` (o
`before:run`, `before:spec`, `after:spec`, `after:screenshot`) con el mismo `on`, solo se ejecuta el
último, y el otro se descarta sin aviso
([cypress#22428](https://github.com/cypress-io/cypress/issues/22428)). Las tareas son la excepción:
Cypress las combina. Cuando otro plugin registra alguno de esos eventos, como
[cypress-split](https://github.com/bahmutov/cypress-split), pasa a cada plugin el `on` de
[cypress-on-fix](https://github.com/bahmutov/cypress-on-fix), que ejecuta todos los manejadores en el
orden en que se registraron:

```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: 'SHOP' },
    setupNodeEvents(cypressOn, config) {
      const on = require('cypress-on-fix')(cypressOn);
      require('cypress-split')(on, config);
      probaraNodeEvents(on, config);
      on('after:run', () => {
        // Your own handler: it runs too.
      });
      return config;
    },
  },
});
```

`probaraNodeEvents` añade sus ajustes a `config` por sí mismo, así que devolver `config` al final los
conserva, junto con lo que cambiaron los demás plugins. Qué cuesta cada evento perdido está en
[solución de problemas](https://docs.probara.net/es/developers/ci-integrations/cypress/troubleshooting/#otro-plugin-dejó-de-funcionar-o-este).

### Con `cypress-multi-reporters`

Cypress ejecuta un solo reporter, así que este sustituye las líneas por prueba del reporter `spec`
por defecto. Para conservarlas, o para escribir JUnit XML a la vez, registra
[`cypress-multi-reporters`](https://github.com/YOU54F/cypress-plugins/tree/master/cypress-multi-reporters)
y pon las opciones de este reporter en `probaraCypressReporterReporterOptions`, la clave que construye
a partir del nombre del reporter. El plugin las lee del mismo sitio:

```js
// cypress.config.js
module.exports = defineConfig({
  e2e: {
    reporter: 'cypress-multi-reporters',
    reporterOptions: {
      reporterEnabled: 'spec, @probara/cypress-reporter',
      probaraCypressReporterReporterOptions: { projectId: 'SHOP' },
    },
    setupNodeEvents(on, config) {
      return probaraNodeEvents(on, config);
    },
  },
});
```

## Fuentes y precedencia

Gana la primera fuente que define un valor:

| Orden | Fuente                                                 | Ejemplo                                           |
| ----- | ------------------------------------------------------ | ------------------------------------------------- |
| 1     | Una opción del reporter en la configuración de Cypress | `{ run: { name: 'Release 2.4' } }`                |
| 2     | Una variable `PROBARA_*`                               | `PROBARA_RUN_NAME=Nightly`                        |
| 3     | La detección del CI                                    | `CI #42` a partir del workflow y el número de run |
| 4     | El valor por defecto                                   | `Automated run 2026-09-29 14:05 UTC`              |

- Una opción con valor `undefined` nunca oculta su variable, y una variable vacía cuenta como no
  definida. Para que una variable pueda sustituir a una opción, omite la opción (o pasa
  `process.env.X ?? default`).
- Los booleanos aceptan `true`, `1`, `yes`, `on` y `false`, `0`, `no`, `off`. Las listas se separan
  con comas en las variables (`PROBARA_RUN_TAGS=nightly,smoke`).
- La detección del CI solo rellena el nombre de la ejecución y su origen (rama, commit, URL del
  build, y en GitHub Actions la ejecución del workflow que agrupa los jobs en paralelo). Lo que rellena cada CI está en
  [Proveedores de CI](https://docs.probara.net/es/developers/ci-integrations/cypress/ci-providers/).

Las opciones y las variables se pueden combinar. Esta configuración define el proyecto y las
etiquetas:

```js
reporterOptions: { projectId: 'SHOP', run: { tags: ['e2e', 'nightly'] } },
```

y el pipeline añade el entorno y el nombre de la ejecución:

```bash
PROBARA_ENVIRONMENT=staging PROBARA_RUN_NAME=Nightly npx cypress run
```

## Opciones

| Opción                   | Variable                       | Tipo                                    | Valor por defecto                                                  | Qué hace                                                                                                                                                          |
| ------------------------ | ------------------------------ | --------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`                | `PROBARA_ENABLED`              | `boolean`                               | activado                                                           | `false` desactiva el envío: no se envía ni se registra nada                                                                                                       |
| `apiToken`               | `PROBARA_API_TOKEN`            | `string`                                | ninguno (obligatorio)                                              | El token de aplicación. Guárdalo en el entorno                                                                                                                    |
| `projectId`              | `PROBARA_PROJECT`              | `string`                                | ninguno (obligatorio)                                              | El ID del Proyecto (mayúsculas y dígitos), por ejemplo `SHOP`                                                                                                     |
| `baseUrl`                | `PROBARA_BASE_URL`             | `string`                                | `https://app.probara.net`                                          | El Probara al que se envía ([autoalojado](#probara-autoalojado))                                                                                                  |
| `run.ulid`               | `PROBARA_RUN_ULID`             | `string`                                | ninguno: una ejecución nueva                                       | Reportar en una ejecución existente ([una ejecución existente](https://docs.probara.net/es/developers/ci-integrations/cypress/results-and-retries/#una-ejecución-existente))              |
| `run.name`               | `PROBARA_RUN_NAME`             | `string`                                | el nombre del build de CI, si no `Automated run <date> <time> UTC` | Nombre de una ejecución nueva                                                                                                                                     |
| `run.description`        | `PROBARA_RUN_DESCRIPTION`      | `string`                                | ninguno                                                            | Descripción de una ejecución nueva                                                                                                                                |
| `run.environment`        | `PROBARA_ENVIRONMENT`          | `string`                                | ninguno                                                            | Entorno de una ejecución nueva por nombre, creado si no coincide ninguno                                                                                          |
| `run.environmentId`      | `PROBARA_ENVIRONMENT_ID`       | `string`                                | ninguno                                                            | Entorno de una ejecución nueva por ULID                                                                                                                           |
| `run.milestone`          | `PROBARA_MILESTONE`            | `string`                                | ninguno                                                            | Hito de una ejecución nueva por ID visible (`M-3`) o nombre                                                                                                       |
| `run.milestoneId`        | `PROBARA_MILESTONE_ID`         | `string`                                | ninguno                                                            | Hito de una ejecución nueva por ULID                                                                                                                              |
| `run.plan`               | `PROBARA_PLAN`                 | `string`                                | ninguno                                                            | Plan de pruebas de una ejecución nueva por ID visible (`PLAN-2`) o nombre: la ejecución empieza con sus casos                                                     |
| `run.configurations`     | `PROBARA_CONFIGURATIONS`       | `{ group, name }[]`                     | ninguno                                                            | Configuraciones de una ejecución nueva por nombre (`Browser=Chrome,OS=Linux`), cada grupo una vez                                                                 |
| `run.configurationUlids` | `PROBARA_CONFIGURATION_ULIDS`  | `string[]`                              | ninguno                                                            | Configuraciones de una ejecución nueva por ULID                                                                                                                   |
| `run.tags`               | `PROBARA_RUN_TAGS`             | `string[]`                              | ninguno                                                            | Etiquetas de una ejecución nueva                                                                                                                                  |
| `run.ulids`              | `PROBARA_RUN_ULIDS`            | `Record<string, string>`                | ninguno                                                            | La ejecución que se reutiliza en cada proyecto (`WEB=<ulid>,API=<ulid>`)                                                                                          |
| `projects`               | `PROBARA_PROJECTS`             | `string[]`                              | ninguno                                                            | Otros proyectos a los que pueden ir los resultados (`WEB,API`) ([varios proyectos](https://docs.probara.net/es/developers/ci-integrations/cypress/sharding/#varios-proyectos-de-probara)) |
| `source`                 | —                              | `false \| objeto (campos GitHub abajo)` | detectado del CI                                                   | `false` no envía origen; un objeto sustituye los campos detectados uno a uno                                                                                      |
| `source.branch`          | `PROBARA_BRANCH`               | `string`                                | detectado del CI                                                   | Rama del origen de la ejecución                                                                                                                                   |
| `source.commit`          | `PROBARA_COMMIT`               | `string`                                | detectado del CI                                                   | Commit del origen de la ejecución                                                                                                                                 |
| `source.buildUrl`        | `PROBARA_BUILD_URL`            | `string`                                | detectado del CI                                                   | URL del build de CI del origen de la ejecución                                                                                                                    |
| `createMissingCases`     | `PROBARA_CREATE_MISSING_CASES` | `boolean`                               | `true`                                                             | Crear un caso para una prueba que no coincide con ninguno                                                                                                         |
| `suiteUlid`              | `PROBARA_SUITE_ULID`           | `string`                                | la raíz del proyecto                                               | Suite bajo la que van los casos creados                                                                                                                           |
| `closeRun`               | `PROBARA_CLOSE_RUN`            | `boolean`                               | `true` para una ejecución nueva, `false` para una reutilizada      | Cerrar la ejecución al final                                                                                                                                      |
| `closeRuns`              | —                              | `Record<string, boolean>`               | ninguno                                                            | Cerrar la ejecución de cada proyecto (`{ SHOP: true, WEB: false }`) cuando `closeRun` no está definido                                                            |
| `uploadAttachments`      | `PROBARA_UPLOAD_ATTACHMENTS`   | `boolean`                               | `true`                                                             | `false` no sube ningún archivo                                                                                                                                    |
| `keyIncludesFile`        | `PROBARA_KEY_INCLUDES_FILE`    | `boolean`                               | `true`                                                             | Empezar cada clave de automatización con el archivo de la spec ([`keyIncludesFile`](#keyincludesfile))                                                            |
| `captureOutput`          | `PROBARA_CAPTURE_OUTPUT`       | `boolean`                               | `false`                                                            | Adjuntar la salida de consola de cada prueba como `stdout.log` y `stderr.log` ([`captureOutput`](#captureoutput))                                                 |
| `attachScreenshots`      | `PROBARA_ATTACH_SCREENSHOTS`   | `boolean`                               | `true`                                                             | Adjuntar la captura de cada intento fallido ([`attachScreenshots`](#attachscreenshots))                                                                           |
| `attachVideos`           | `PROBARA_ATTACH_VIDEOS`        | `boolean`                               | `false`                                                            | Adjuntar el vídeo de una spec a sus resultados fallidos ([`attachVideos`](#attachvideos))                                                                         |
| `browserAsParameter`     | `PROBARA_BROWSER_AS_PARAMETER` | `boolean`                               | `true`                                                             | Enviar el navegador que ejecuta Cypress como parámetro `browser` ([`browserAsParameter`](#browserasparameter))                                                    |
| `issueUrlTemplate`       | `PROBARA_ISSUE_URL_TEMPLATE`   | `string`                                | ninguno                                                            | La URL en la que se convierte cada `probara.issue(id)`, con `%s` para el ID ([`issueUrlTemplate`](#issueurltemplate))                                             |
| `runCasesOnly`           | `PROBARA_RUN_CASES_ONLY`       | `boolean`                               | `false`                                                            | Ejecutar solo las pruebas de los casos de `run.ulid` ([`runCasesOnly`](#runcasesonly))                                                                            |
| `statusMapping`          | `PROBARA_STATUS_MAPPING`       | `{ passed, failed, skipped, blocked }`  | ninguno                                                            | Enviar un estado como otro (`failed=blocked`) ([estados](https://docs.probara.net/es/developers/ci-integrations/cypress/results-and-retries/#mapeo-y-filtro-de-estados))                  |
| `statusFilter`           | `PROBARA_STATUS_FILTER`        | `string[]`                              | ninguno                                                            | No enviar ningún resultado con estos estados, después del mapeo (`skipped`)                                                                                       |
| `resultsFile`            | `PROBARA_RESULTS_FILE`         | `string`                                | ninguno                                                            | Archivo JSON para lo que no se pudo enviar ([archivo de resultados](https://docs.probara.net/es/developers/ci-integrations/cypress/results-and-retries/#archivo-de-resultados))           |
| `assignFailedTo`         | `PROBARA_ASSIGN_FAILED_TO`     | `string[]`                              | ninguno                                                            | Asignar cada resultado fallido sin responsable a uno de estos miembros, por turnos (`ana@example.com,bo@example.com`)                                             |
| `debug`                  | `PROBARA_DEBUG`                | `boolean`                               | `false`                                                            | Registrar cada petición ([depuración](https://docs.probara.net/es/developers/ci-integrations/cypress/troubleshooting/#depuración))                                                        |
| `rootDir`                | —                              | `string`                                | el `projectRoot` de Cypress                                        | Directorio respecto al que se expresan las rutas de spec de las claves de automatización ([`keyIncludesFile`](#keyincludesfile))                                  |
| `chunkSize`              | —                              | `number`                                | `500`                                                              | Resultados por petición de informe, de 1 a 500                                                                                                                    |
| `timeoutMs`              | —                              | `number`                                | `30000`                                                            | Tiempo máximo de un intento HTTP, en milisegundos, de 1 a 600000                                                                                                  |
| `maxRetries`             | —                              | `number`                                | `4`                                                                | Reintentos de una petición fallida, de 0 a 10                                                                                                                     |
| `attachmentConcurrency`  | —                              | `number`                                | `2`                                                                | Resultados cuyos adjuntos se suben a la vez, de 1 a 8                                                                                                             |

El reporter envía su propio nombre y su versión en el `User-Agent` (por ejemplo
`probara-cypress-reporter/0.1.0`); no hay ninguna opción para ello.

En GitHub Actions el origen también recibe estos campos, detectados de las variables `GITHUB_*`:

| Opción                     | Variable | Tipo     | Por defecto                 | Qué hace                                                                        |
| -------------------------- | -------- | -------- | --------------------------- | ------------------------------------------------------------------------------- |
| `source.provider`          | —        | `string` | detectado de GitHub Actions | `github_actions` (detectado) u `other`                                          |
| `source.repository`        | —        | `string` | detectado de GitHub Actions | Repositorio del origen de la ejecución, `owner/name`                            |
| `source.commitAuthor`      | —        | `string` | detectado de GitHub Actions | Quién activó el build                                                           |
| `source.pullRequestNumber` | —        | `number` | detectado de GitHub Actions | Pull request del build                                                          |
| `source.workflow`          | —        | `string` | detectado de GitHub Actions | Workflow de CI del origen de la ejecución                                       |
| `source.ciRunId`           | —        | `string` | detectado de GitHub Actions | Id de la ejecución de CI: los jobs de un mismo workflow comparten una ejecución |
| `source.ciRunAttempt`      | —        | `number` | detectado de GitHub Actions | Intento de la ejecución de CI: una re-ejecución va a una ejecución propia       |
| `source.ciJob`             | —        | `string` | detectado de GitHub Actions | Job de CI del origen de la ejecución                                            |

### Opciones de runtime

Para código y pruebas, el reporter también acepta los puntos de extensión de `@probara/core`. No
tienen variable, y una configuración de Cypress rara vez los necesita:

| Opción   | Tipo                           | Valor por defecto            | Qué hace                                                         |
| -------- | ------------------------------ | ---------------------------- | ---------------------------------------------------------------- |
| `logger` | `{ debug, info, warn, error }` | líneas `[probara]` en stdout | Dónde registra el reporter                                       |
| `env`    | `Record<string, string>`       | `process.env`                | De dónde se leen las variables `PROBARA_*` y las del CI          |
| `fetch`  | `function`                     | el `fetch` global            | El cliente HTTP                                                  |
| `sleep`  | `function`                     | `setTimeout`                 | Las esperas entre reintentos                                     |
| `random` | `function`                     | `Math.random`                | La variación aleatoria del backoff                               |
| `now`    | `function`                     | la hora actual               | El reloj del nombre por defecto y de las fechas de `Retry-After` |

### Opciones desconocidas

Una opción que el reporter no conoce se omite con una advertencia, y el envío continúa:

```js
reporterOptions: { projectId: 'SHOP', captureOutputs: true },
```

```text
$ npx cypress run
[probara] Ignored the unknown option "captureOutputs" of @probara/cypress-reporter
[probara] Sending 3 results of 3 tests (3 passed, 0 failed, 0 skipped, 0 blocked)
[probara] Recorded 3 results (2 new cases, 0 unmatched) in R-1 (closed): https://app.probara.net/projects/SHOP/runs/R-1
```

## Ajustes propios del reporter de Cypress

### `keyIncludesFile`

Cada prueba se asocia a su caso por una clave de automatización: el archivo de la spec relativo a
`rootDir` (el `projectRoot` de Cypress), después `>` entre espacios, y después los títulos de los
`describe` y el título del `it` unidos por espacios, sin los IDs de caso:
`cypress/e2e/cart.cy.js > Cart adds an item`. Es la clave que `probara import junit` da a la misma
prueba en el informe del reporter `junit` de Cypress o de cypress-junit.

`keyIncludesFile: false` omite el archivo de la spec, como un informe JUnit escrito sin el atributo
`file` de su suite raíz. Úsalo cuando tus casos se importaron desde esos informes, para que cada
prueba conserve su caso. Una prueba recibe entonces la misma clave que otra con los mismos títulos
de `describe` y el mismo título en otra spec.

```js
reporterOptions: { projectId: 'SHOP', keyIncludesFile: false },
```

```text
Cart adds an item
Login logs in with a valid password
```

Cambiar `keyIncludesFile` cambia todas las claves: las pruebas que no nombran ningún caso en su
título crean entonces casos nuevos. Un caso que crea el informe va a una suite con el nombre de la
spec y de sus bloques `describe` o, con `keyIncludesFile: false`, solo con el de sus bloques
`describe`. Ni `--spec` ni las opciones de carpetas de Cypress cambian una clave
([vincular](https://docs.probara.net/es/developers/ci-integrations/cypress/linking/#claves-de-automatización)).

### `captureOutput`

`captureOutput: true` adjunta lo que cada prueba escribe en la consola del navegador con
`console.log`, `console.info` y `console.debug` como `stdout.log`, y con `console.warn` y
`console.error` como `stderr.log`. La consola del navegador sigue mostrándolo todo. Necesita el
archivo de soporte: sin él, no se captura nada. Qué se captura y qué no está en
[salida de consola](https://docs.probara.net/es/developers/ci-integrations/cypress/steps-and-attachments/#salida-de-consola).

### `attachScreenshots`

`attachScreenshots: true` (el valor por defecto) adjunta la captura que Cypress toma de un intento
fallido al resultado de **ese** intento, como `image/png`. Necesita el plugin, que es quien recibe
las capturas de Cypress. Con `false` no se adjunta ninguna, y Cypress las sigue tomando donde
siempre ([capturas de pantalla](https://docs.probara.net/es/developers/ci-integrations/cypress/steps-and-attachments/#capturas-de-pantalla)).

### `attachVideos`

`attachVideos: true` adjunta el vídeo de una spec a **cada resultado fallido de esa spec** (también a
uno bloqueado), con el nombre del archivo de la spec, como `video/mp4`. Necesita `video: true` en la
configuración de Cypress y el plugin. Está desactivado por defecto por su coste: una subida por cada
resultado fallido, y los vídeos pesan mucho
([el vídeo de una spec](https://docs.probara.net/es/developers/ci-integrations/cypress/steps-and-attachments/#el-vídeo-de-una-spec)).

### `browserAsParameter`

`browserAsParameter: true` (el valor por defecto) envía el nombre del navegador que ejecuta Cypress
(`electron`, `chrome`, `firefox`, `edge`) como parámetro `browser` de cada resultado:

```json
{
  "automationKey": "cypress/e2e/cart.cy.js > Cart adds an item",
  "parameters": { "browser": "electron" }
}
```

Nunca forma parte de la clave, así que una batería ejecutada en dos navegadores se registra en un
solo caso. El parámetro `browser` selecciona un caso de ejecución solo cuando el caso declara un
parámetro `browser`; si no, se queda en el resultado solo para mostrarlo. El navegador y el intento son contexto: se muestran en el resultado y nunca se convierten en un parámetro de un caso que un reporte crea. Es el plugin quien conoce
el navegador: sin él no hay parámetro `browser`.

### `issueUrlTemplate`

`probara.issue(id)` nombra una incidencia de tu gestor: `issueUrlTemplate` la convierte en un enlace
del resultado, con el ID como nombre y el ID codificado para URL en lugar de `%s`
(`https://jira.example.com/browse/%s`). La plantilla es una URL `http` o `https` con `%s`; cualquier
otro valor desactiva el envío con un error. Sin plantilla, las incidencias se omiten con una
advertencia ([enlaces](https://docs.probara.net/es/developers/ci-integrations/cypress/metadata/#enlaces-e-incidencias)).

### `runCasesOnly`

`runCasesOnly: true` (o `PROBARA_RUN_CASES_ONLY=true`) ejecuta solo las pruebas de los casos de la
ejecución `run.ulid` (`PROBARA_RUN_ULID`), y reporta en esa ejecución, que queda abierta. Necesita
tanto el plugin como el archivo de soporte. Actívalo por job con las variables y no en la
configuración: con la opción en la configuración, cada job sin ULID de ejecución muestra una
advertencia y ejecuta todas las pruebas.
[Selección de pruebas](https://docs.probara.net/es/developers/ci-integrations/cypress/run-selection/) tiene las reglas de
coincidencia y cada alternativa.

## Qué pasa con cada configuración

| Configuración                                     | Qué hace el reporter                                                                           |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Sin token ni proyecto, o con `enabled: false`     | Queda desactivado y en silencio: no se envía ni se registra nada (salvo en debug).             |
| Solo uno de los dos, o un valor no válido         | El envío queda desactivado; se registra cada problema, y las pruebas se ejecutan como siempre. |
| Un token y un proyecto, todos los valores válidos | Reporta.                                                                                       |

Un valor del tipo incorrecto (como `run.tags: 'nightly'` en lugar de una lista) es un valor no
válido:

```js
reporterOptions: { projectId: 'SHOP', run: { tags: 'nightly' } },
```

```text
$ npx cypress run
[probara] Probara reporting is off: run.tags must be a list of strings
```

Los problemas nombran la opción o la variable afectada, nunca su valor, así que un token nunca
aparece.

## Desactivar el envío

Define `enabled: false` o `PROBARA_ENABLED=false`, u omite el token: el reporter no envía nada y
queda en silencio. Los builds de pull requests desde forks no reciben secretos, así que no reportan
nada por sí solos. Para conservar lo que una ejecución no pudo enviar, incluso con el envío
desactivado, define un
[archivo de resultados](https://docs.probara.net/es/developers/ci-integrations/cypress/results-and-retries/#archivo-de-resultados).

## Probara autoalojado

Apunta el reporter a otro Probara con `baseUrl` o `PROBARA_BASE_URL`: la URL de la aplicación, sin
ruta. Las peticiones van a ese host y a ningún otro. Para proxies y autoridades de certificación
privadas, consulta [red](#red).

## Red

El reporter se comunica por HTTPS con un único host, la URL base, desde Node.js: el navegador que
ejecuta tus specs nunca llama a Probara.

### Qué proceso envía, y cuándo

| Configuración                          | Proceso que envía                                          | Cuándo                                                                                                   |
| -------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Con el plugin registrado (lo habitual) | El del plugin, en el Node.js que arranca `cypress`         | Todo al terminar la ejecución: los informes, después la subida de adjuntos, y después el cierre          |
| Sin plugin                             | El del reporter, dentro de Cypress, en el Node.js que trae | Los resultados de cada spec al terminar esa spec, en una ejecución propia                                |
| `runCasesOnly`                         | El del plugin                                              | Antes de la primera spec: leer las claves de casos de la ejecución, 200 casos por página hasta la última |

No se envía nada mientras se ejecutan las pruebas. Cypress espera al plugin antes de salir, así que
el tiempo de las peticiones, reintentos incluidos, forma parte del comando `cypress run`. Con
`runCasesOnly`, las claves de casos se leen una vez por `cypress run`; si no se pueden leer tras los
reintentos, todas las pruebas se ejecutan y se reportan, con una advertencia.

### Tiempos máximos

| Ajuste      | Valor por defecto                    | Rango      | Qué limita                                                                   |
| ----------- | ------------------------------------ | ---------- | ---------------------------------------------------------------------------- |
| `timeoutMs` | 30000 ms                             | 1 a 600000 | Un intento de una petición, incluido el cuerpo de la respuesta               |
| subidas     | 120000 ms, o `timeoutMs` si es mayor | —          | Un intento de subida de un adjunto (un archivo grande en una conexión lenta) |

Un intento que agota su tiempo se reintenta como un error de red.

### Reintentos y backoff

| Respuesta                                                       | Qué pasa                                            |
| --------------------------------------------------------------- | --------------------------------------------------- |
| Error de red, tiempo agotado, 408, 429, 500, 502, 503, 504      | Se reintenta                                        |
| 409 con `Retry-After` (la misma petición sigue en curso)        | Se reintenta                                        |
| Un `201` cuyo cuerpo nunca llegó                                | Se reintenta; la clave de idempotencia lo reproduce |
| Cualquier otra respuesta (400, 401, 403, 404, 409, 413, 422...) | No se reintenta: la petición falla                  |

- `maxRetries` (de 0 a 10, 4 por defecto) define los reintentos después del primer intento: 5
  intentos en total por defecto.
- La espera antes del reintento _n_ es 1 s × 2ⁿ⁻¹, como máximo 30 s, más hasta un 20 % de variación
  aleatoria.
- Una cabecera `Retry-After` (en segundos o como fecha HTTP) sustituye esa espera, con un máximo de
  120 s.
- Cada reintento se registra, con el intento y la espera.

Con los valores por defecto, un informe que sigue fallando se rinde tras unos 15 s de espera
(1 + 2 + 4 + 8 s, hasta 18 s con la variación), más los propios intentos, cada uno de como máximo
`timeoutMs`. El peor caso es un `Retry-After` en cada respuesta: 120 s antes de cada reintento, es
decir, 8 minutos de espera con los 4 reintentos por defecto (20 minutos con `maxRetries: 10`), más
hasta 5 intentos de 30 s. Eso es por petición, y un informe fallido detiene los siguientes de su
proyecto. Reduce `maxRetries` o `timeoutMs` para acotar un paso de CI.

### Límite de peticiones

Probara limita las peticiones a la API por organización (60 peticiones por minuto en Free, 1.200 en Pro y 3.000 en Enterprise), para todos los tokens de la organización en conjunto. Lo que cuesta una ejecución:

| Petición                 | Cuántas                                                                        |
| ------------------------ | ------------------------------------------------------------------------------ |
| Claves de casos          | 1 por cada 200 casos de la ejecución, solo con `runCasesOnly`                  |
| Informe                  | 1 por bloque de hasta 500 resultados (`chunkSize`)                             |
| Preparación de adjuntos  | 1 por resultado con archivos (por cada 20 archivos o 64 MiB)                   |
| Confirmación de adjuntos | 1 por resultado con archivos                                                   |
| Cierre                   | 1, cuando se encolaron adjuntos (si no, el último informe cierra la ejecución) |

Una ejecución de 2000 intentos sin archivos cuesta 4 peticiones; una en la que 100 intentos fallidos
adjuntan su captura cuesta unas 200 más. Sin el plugin, cada spec es una ejecución propia y paga
estas peticiones por su cuenta. Las respuestas `429` se reintentan después de su `Retry-After`. Para
repartir las subidas, reduce `attachmentConcurrency`; para enviar menos archivos, adjunta solo lo
importante, o define `uploadAttachments: false`.

### Bloques y orden

- Los resultados salen en bloques de `chunkSize` (de 1 a 500, 500 por defecto), **uno tras otro**, en
  el orden en que Cypress terminó las specs, con los intentos de cada spec en orden. Un caso de la
  ejecución conserva el último resultado registrado, así que el orden importa.
- El primer bloque crea la ejecución (salvo que `run.ulid` nombre una); los demás la reutilizan.
- Cuando un bloque falla tras sus reintentos, los bloques siguientes de ese proyecto no se envían y
  la ejecución queda abierta; un
  [archivo de resultados](https://docs.probara.net/es/developers/ci-integrations/cypress/results-and-retries/#archivo-de-resultados)
  los conserva.
- Las subidas empiezan cuando su informe queda registrado, `attachmentConcurrency` resultados a la
  vez (de 1 a 8, 2 por defecto), y la ejecución se cierra después de las subidas.

### Idempotencia

Cada informe, creación de ejecución, cierre de ejecución y confirmación de adjuntos lleva una
[`Idempotency-Key`](https://docs.probara.net/es/developers/api/idempotency/), la misma en cada reintento de esa petición. Un
informe reintentado cuyo primer intento sí se registró lo reproduce Probara, nunca se registra dos
veces. Volver a ejecutar `cypress run` es una ejecución nueva, con todos los resultados registrados
de nuevo.

### Proxies

El reporter usa el `fetch` integrado de Node y no tiene opción de proxy propia. Con el plugin
registrado, las peticiones salen del proceso del Node.js que arrancó `cypress`:

| Node.js                           | Soporte de proxy                                                                          |
| --------------------------------- | ----------------------------------------------------------------------------------------- |
| 22.21 o posterior, 24 o posterior | Define `NODE_USE_ENV_PROXY=1` con `HTTPS_PROXY` (y `NO_PROXY`); `fetch` pasa por el proxy |
| 22.12 a 22.20                     | Sin soporte: `fetch` ignora `HTTPS_PROXY` y `HTTP_PROXY`                                  |

```bash
NODE_USE_ENV_PROXY=1 HTTPS_PROXY=http://proxy.example.com:8080 npx cypress run
```

Node añadió el soporte de `NODE_USE_ENV_PROXY` para `fetch` en 22.21.0 y 24.0.0
([documentación de Node](https://nodejs.org/api/cli.html#node_use_env_proxy1)). Cypress también lee
`HTTPS_PROXY` y `NO_PROXY` para el tráfico del navegador
([configuración de proxy de Cypress](https://docs.cypress.io/app/references/proxy-configuration)):
pon en `NO_PROXY` los hosts a los que tus pruebas acceden directamente. En versiones anteriores de
Node, actualiza Node o permite la URL base en el firewall. Detrás de un proxy, registra el plugin:
sin él, las peticiones salen del propio proceso de Cypress.

### Autoridades de certificación propias

Para un Probara autoalojado detrás de una autoridad de certificación privada, entrega a Node el
certificado de la CA (PEM) al arrancar:

```bash
NODE_EXTRA_CA_CERTS=/etc/ssl/certs/company-ca.pem npx cypress run
```

Node lee `NODE_EXTRA_CA_CERTS` una sola vez al arrancar, así que defínela en el entorno del paso. En
Node 22.19 y posteriores, `NODE_USE_SYSTEM_CA=1` confía en cambio en el almacén de certificados del
sistema operativo. No hay ninguna opción para desactivar la verificación TLS.

## Modo interactivo

**`cypress open` no reporta nada.** Cypress construye el `reporter` de su configuración
[solo durante `cypress run`](https://docs.cypress.io/app/references/configuration#Global): la
aplicación muestra en su lugar su propio registro de comandos. Una sesión de `cypress open` con el
reporter, el plugin y el archivo de soporte registrados ejecuta sus pruebas como siempre y no crea
ninguna ejecución en Probara. Para reportar las specs en las que trabajas, ejecútalas con
`cypress run --spec`:

```bash
PROBARA_API_TOKEN=… PROBARA_PROJECT=SHOP npx cypress run --spec 'cypress/e2e/cart.cy.js'
```

Para reunir varios `cypress run` locales en una sola ejecución, créala una vez y pasa su ULID a cada
uno; el reporter nunca cierra una ejecución que no creó:

```bash
PROBARA_RUN_ULID=$(npx @probara/cli run create --run-name "Cart rework")
export PROBARA_RUN_ULID
npx cypress run --spec 'cypress/e2e/cart.cy.js'
npx cypress run --spec 'cypress/e2e/checkout.cy.js'
npx @probara/cli run close
```

Relacionado: [Primeros pasos](https://docs.probara.net/es/developers/ci-integrations/cypress/) ·
[Resultados y reintentos](https://docs.probara.net/es/developers/ci-integrations/cypress/results-and-retries/) ·
[Solución de problemas](https://docs.probara.net/es/developers/ci-integrations/cypress/troubleshooting/) · Fuente:
[configuration.md](https://github.com/cynch-me/probara-sdk/blob/main/packages/cypress-reporter/docs/configuration.md),
[network.md](https://github.com/cynch-me/probara-sdk/blob/main/packages/cypress-reporter/docs/network.md),
[watch.md](https://github.com/cynch-me/probara-sdk/blob/main/packages/cypress-reporter/docs/watch.md)