# Solución de problemas del reporter de Playwright

> Resuelve los problemas habituales de @probara/playwright-reporter — nada enviado, respuestas 401 y 403, ejecuciones abiertas, resultados sin coincidencia, adjuntos que faltan — y lee su registro.

El reporter escribe en stderr, en líneas `[probara]`; [`PROBARA_DEBUG=true`](#registro-de-depuración)
añade cada petición. Sea cual sea el problema, el código de salida de Playwright sigue siendo el de
las pruebas: el reporter nunca lanza errores dentro de Playwright y no tiene ninguna opción para que
el comando falle por un error de envío.

## Dónde se ven los problemas

| Ves                                                    | Consulta                                                                                            |
| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| Ninguna línea `[probara]`                              | [No se envía nada](#no-se-envía-nada-y-no-se-registra-nada)                                         |
| `... Probara reporting is off ...`                     | [Un problema de configuración](#el-envío-está-desactivado-un-problema-de-configuración)             |
| `... not sent ...`                                     | [401 o 403](#probara-responde-401-o-403), [la ejecución quedó abierta](#la-ejecución-quedó-abierta) |
| `... not recorded (...)`                               | [Resultados sin coincidencia](#hay-resultados-que-no-se-registraron-sin-coincidencia)               |
| `[probara] probara.x() ...` en la salida de una prueba | [Un helper avisa](#un-helper-avisa-de-que-solo-funciona-mientras-se-ejecuta-una-prueba)             |

## No se envía nada y no se registra nada

**Por qué.** Sin un token y un proyecto, el reporter queda desactivado y en silencio, a propósito:
las ejecuciones locales y los builds de forks no envían nada. Solo lo indica en modo depuración:

```text
$ PROBARA_DEBUG=true npx playwright test
[probara] Probara reporting is not configured: set PROBARA_API_TOKEN and PROBARA_PROJECT to enable it
```

**Solución.** Pasa el secreto `PROBARA_API_TOKEN` al paso que ejecuta `npx playwright test`, y
define el proyecto (`projectId` o `PROBARA_PROJECT`). Comprueba que el reporter está registrado en
la configuración que usa Playwright (`reporter: [...]`), o en `--reporter` si pasas uno:
`--reporter` sustituye a los reporters de la configuración. Con `merge-reports`, el token y el
reporter van en el job de combinación
([shards](https://docs.probara.net/es/developers/ci-integrations/playwright/sharding/#patrón-1-combinar-los-informes-blob)).

## El envío está desactivado: un problema de configuración

```text
$ PROBARA_RUN_ULID=R-12 npx playwright test
[probara] Probara reporting is off: PROBARA_RUN_ULID is not a ULID
```

**Por qué.** Un ajuste tiene un valor incorrecto, o solo está definido uno de los dos, el token o el
proyecto. Cada problema se registra nombrando la opción o la variable afectada (nunca su valor), y
no se envía nada.

**Solución.** Corrige el ajuste que nombra la línea
([opciones](https://docs.probara.net/es/developers/ci-integrations/playwright/configuration/#opciones)).

## Probara responde 401 o 403

```text
$ npx playwright test
[probara] Sending 2 results of 2 tests (2 passed, 0 failed, 0 skipped, 0 blocked)
[probara] 2 results were not sent: Probara answered 401 unauthorized: <message from Probara>. No run was created or updated
```

**Por qué.** `401 unauthorized`: el token es incorrecto, está revocado o corresponde a otro host de
Probara (`baseUrl`). `403 forbidden`: el token no puede enviar a ese proyecto, o la organización
está en el plan Free, donde el envío desde CI no está disponible.

**Solución.** Crea un token de aplicación nuevo desde la tarjeta **Playwright**
([primeros pasos](https://docs.probara.net/es/developers/ci-integrations/playwright/#1-crea-un-token-de-aplicación)) y
actualiza el secreto; revisa el ID del Proyecto; revisa el plan de la organización. La
[referencia de los tokens de aplicación](https://docs.probara.net/es/developers/authentication/#tokens-de-aplicación) lista
las llamadas exactas que puede hacer un token.

## La ejecución quedó abierta

La línea de error termina con `The run R-4 was left open: <url>`, o, cuando ni siquiera el primer
informe llegó, con `No run was created or updated`.

**Por qué.** Un informe falló tras sus reintentos (Probara inaccesible, un informe rechazado): los
informes siguientes no se envían, y una ejecución que ya tiene resultados queda abierta, para que
nada parezca completo cuando no lo está. La última línea nombra la ejecución.

**Solución.** Define un
[archivo de resultados](https://docs.probara.net/es/developers/ci-integrations/playwright/results-and-retries/#archivo-de-resultados):
lo que no se envió va ahí, con la ejecución a la que pertenece, y `probara import results` lo envía
a esa ejecución y la cierra. Si no, cierra la ejecución a mano con
`npx @probara/cli run close --run-ulid <ulid>` y vuelve a ejecutar las pruebas.

## Un job envía después de cerrarse su ejecución

En GitHub Actions los jobs de un mismo workflow comparten una ejecución, y un job final la cierra. Un
job que envía después de ese cierre recibe `409 ci_run_closed` (la ejecución ya estaba cerrada): el
reporter registra el motivo, no envía nada más, y las pruebas conservan su código de salida.

**Por qué.** Un job que envía no está en el `needs` del job final, así que el job final cerró la
ejecución antes de que ese job enviara. O un job en paralelo cerró la ejecución al terminar porque no
tenía `PROBARA_CLOSE_RUN: false`, y los jobs posteriores reciben el mismo error.

**Solución.** Mantén cada job que envía en el `needs` del job final, y define `PROBARA_CLOSE_RUN: false`
en cada job en paralelo. La sección
[jobs en paralelo](https://docs.probara.net/es/developers/ci-integrations/playwright/ci-providers/#jobs-en-paralelo-una-ejecución-cerrada-por-el-job-final)
tiene el workflow completo.

## Hay resultados que no se registraron (sin coincidencia)

```text
$ PROBARA_CREATE_MISSING_CASES=false npx playwright test
[probara] Sending 2 results of 2 tests (2 passed, 0 failed, 0 skipped, 0 blocked)
[probara] Recorded 1 result (0 new cases, 1 unmatched) in R-1 (closed): https://app.probara.net/projects/SHOP/runs/R-1
[probara] 1 result was not recorded (case_not_found): cart.spec.ts > cart > removes an item
```

**Por qué.** Un resultado nombra un caso que no existe (un ID mal escrito, un caso de otro
proyecto), o no coincide con ningún caso mientras `createMissingCases` está desactivado. Probara
registra los demás e indica cuáles quedaron fuera, con el motivo.

**Solución.** Corrige el ID, crea el caso o deja que el reporter cree los casos que faltan (el
comportamiento por defecto).

## No se envía un caso de otro proyecto

**Por qué.** Una prueba está vinculada a `WEB-3` mientras `WEB` no es el proyecto ni uno de
`projects`: el resultado acabaría en el proyecto equivocado. Una advertencia por proyecto lo indica.

**Solución.** Lista el proyecto en `projects` (`PROBARA_PROJECTS=WEB`)
([varios proyectos](https://docs.probara.net/es/developers/ci-integrations/playwright/sharding/#varios-proyectos-de-probara)).

## Cada ejecución crea casos nuevos

**Por qué.** Las claves de automatización cambiaron: se renombró o movió una prueba, un `describe` o
un archivo, se renombró un proyecto de Playwright, o cambió `rootDir` (`testDir`)
([qué cambia una clave](https://docs.probara.net/es/developers/ci-integrations/playwright/linking/#claves-de-automatización)).
Ejecutar desde otro directorio no cambia las claves: son relativas al `rootDir` de Playwright.

**Solución.** Vincula las pruebas con sus casos por ID
([vincular](https://docs.probara.net/es/developers/ci-integrations/playwright/linking/)), para que un cambio de nombre los
conserve. Antes de una refactorización, [compara las claves](#comprobar-qué-se-enviaría).

## Falta un adjunto

**Por qué.** El registro nombra cada archivo que omitió y el motivo: más de 32 MiB, una imagen de más
de 10 MiB o de 8192 px, un tipo de contenido rechazado, más de 20 archivos en un resultado, o un
archivo que ya no estaba al subirlo
([límites](https://docs.probara.net/es/developers/ci-integrations/playwright/steps-and-attachments/#límites-y-lo-que-se-omite)).
Un archivo adjuntado dentro de un paso va a ese paso, no al resultado. Los vídeos y las trazas solo
existen cuando `use` los activa.

**Solución.** Conserva `test-results/` hasta que el reporter termine; reduce el tamaño de las
capturas (`fullPage: false`); adjunta menos archivos por resultado.

## Un helper avisa de que solo funciona mientras se ejecuta una prueba

**Por qué.** Se llamó a un helper `probara.*` fuera de una prueba: al principio de un archivo, en
`beforeAll`, en `afterAll` o en un fixture de worker. No se registra nada, y la prueba continúa.

**Solución.** Llámalo en la prueba, en `beforeEach`, en `afterEach` o en un fixture de prueba
([dónde llamar a los helpers](https://docs.probara.net/es/developers/ci-integrations/playwright/metadata/#dónde-llamar-a-los-helpers)).

## Probara responde 429 (demasiadas peticiones)

**Por qué.** El límite de tasa de la organización (60 peticiones por minuto en Free, 1.200 en Pro y 3.000 en Enterprise) lo
comparten todos los tokens y pipelines. Los adjuntos cuestan dos peticiones por resultado
([límite de tasa](https://docs.probara.net/es/developers/ci-integrations/playwright/configuration/#límite-de-tasa)).

**Solución.** El reporter espera y reintenta por su cuenta. En suites grandes, conserva las trazas y
los vídeos solo de los fallos, baja `attachmentConcurrency` o reparte en el tiempo los pipelines con
shards.

## merge-reports no envía nada

**Por qué.** El reporter no está entre los reporters de la combinación, o el job de combinación no
tiene token.

**Solución.** Pasa `--reporter @probara/playwright-reporter` (o un `--config` que lo registre) a
`npx playwright merge-reports`, y da a ese job `PROBARA_API_TOKEN` y el proyecto
([shards](https://docs.probara.net/es/developers/ci-integrations/playwright/sharding/#patrón-1-combinar-los-informes-blob)).

## El registro

El reporter escribe solo en **stderr**, con cada línea precedida de `[probara]`; stdout pertenece a
los reporters de Playwright (`list`, `dot`...). Una ejecución que envía resultados escribe dos
líneas:

```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
```

| Línea                                | Qué dice                                                                                                                    |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `Sending N results of M tests (...)` | Antes de enviar nada: un resultado por intento y caso, por estado después de `statusMapping`, y lo que se dejó fuera        |
| `Recorded N results (...) in R-1`    | Por ejecución: lo que registró Probara, los casos que creó, los resultados sin coincidencia y el enlace                     |
| `N results were not recorded (...)`  | Los resultados sin coincidencia, por motivo, con sus casos o claves                                                         |
| `Attached N files to results (...)`  | Subidas: adjuntados, omitidos y fallidos                                                                                    |
| `N results were not sent: ...`       | Un informe fallido: el motivo, y la ejecución que quedó abierta                                                             |
| `Wrote ... to <file>`                | Lo que fue al [archivo de resultados](https://docs.probara.net/es/developers/ci-integrations/playwright/results-and-retries/#archivo-de-resultados) |

Una advertencia que se repite en cada prueba (una llamada mal formada a un helper, un adjunto
omitido) se registra la primera vez, nombrando la prueba, y después solo en modo depuración. El
token nunca aparece en ninguna línea, ni siquiera cuando la respuesta de Probara lo repite. Las
líneas del registro son para personas: no las analices con código, porque una versión minor puede
cambiarlas.

## Registro de depuración

`debug: true` (`PROBARA_DEBUG=true`) añade una línea por cada petición (método, ruta, estado,
tiempo) y por cada reintento, e indica por qué el envío está desactivado cuando lo está:

```bash
PROBARA_DEBUG=true npx playwright test
```

Déjalo desactivado en las ejecuciones normales: es muy detallado, aunque nunca registra el token ni
los cuerpos.

## Comprobar qué se enviaría

El reporter no tiene un modo de simulación propio, pero un archivo de resultados cumple esa función:
ejecuta las pruebas con el envío desactivado y un archivo de resultados, y deja que la CLI imprima lo
que enviaría. Nada llega a Probara, y no hace falta token:

```text
$ PROBARA_ENABLED=false PROBARA_PROJECT=SHOP PROBARA_RESULTS_FILE=probara-results.json npx playwright test
[probara] Wrote 2 results to /work/shop/probara-results.json: send them with probara import results /work/shop/probara-results.json
$ npx @probara/cli import results probara-results.json --dry-run
passed	SHOP-12	cart.spec.ts > cart > adds an item
passed	-	cart.spec.ts > cart > removes an item
Total: 2 results from 1 file (2 passed, 0 failed, 0 skipped, 0 blocked)
```

El primer comando escribe en stderr; la simulación imprime en stdout una línea por resultado: el
estado, el caso (`-` cuando no nombra ninguno) y la clave de automatización. `--dry-run` nunca toca
el archivo: bórralo después, o impórtalo de verdad, porque un archivo que se queda ahí hace que la
siguiente ejecución escriba `probara-results-2.json`. `--json` imprime en cambio el documento
completo, cada entrada tal como la recibiría Probara
([`probara import results`](https://github.com/cynch-me/probara-sdk/blob/main/packages/cli/docs/commands.md#probara-import-results),
en inglés).

Úsalo para comparar las claves antes de una refactorización o de una actualización: escribe un
archivo por ejecución y compara las dos simulaciones. Da a cada ejecución su propio nombre de archivo
y empieza sin ellos: con un archivo ya en la ruta, una ejecución escribe en un hermano
(`before-2.json`), y la simulación de `before.json` mostraría una ejecución anterior, ocultando la
diferencia.

```bash
rm -f before.json after.json
PROBARA_ENABLED=false PROBARA_PROJECT=SHOP PROBARA_RESULTS_FILE=before.json npx playwright test
# Change the code, or upgrade the reporter, then:
PROBARA_ENABLED=false PROBARA_PROJECT=SHOP PROBARA_RESULTS_FILE=after.json npx playwright test
npx @probara/cli import results before.json --dry-run > before.txt
npx @probara/cli import results after.json --dry-run > after.txt
diff before.txt after.txt
```

Cada línea que cambió es una prueba cuya clave o vínculo a un caso cambió: recibiría un caso nuevo.

Siguiente: [red, reintentos y proxies](https://docs.probara.net/es/developers/ci-integrations/playwright/configuration/#red),
o la [guía de solución de problemas de la CLI](https://github.com/cynch-me/probara-sdk/blob/main/packages/cli/docs/troubleshooting.md)
(en inglés) para `probara import results`, `run create` y `run close`.