# Reporter de Playwright

> Envía a Probara cada resultado de tus pruebas de Playwright desde CI con @probara/playwright-reporter — requisitos, instalación, configuración y tu primera ejecución.

`@probara/playwright-reporter` es un reporter de [Playwright](https://playwright.dev) que envía a
Probara cada resultado de una ejecución de `playwright test`: cada intento con su estado, sus pasos,
sus errores y sus adjuntos, vinculado a su caso de prueba. Los casos que aún no existen se crean, y
la ejecución se cierra cuando todo ha llegado. Lo registras en `playwright.config` junto al reporter
que lees en la terminal; no hace falta un paso de subida aparte.

- Paquete: [`@probara/playwright-reporter` en npm](https://www.npmjs.com/package/@probara/playwright-reporter)
  (versión actual `0.1.0`).
- Código fuente y changelog: [probara-sdk en GitHub](https://github.com/cynch-me/probara-sdk/tree/main/packages/playwright-reporter)
  (Apache-2.0).
- Lado de Probara: la [guía de la integración con Playwright](https://docs.probara.net/es/guides/integrations/playwright/)
  cubre la tarjeta **Playwright**, sus tokens de aplicación y lo que muestra Probara.

## Antes de empezar

| Necesitas                                                    | Por qué                                                                                                                 |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| Node.js 22.12 o posterior                                    | Es el campo `engines` del paquete. El proceso principal de Playwright ejecuta el reporter.                              |
| `@playwright/test` 1.42 o posterior                          | Es el rango de la dependencia peer. Los archivos de los pasos necesitan 1.50; el contexto de error de un intento, 1.51. |
| 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, Probara responde `403 forbidden`.                |
| Alguien con el permiso **Administrar integraciones**         | Crear un token de aplicación forma parte de ese permiso, que tienen los propietarios y los administradores.             |
| El **ID del Proyecto** al que enviar los resultados          | Una letra mayúscula seguida de mayúsculas o dígitos, por ejemplo `SHOP`. Cualquier otro valor desactiva el envío.       |

## 1. Crea un token de aplicación

El reporter se autentica con un [token de aplicación](https://docs.probara.net/es/developers/authentication/#tokens-de-aplicación):
un token que pertenece a tu organización, no a una persona. No ocupa ningún puesto y sigue
funcionando cuando la persona que lo creó se va.

1. En **Workspace › Integraciones**, selecciona la tarjeta **Playwright**.
2. Abre la pestaña **Tokens de acceso** y selecciona **Crear un token de aplicación**.
3. Escribe un **Nombre del token** con lo que lo usa (el repositorio o el pipeline) y selecciona
   **Crear token**.
4. Selecciona **Copiar token** en **Copia tu nuevo token**. Empieza por `probara_app_` y solo se muestra una vez: guárdalo en
   ese momento como un secreto de CI llamado `PROBARA_API_TOKEN`.

El reporter lee el token del entorno. Nunca lo pongas en `playwright.config`, que se sube al
repositorio.

## 2. Instala el reporter

```bash
npm i -D @probara/playwright-reporter
```

Fija la versión en `package.json` (o conserva el lockfile) para que una versión nueva nunca cambie
un pipeline por sorpresa: el reporter está en `0.x`, donde una versión minor puede cambiar opciones
([actualizar](https://docs.probara.net/es/developers/ci-integrations/playwright/migrating/#actualizar)).

## 3. Regístralo en `playwright.config`

Añádelo junto al reporter que lees en la terminal, con tu ID del Proyecto (o define
`PROBARA_PROJECT` en el entorno):

```ts
// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  reporter: [['list'], ['@probara/playwright-reporter', { projectId: 'SHOP' }]],
});
```

Todo lo demás tiene un valor por defecto: la ejecución toma el nombre del build de CI, y su rama,
su commit y la URL del build salen del CI. El paquete exporta el tipo de sus opciones,
`ProbaraPlaywrightOptions`, por si quieres que se comprueben:

```ts
// playwright.config.ts
import { defineConfig } from '@playwright/test';
import type { ProbaraPlaywrightOptions } from '@probara/playwright-reporter';

export default defineConfig({
  reporter: [
    ['list'],
    ['@probara/playwright-reporter', { projectId: 'SHOP' } satisfies ProbaraPlaywrightOptions],
  ],
});
```

## 4. Ejecuta tus pruebas con el token

Pasa el secreto al paso que ejecuta `npx playwright test`. En GitHub Actions:

```yaml
- name: Run Playwright tests
  run: npx playwright test
  env:
    PROBARA_API_TOKEN: ${{ secrets.PROBARA_API_TOKEN }}
```

El reporter escribe en stderr, en líneas `[probara]`, y termina con el enlace a la ejecución:

```text
$ npx playwright test
[probara] Sending 2 results of 2 tests (2 passed, 0 failed, 0 skipped, 0 blocked)
[probara] Recorded 2 results (1 new case, 0 unmatched) in R-1 (closed): https://app.probara.net/projects/SHOP/runs/R-1
```

Sin un token y un proyecto, el reporter queda desactivado y en silencio: las ejecuciones locales, y
los builds que no reciben secretos (como los pull requests desde forks en la mayoría de los CI), no
envían nada, sin ninguna opción extra. Para un workflow completo en tu CI, consulta
[proveedores de CI](https://docs.probara.net/es/developers/ci-integrations/playwright/ci-providers/).

## Qué ves en Probara

- **Una ejecución automatizada**, con el nombre del build de CI (`Playwright #42` en GitHub
  Actions), la rama, el commit y un enlace al build. Se cierra cuando el reporter termina.
- **Un resultado por intento**: una prueba reintentada muestra cada intento en el historial del
  caso de la ejecución, y el caso conserva el último resultado.
- **Pasos** de `test.step`, anidados, con su estado, su duración y su error, y los archivos
  adjuntados dentro de ellos.
- **Adjuntos**: capturas, vídeos, trazas, el contexto de error y tus propios archivos de
  `testInfo.attach()`.
- **Casos de prueba nuevos** para las pruebas que no coinciden con ninguno, en suites construidas a
  partir del archivo y de los títulos de `describe`.
- **Atribución al token**: las ejecuciones y los resultados muestran la aplicación y el nombre del
  token, por ejemplo **Playwright · e2e-ci**, no a una persona.

## Cómo se corresponde Playwright con Probara

| Playwright                                 | En Probara                                                                                  |
| ------------------------------------------ | ------------------------------------------------------------------------------------------- |
| El comando `playwright test`               | Una ejecución automatizada, con el nombre del build de CI, cerrada al final                 |
| Una prueba (por proyecto de Playwright)    | Un caso de prueba, encontrado por su clave de automatización o vinculado por un ID de caso  |
| Cada intento (reintentos incluidos)        | Un resultado en la ejecución, con su estado, su duración, su hora de inicio y sus errores   |
| `test.step` y los hooks que ejecutan pasos | Los pasos del resultado, anidados, con su estado, su duración y su error                    |
| Capturas, vídeos, trazas, adjuntos         | Archivos del resultado, o del paso en el que se adjuntaron                                  |
| Llamadas `probara.*` en la prueba          | El título, la suite, las etiquetas, los campos y los pasos de un caso nuevo; los parámetros |

La misma prueba en dos proyectos de Playwright (`chromium` y `firefox`) son dos casos: el proyecto
forma parte de la clave de automatización
([vincular](https://docs.probara.net/es/developers/ci-integrations/playwright/linking/#claves-de-automatización)).

## El envío nunca rompe tu ejecución de pruebas

El reporter nunca lanza errores dentro de Playwright ni cambia su código de salida: una prueba que
falla hace fallar el comando; un problema de envío, no. Una opción mal escrita, un Probara
inaccesible o un token rechazado se registran en stderr, nunca con el token, y las pruebas conservan
su resultado. No hay ninguna opción para que el comando falle por un error de envío; para conservar
lo que no se pudo enviar, define un
[archivo de resultados](https://docs.probara.net/es/developers/ci-integrations/playwright/results-and-retries/#archivo-de-resultados).

## Referencia

| Página                                                                                    | Qué cubre                                                                              |
| ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [Configuración](https://docs.probara.net/es/developers/ci-integrations/playwright/configuration/)                 | Cada opción, su variable, su tipo y su valor por defecto; precedencia; red, proxies    |
| [Vincular pruebas con casos](https://docs.probara.net/es/developers/ci-integrations/playwright/linking/)          | Anotaciones, IDs de caso en los títulos, `probara.id()`, claves de automatización      |
| [Metadatos](https://docs.probara.net/es/developers/ci-integrations/playwright/metadata/)                          | Título, suite, comentario, etiquetas, campos, parámetros, ignorar un intento           |
| [Pasos y adjuntos](https://docs.probara.net/es/developers/ci-integrations/playwright/steps-and-attachments/)      | `test.step`, hooks, `probara.step()`, capturas, vídeos, trazas, `probara.attach()`     |
| [Resultados y reintentos](https://docs.probara.net/es/developers/ci-integrations/playwright/results-and-retries/) | Opciones de la ejecución, estados, mapeo de estados, reintentos, archivo de resultados |
| [Shards y varios proyectos](https://docs.probara.net/es/developers/ci-integrations/playwright/sharding/)          | Una ejecución para todos los shards, `merge-reports`, varios proyectos de Probara      |
| [Proveedores de CI](https://docs.probara.net/es/developers/ci-integrations/playwright/ci-providers/)              | GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines, Bitbucket, Buildkite    |
| [Solución de problemas](https://docs.probara.net/es/developers/ci-integrations/playwright/troubleshooting/)       | Problemas y soluciones, el registro, `PROBARA_DEBUG`, comprobar qué se enviaría        |
| [Migrar y actualizar](https://docs.probara.net/es/developers/ci-integrations/playwright/migrating/)               | Desde Qase, desde `probara import junit`, versiones y el contrato de la clave          |

Siguiente: [configura el reporter](https://docs.probara.net/es/developers/ci-integrations/playwright/configuration/), o
vuelve al [resumen de integraciones de CI](https://docs.probara.net/es/developers/ci-integrations/). ¿Usas Jest, Cypress o
Vitest? Consulta el [reporter de Jest](https://docs.probara.net/es/developers/ci-integrations/jest/), el
[reporter de Cypress](https://docs.probara.net/es/developers/ci-integrations/cypress/) o el
[reporter de Vitest](https://docs.probara.net/es/developers/ci-integrations/vitest/).