Metadata-Version: 2.4
Name: robotframework-xlibrary-result
Version: 1.0.1
Summary: HTML report generator for Robot Framework — rich, self-contained reports with API logging, deep-diff, JSON Schema validation, image comparison, and screenshot annotation.
Author-email: Tassana Khrueawan <Tassana.khr@gmail.com>
Maintainer-email: Tassana Khrueawan <Tassana.khr@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Khrx1999/robotframework-xlibrary-result
Project-URL: Repository, https://github.com/Khrx1999/robotframework-xlibrary-result
Project-URL: Documentation, https://github.com/Khrx1999/robotframework-xlibrary-result#readme
Project-URL: Changelog, https://github.com/Khrx1999/robotframework-xlibrary-result/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/Khrx1999/robotframework-xlibrary-result/issues
Keywords: robotframework,robot-framework,test-automation,html-report,api-testing,screenshot,json-schema,test-reporting
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Robot Framework
Classifier: Framework :: Robot Framework :: Library
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Testing :: Acceptance
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: robotframework>=6.0
Requires-Dist: Jinja2>=3.0
Requires-Dist: MarkupSafe>=2.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: Pillow>=9.4
Requires-Dist: numpy>=1.20
Requires-Dist: requests>=2.28
Provides-Extra: schema
Requires-Dist: jsonschema>=4.0; extra == "schema"
Provides-Extra: imaging
Requires-Dist: opencv-python>=4.5; extra == "imaging"
Requires-Dist: imageio>=2.20; extra == "imaging"
Provides-Extra: all
Requires-Dist: jsonschema>=4.0; extra == "all"
Requires-Dist: opencv-python>=4.5; extra == "all"
Requires-Dist: imageio>=2.20; extra == "all"
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# robotframework-xlibrary-result

