Metadata-Version: 2.4
Name: robotframework-evidence-reporter
Version: 0.1.0
Summary: Standalone business evidence reports per Robot Framework test
License-Expression: MIT
License-File: LICENSE
Keywords: robotframework,selenium,evidence,reporting,pabot
Author: Angel Gerardo Molina Valdez
Requires-Python: >=3.12,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Dist: jinja2 (>=3.1.6,<4.0)
Requires-Dist: pillow (>=11.0,<14.0)
Requires-Dist: robotframework (>=7.0,<8.0)
Project-URL: Homepage, https://angel-valdezzz.github.io/robotframework-evidence-reporter/
Project-URL: Repository, https://github.com/angel-valdezzz/robotframework-evidence-reporter
Description-Content-Type: text/markdown

# Robot Framework Evidence Reporter

Un HTML autocontenido por caso de Robot Framework, orientado a evidencias de negocio. Registra capturas explícitas, mensajes y metadatos durante la ejecución; genera el HTML después, desde CLI o Python.

[Documentación](https://angel-valdezzz.github.io/robotframework-evidence-reporter/) · [Documentación de keywords](https://angel-valdezzz.github.io/robotframework-evidence-reporter/reference/keywords.html) · [Ver reporte HTML](https://angel-valdezzz.github.io/robotframework-evidence-reporter/demo/passed.html)

## Estado de publicación

El código, la documentación y la demo HTML están publicados. La publicación en PyPI se ejecuta mediante GitHub Actions y requiere el Trusted Publisher configurado en la cuenta del propietario. Por ahora se puede instalar desde una revisión Git fija o construir el wheel desde el repositorio.

## Instalación

```bash
# Disponible después de la primera publicación en PyPI
pip install robotframework-evidence-reporter
poetry add robotframework-evidence-reporter

# Instalación desde el código publicado mientras tanto
pip install "git+https://github.com/angel-valdezzz/robotframework-evidence-reporter.git@main"
```

Python 3.12 o superior y Robot Framework 7. Para capturar páginas o elementos instala también SeleniumLibrary. La librería reutiliza su navegador activo: no abre otra sesión ni depende de un navegador concreto.

## Uso en Robot

```robotframework
*** Settings ***
Library    SeleniumLibrary
Library    EvidenceReporter

*** Test Cases ***
Registrar Cliente
    Open Browser    https://example.test    chrome
    Set Report Metadata    Aplicación=Portal    Ambiente=QA    Ticket=QA-123
    Capture Page Evidence    Formulario de alta
    ${milestone}=    Create Milestone    Cliente registrado
    Capture Element Evidence    css:.confirmation    Confirmación    milestone_id=${milestone}
    Add Evidence Message    El alta fue confirmada.    milestone_id=${milestone}
    [Teardown]    Close All Browsers
```

Los hitos son opcionales. Sin `milestone_id`, la evidencia se añade directamente al caso. No se registran automáticamente argumentos ni todos los logs técnicos; añade los mensajes de negocio que necesites.

```bash
robot --outputdir results tests
rf-evidence build results/evidence --output reports
```

Cada caso conserva su estado final de Robot (`PASS`, `FAIL`, `SKIP`), inicio, fin y duración, incluidos fallos del teardown. Un proceso interrumpido antes de guardar el resultado final conserva `INCOMPLETE`. Las fechas incluyen el offset horario del proceso que las registra.

## Capturas y errores

| Keyword | Captura |
| --- | --- |
| `Capture Page Evidence` | Página visible del navegador activo |
| `Capture Element Evidence` | Elemento usando un locator SeleniumLibrary |
| `Capture Desktop Evidence` | Escritorio de la máquina donde corre Robot |
| `Attach Image Evidence` | Copia una imagen PNG, JPEG o WEBP existente |

Las capturas fallidas producen **WARN por defecto**, se registran en el HTML y no cambian el estado del caso. Usa `strict=${True}` por keyword o `strict=${True}` al importar la librería para exigir una captura. `strict=${False}` por keyword permite sobrescribir esa configuración global.

El usuario elige cuándo usar el escritorio. No hay detección automática de headless, remoto ni paralelismo. Pillow ImageGrab necesita un entorno gráfico compatible; en Linux puede requerir un backend de captura, y en macOS permisos de pantalla. La captura corresponde al escritorio del proceso, no necesariamente al navegador remoto. No se implementa página completa en esta versión.

Errores definidos: `BROWSER_UNAVAILABLE`, `ELEMENT_NOT_FOUND`, `SCREENSHOT_FAILED`, `DESKTOP_UNAVAILABLE`, `IMAGE_UNAVAILABLE`, `INVALID_IMAGE`, `STORAGE_ERROR`. Argumentos incorrectos, hitos ajenos al caso y errores internos no se silencian. Si falla el almacenamiento inicial o final del listener, Robot registra el error del listener; comprueba también que se hayan generado los JSON esperados.

## Python y paralelo

```python
from rf_evidence_reporter import build_reports

paths = build_reports("results/evidence", "reports")
```

Cada caso usa un UUID y un directorio propio. Para Pabot proporciona un directorio compartido de esta ejecución, por ejemplo `output_dir=${EXECDIR}/results/evidence`. Genera los HTML después de que terminen todos los procesos. Usa un directorio nuevo por ejecución: el generador incluye todos los `case.json` encontrados y conserva cada intento separado.

## Desarrollo

```bash
poetry install
poetry run ruff check src tests scripts
poetry run ruff format --check src tests scripts
poetry run robocop check tests examples
poetry run python -m unittest discover -s tests -v
poetry run python scripts/validate.py
poetry run python scripts/demo.py
poetry run python -m robot.libdoc --name "Evidence Reporter" EvidenceReporter docs/reference/keywords.html
poetry run mkdocs build --strict
poetry build
```

`scripts/validate.py` verifica Robot y Pabot, incluyendo un caso con fallo deliberado en teardown. Las pruebas del núcleo usan unittest de Python; las pruebas de integración usan Robot. La demo pública utiliza datos e imágenes ficticios, indicados en el propio reporte.

El HTML incluye imágenes, CSS y JavaScript sin recursos externos. Su visualizador funciona sin conexión y es navegable con teclado. Jira puede permitir adjuntarlo sin ofrecer vista previa; se puede descargar y abrir en un navegador. El contenido y las imágenes no se censuran automáticamente: registra solo datos apropiados para el destino del reporte.

## Publicación

GitHub Actions valida los cambios. `main` publica MkDocs y la demo en GitHub Pages. Un cambio de `pyproject.toml` en `main`, o una release `vX.Y.Z` cuya versión coincida con el paquete, publica wheel y sdist en PyPI mediante Trusted Publishing. Consulta `docs/publishing.md` para el registro inicial del publisher.

Licencia MIT.

## Estatus de evidencia y presentación

Las cuatro keywords de captura aceptan `status=INFO` (por defecto), `PASS`, `WARN` o `FAIL`. No aceptan `SKIP`; un valor inválido produce `INVALID_CAPTURE_STATUS`. El estatus describe la evidencia y no modifica el resultado de Robot. Si la captura falla, se registra una advertencia independientemente del estatus solicitado.

Consulta los [ejemplos completos con estatus de evidencia](https://angel-valdezzz.github.io/robotframework-evidence-reporter/guide/#estatus-de-evidencia-y-presentacion).

El HTML tiene pestañas **Resumen**, **Pasos** y **Logs**. Resumen muestra una sola insignia de estatus de ejecución (`SKIP` en amarillo). Pasos presenta capturas e hitos; sus logs son plegables. Logs agrupa mensajes y advertencias en bloques plegables, con bordes por nivel y fondo neutro. El switch permite elegir modo claro u oscuro; conserva la preferencia cuando el navegador permite almacenamiento local.

Las fechas visibles incluyen día/mes/año y hora con segundos. La zona horaria se indica al pie y el JSON conserva el timestamp completo. Los registros anteriores sin estatus de captura se presentan como `INFO`. No hay botón de impresión; PDF y Word quedan para una etapa posterior.

## Navegación del reporte

En Pasos, las evidencias directas empiezan plegadas y tienen pestañas Evidencias/Logs del bloque. Los hitos empiezan abiertos; puedes contraerlos individualmente o usar Expandir/Contraer todos los hitos. Los controles globales no modifican el bloque directo.

La documentación comparte logo, colores y temas con el reporte. Consulta [Primera evidencia](https://angel-valdezzz.github.io/robotframework-evidence-reporter/getting-started/) para ejemplos de instalación y ejecución.

