# Reporter de Cucumber

> Envía cada escenario y cada paso de Cucumber a Probara al final de la ejecución, con @probara/cucumber-reporter — instálalo, configúralo y revisa tus ejecuciones.

`@probara/cucumber-reporter` es un [formateador de Cucumber](https://cucumber.io) para cucumber-js. Envía
a Probara cada escenario de una ejecución al final de esta: cada intento con sus pasos, sus palabras clave y
sus datos, sus errores y sus adjuntos, identificado con la misma clave que el caso sincronizado del
escenario. Un escenario etiquetado con `@probara:SHOP-12` llega a ese caso. Los casos que faltan se crean,
y la ejecución se cierra cuando todo ha llegado.

Es de código abierto, está publicado en [npm](https://www.npmjs.com/package/@probara/cucumber-reporter) en
la versión `0.1.0` y vive en el
[repositorio de probara-sdk](https://github.com/cynch-me/probara-sdk/tree/main/packages/cucumber-reporter).
Antes de la 1.0, una versión menor puede traer cambios incompatibles: fija la versión y lee el
[changelog](https://github.com/cynch-me/probara-sdk/blob/main/packages/cucumber-reporter/CHANGELOG.md)
antes de actualizar.

Sincroniza primero tus archivos `.feature` en la rama principal, para que Git tenga los casos. Después, el
reporter envía los resultados de las pruebas. [Sincronizar archivos .feature desde Git](https://docs.probara.net/es/guides/syncing-feature-files-from-git/)
explica la sincronización.

## Qué obtienes

- **Un resultado por intento.** Un escenario reintentado con `--retry` envía cada intento, en orden. Cada
  fila de un esquema de escenario es un resultado propio, registrado en el caso de ejecución con los valores de la fila.
- **Cada paso**, con su palabra clave (`Given`, `When`, `Then`, `And`, `But` o `*`, en inglés), su estado, su
  duración, su error y el Doc String o la Data Table que tuviera. Los pasos de Background van bajo un paso
  `Background`.
- **Adjuntos.** Los archivos que un paso adjunta con `this.attach`, `this.log` y `this.link` se suben con su
  resultado.
- **Vinculación** por la clave del escenario, construida como la construye `probara sync gherkin`, o por una
  etiqueta `@probara:<ID>`.
- **Ejecuciones** con el nombre de la compilación de CI, que se cierran al terminar.
- **Nunca rompe tu ejecución de pruebas.** Un problema al reportar se registra en stderr. El código de salida
  de la ejecución sigue siendo el de cucumber-js.

## Lo que necesitas

| Lo que necesitas                                                   | Por qué                                                                                    |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| Node.js 22.12 o posterior                                          | El rango `engines` del paquete.                                                            |
| `@cucumber/cucumber` 13.3 o posterior (13.3 es la versión probada) | El formateador se carga desde la misma instalación que cucumber-js.                        |
| Un plan de pago (**Pro** o **Enterprise**, o cualquier prueba)     | Reportar desde CI no forma parte del plan Free. En Free, Probara responde `403 forbidden`. |
| Un **propietario** o **administrador** de Probara                  | Solo los propietarios y administradores crean y revocan tokens de aplicación.              |
| El **ID de proyecto** donde reportar                               | Como `SHOP`: una letra mayúscula, y después letras mayúsculas o dígitos.                   |

## 1. Crea un token de aplicación

El reporter inicia sesión con un [token de aplicación](https://docs.probara.net/es/developers/authentication/#tokens-de-aplicación):
un token que pertenece a la organización, no a una persona. No consume un puesto y sigue funcionando cuando
quien lo creó deja la organización.

1. En Probara, abre **Workspace › Integraciones** y selecciona la tarjeta **Cucumber**.
2. Abre la pestaña **Tokens de acceso** y selecciona **Crear un token de aplicación**.
3. Escribe un **Nombre del token** con el nombre de lo que lo usa (el repositorio o el pipeline) y selecciona
   **Crear token**.
4. Selecciona **Copiar token**. Solo se muestra una vez: guárdalo enseguida como secreto de CI llamado
   `PROBARA_API_TOKEN`.

La [guía de la integración con Cucumber](https://docs.probara.net/es/guides/integrations/cucumber/) cubre la tarjeta, la gestión y la
revocación de tokens, y lo que Probara muestra de las ejecuciones que crea un token de aplicación.

## 2. Instala el reporter

Instálalo junto a cucumber-js, en el mismo proyecto:

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

## 3. Añádelo a cucumber.js

Añade el formateador a `format`, y tu ID de proyecto a `formatOptions`:

```js
// cucumber.js
module.exports = {
  default: {
    format: ['@probara/cucumber-reporter'],
    formatOptions: { probara: { projectId: 'SHOP' } },
  },
};
```

El formateador sustituye la salida de progreso de cucumber-js. Para conservarla, indica también una ruta de
archivo para el reporter: `format: ['progress', '@probara/cucumber-reporter:reports/probara.txt']`. La
[página de configuración](https://docs.probara.net/es/developers/ci-integrations/cucumber/configuration/#dónde-va-la-salida) explica
por qué.

## 4. Ejecuta tus pruebas con el token

Da al paso que ejecuta cucumber-js el secreto. En GitHub Actions:

```yaml
- name: Ejecutar las pruebas de Cucumber
  run: npx cucumber-js
  env:
    PROBARA_API_TOKEN: ${{ secrets.PROBARA_API_TOKEN }}
```

No hay un paso de envío aparte: el reporter envía los resultados al final de la ejecución, y la cierra
entonces. [Proveedores de CI](https://docs.probara.net/es/developers/ci-integrations/cucumber/ci-providers/) tiene pipelines completos
para GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines, Bitbucket Pipelines y Buildkite. En
ellos, la sincronización de los archivos `.feature` en la rama principal va antes de las pruebas.

## Qué ves

El reporter registra en stderr y no imprime nada en stdout. Al terminar la ejecución, registra cuántos resultados
envía, a qué ejecución van y, si sube archivos, cuántos:

```text
$ npx cucumber-js
[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
[probara] Attached 2 files to results (0 skipped, 0 failed)
```

En Probara, la ejecución aparece en la lista de ejecuciones del proyecto como una ejecución automatizada, con
el nombre de la compilación de CI (o `Automated run <fecha>` fuera de CI), y con su rama, su commit y la URL
de la compilación. Muestra la aplicación **Cucumber** y el nombre del token (como **Cucumber · e2e-ci**) en
lugar de una persona.

## Cómo se traduce Cucumber a Probara

| Cucumber                                     | En Probara                                                                                                  |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Un escenario, una vez por intento            | Un resultado en el caso con su clave de automatización, o en el caso que nombra su etiqueta `@probara:<ID>` |
| Una fila de un esquema de escenario          | Un resultado propio, registrado en el caso de ejecución con los valores de la fila                          |
| Un paso                                      | Un paso del resultado, con su palabra clave, estado, duración, error y datos                                |
| Los pasos de Background                      | Un paso `Background` del resultado, con ellos anidados                                                      |
| `this.attach`, `this.log` y `this.link`      | Archivos del resultado, o del paso que los adjuntó                                                          |
| Un hook `Before` o `After` que falla         | El escenario falla, con el error del hook o `The hook failed`. El hook en sí no se envía                    |
| Un escenario que no coincide con ningún caso | Un caso nuevo, con el nombre del escenario, en la suite de `suiteUlid` (la raíz del proyecto por defecto)   |
| La ejecución de cucumber-js                  | Una ejecución automatizada, con el nombre de la compilación de CI, que se cierra al final                   |

Los hooks no son pasos, así que nunca aparecen en la lista de pasos. La duración de cada hook sí cuenta en la
duración de su escenario.

## Reportar nunca rompe tu ejecución de pruebas

El reporter nunca lanza errores a cucumber-js ni cambia su código de salida: un escenario que falla hace fallar
el comando, y un problema al reportar no. Cada problema (una configuración incorrecta, Probara inaccesible, un
token rechazado) se registra en stderr, nunca con el token. Para conservar lo que no se pudo enviar, configura
un [archivo de resultados](https://docs.probara.net/es/developers/ci-integrations/cucumber/results-and-retries/#archivo-de-resultados).

## Referencia

| Página                                                                                  | Qué cubre                                                                                                      |
| --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| [Configuración](https://docs.probara.net/es/developers/ci-integrations/cucumber/configuration/)                 | Cada opción, su variable, tipo y valor por defecto; precedencia; la salida; la red                             |
| [Vincular casos de prueba](https://docs.probara.net/es/developers/ci-integrations/cucumber/linking/)            | La clave de automatización, los esquemas de escenario, la etiqueta `@probara:<ID>` y los casos que no existen  |
| [Pasos y adjuntos](https://docs.probara.net/es/developers/ci-integrations/cucumber/steps-and-attachments/)      | Los campos de los pasos, Background, hooks, Doc Strings y Data Tables, y los archivos que adjunta un escenario |
| [Resultados y reintentos](https://docs.probara.net/es/developers/ci-integrations/cucumber/results-and-retries/) | Estados, reintentos, mapeo y filtro de estados, duraciones, archivo de resultados                              |
| [Proveedores de CI](https://docs.probara.net/es/developers/ci-integrations/cucumber/ci-providers/)              | GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines, Bitbucket Pipelines, Buildkite                  |
| [Solución de problemas](https://docs.probara.net/es/developers/ci-integrations/cucumber/troubleshooting/)       | Cada mensaje que registra el reporter, y qué hacer con él                                                      |
| [Migración y actualización](https://docs.probara.net/es/developers/ci-integrations/cucumber/migrating/)         | Desde `probara import cucumber`, desde el reporter de cucumber-js de Qase, y cómo actualizar                   |

Relacionado: [Integraciones CI](https://docs.probara.net/es/developers/ci-integrations/) ·
[CLI](https://docs.probara.net/es/developers/cli/) (`sync gherkin`, e `import cucumber` para los JSON de otras herramientas) ·
[Guía de la integración con Cucumber](https://docs.probara.net/es/guides/integrations/cucumber/) ·
[Sincronizar archivos .feature desde Git](https://docs.probara.net/es/guides/syncing-feature-files-from-git/) ·
[Código fuente en GitHub](https://github.com/cynch-me/probara-sdk/tree/main/packages/cucumber-reporter)