[![PyPI version](https://img.shields.io/pypi/v/robotframework-xlibrary-result.svg)](https://pypi.org/project/robotframework-xlibrary-result/)
[![Python versions](https://img.shields.io/pypi/pyversions/robotframework-xlibrary-result.svg)](https://pypi.org/project/robotframework-xlibrary-result/)
[![Robot Framework](https://img.shields.io/badge/Robot%20Framework-6.0%2B-green.svg)](https://robotframework.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> Rich, self-contained HTML reports for Robot Framework — API logging, deep-diff comparison, JSON Schema validation, image diffing, and annotated screenshots in a single `test_result.html`.

---

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Keyword Reference](#keyword-reference)
- [Configuration](#configuration)
- [Compatibility](#compatibility)
- [Development](#development)
- [License](#license)

---

## Features

- **Self-contained HTML report** — single file, no external assets, ready to share or attach to CI artifacts.
- **API request / response logger** — headers, body, cURL preview, status badge, sensitive-data masking.
- **Deep-diff data comparator** — Dict ↔ Dict, List ↔ List, Dict ↔ List with 3 viewer modes (Table / JSON / Inline).
- **JSON Schema validation** — Draft-7 with tree-style error rendering.
- **Image comparison** — pixel, histogram, template-matching, and ORB feature algorithms.
- **Cross-platform screenshots** — desktop, Android (ADB), iOS (xcrun), and Flutter; auto-annotated.
- **Zero-config defaults** — bundled `report.yaml` works out-of-the-box; project-level YAML overrides automatically picked up.

---

## Installation

```bash
pip install robotframework-xlibrary-result
```

Optional extras:

| Extra | Adds | Use when |
|---|---|---|
| `[schema]` | `jsonschema` | You need `VALIDATE JSON SCHEMA` |
| `[imaging]` | `opencv-python`, `imageio` | You need template / ORB image diff |
| `[all]` | All of the above | You want everything bundled |

```bash
pip install "robotframework-xlibrary-result[all]"
```

---

## Quick Start

```robotframework
*** Settings ***
Library    robotframework_xlibrary_result.XLibraryResult
Library    RequestsLibrary

Suite Setup       Init Report
Suite Teardown    Finalise Report

*** Variables ***
${REPORT_PATH}    ${OUTPUT_DIR}/test_result.html
@{EXEC_RESULTS}   @{EMPTY}

*** Test Cases ***
TC01 — Get user list
    SET CURRENT TEST CASE ID    TC01
    APPEND STEP TITLE           Execution
    ${resp}=    GET    https://api.example.com/users
    Append Request and Response to HTML Report
    ...    GET /users    PASS    request_data=${None}    response_data=${resp.json()}
    ...    http_method=GET    http_status_code=${resp.status_code}    url=${resp.url}
    Compare Dict to Dict    ${resp.json()}    {"status": "ok"}    Verify status field

*** Keywords ***
Init Report
    ${LIB}=    Get Library Instance    robotframework_xlibrary_result.XLibraryResult
    ${EMPTY}=  Create Dictionary
    Setup Generate HTML Report    ${LIB}    ${REPORT_PATH}    Demo Suite
    ...    ${EMPTY}    ${EMPTY}    Robot Framework user

Finalise Report
    Write Steps To HTML    ${REPORT_PATH}    PASS    ${EXEC_RESULTS}
```

More runnable examples: see [`examples/`](examples/).

---

## Keyword Reference

### Setup & Lifecycle
| Keyword | Purpose |
|---|---|
| `Load Report Config` | Load `report.yaml` (project or bundled default) |
| `Setup Generate HTML Report` | Initialise the report at suite start |
| `Write Steps To HTML` | Flush collected steps to the final HTML at suite teardown |
| `SET CURRENT TEST CASE ID` | Bind the active test case for subsequent steps |

### Step Logging
| Keyword | Purpose |
|---|---|
| `APPEND STEP TO HTML RESULT` | Add a generic step (status badge, duration, attachments) |
| `APPEND STEP TITLE` | Add a section title |
| `APPEND STEP SUB TITLE` | Add a sub-section title |
| `Capture Screenshot` | Capture & attach an annotated screenshot |
| `Generate Execution Results From Steps` | Build the suite-level execution summary |
| `ANALYZE REPORT ON TEST RESULT` | Post-run analysis of report contents |

### API Logging
| Keyword | Purpose |
|---|---|
| `APPEND STEP REQUEST HTML RESULT` | Log a single HTTP request (headers / body / cURL) |
| `Append Request and Response to HTML Report` | Log request + response side-by-side |
| `VALIDATE RESPONSE WITH HTML` | Validate a response and embed the result |

### Data Comparison
| Keyword | Purpose |
|---|---|
| `Compare Dict to Dict` | Deep-diff two dicts |
| `Compare List of Dict to List of Dict` | Deep-diff two lists of dicts (per-item card view) |
| `Compare Dict to List of Dict` | Match a dict against a list-of-dicts |

### Validation & Imaging
| Keyword | Purpose |
|---|---|
| `VALIDATE JSON SCHEMA` | Validate JSON against Draft-7 schema |
| `xCompare Images` | Compare two images (pixel / histogram / template / ORB) |

---

## Configuration

The library searches upwards from your test file for `CONFIG/REPORT_CONFIG/report.yaml`. If none is found, it falls back to the bundled `defaults/report.yaml` — so it works **out-of-the-box** with zero setup.

Override only the keys you care about:

```yaml
project:
  name: "My Awesome API"
  logo: "https://example.com/logo.png"
  subtitle: "Smoke + regression"

tool:
  version: "v2.5.1"

footer:
  powered_by: "Powered by Robot Framework"
  copyright: "© {year} Acme Corp"

report:
  auto_open: true
  filename: "smoke_2025_q4"
```

Full schema with comments: [`defaults/report.yaml`](src/robotframework_xlibrary_result/defaults/report.yaml).

---

## Compatibility

| | Supported |
|---|---|
| **Python** | 3.9 – 3.13 |
| **Robot Framework** | 6.0+ |
| **OS** | macOS, Linux, Windows |

---

## Development

```bash
git clone https://github.com/Khrx1999/robotframework-xlibrary-result.git
cd robotframework-xlibrary-result
pip install -e ".[dev,all]"

pytest                  # run smoke tests
ruff check src tests    # lint
python -m build         # build sdist + wheel
```

Contributions welcome — please open an issue first to discuss significant changes. See [CHANGELOG.md](CHANGELOG.md) for release notes.

---

## License

MIT — see [LICENSE](LICENSE).

Copyright © 2026 **Tassana Khrueawan**.
