Metadata-Version: 2.4
Name: behave-modern-file-report
Version: 1.1.2
Summary: Document-style report formatters for Behave BDD (PDF, DOCX, TXT).
Project-URL: Homepage, https://github.com/MathiasPaulenko/behave-modern-file-report
Project-URL: Documentation, https://github.com/MathiasPaulenko/behave-modern-file-report#readme
Project-URL: Repository, https://github.com/MathiasPaulenko/behave-modern-file-report
Project-URL: Issues, https://github.com/MathiasPaulenko/behave-modern-file-report/issues
Project-URL: Changelog, https://github.com/MathiasPaulenko/behave-modern-file-report/blob/main/CHANGELOG.md
Author-email: Mathias Paulenko <mathias@paulenko.com>
License: MIT
License-File: LICENSE
Keywords: bdd,behave,docx,pdf,report,txt
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Testing :: BDD
Requires-Python: >=3.11
Provides-Extra: all
Requires-Dist: behave>=1.3.0; extra == 'all'
Requires-Dist: jinja2>=3.1; extra == 'all'
Requires-Dist: python-docx>=1.1; extra == 'all'
Requires-Dist: reportlab>=4.0; extra == 'all'
Requires-Dist: weasyprint>=63.0; extra == 'all'
Provides-Extra: behave
Requires-Dist: behave>=1.3.0; extra == 'behave'
Provides-Extra: dev
Requires-Dist: behave>=1.3.0; extra == 'dev'
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: jinja2>=3.1; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: python-docx>=1.1; extra == 'dev'
Requires-Dist: reportlab>=4.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Requires-Dist: weasyprint>=63.0; extra == 'dev'
Provides-Extra: docx
Requires-Dist: python-docx>=1.1; extra == 'docx'
Provides-Extra: pdf
Requires-Dist: jinja2>=3.1; extra == 'pdf'
Requires-Dist: reportlab>=4.0; extra == 'pdf'
Requires-Dist: weasyprint>=63.0; extra == 'pdf'
Description-Content-Type: text/markdown

# behave-modern-file-report

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](#testing)
[![Coverage](https://img.shields.io/badge/coverage-enabled-brightgreen.svg)](#testing)

Document-style report formatters for **[Behave](https://github.com/behave/behave)** BDD framework.
Generate polished **PDF**, **DOCX**, and **TXT** reports from your Behave test runs — with
cover pages, executive summaries, environment metadata, attachments, and branding support.

---

## Table of contents

- [Features](#features)
- [Installation](#installation)
- [Quick start](#quick-start)
- [Example project](#example-project)
- [CLI usage](#cli-usage)
- [Configuration options](#configuration-options)
- [Attachments API](#attachments-api)
- [Custom templates](#custom-templates)
- [Branding](#branding)
- [Extras](#extras)
- [Development](#development)
- [License](#license)

---

## Features

- **Three output formats**: PDF (via WeasyPrint or ReportLab), DOCX (python-docx), TXT
- **Cover page** with title, project name, logo, and run metadata
- **Executive summary** with scenario totals, pass rate, and per-feature breakdown
- **Environment metadata** (Python version, platform, hostname, Git info)
- **Attachments**: screenshots, files, text, and JSON — embedded inline in reports
- **Multi-source screenshots**: bytes, file path, Selenium WebDriver, Playwright Page, PIL Image
- **Custom Jinja2 templates** for PDF reports
- **Branding**: custom logo, primary color, title, and project name
- **Table of contents** (PDF/DOCX) with clickable links
- **Error blocks** with traceback, exception type, and message
- **Background steps** and **Rule** support
- **Scenario outlines** with example tables
- **Regression tests** with golden files for TXT and HTML output

---

## Installation

```bash
# Install with all optional dependencies
pip install "behave-modern-file-report[all]"

# Or pick only what you need
pip install "behave-modern-file-report[behave,pdf]"
pip install "behave-modern-file-report[behave,docx]"
pip install "behave-modern-file-report[behave]"
```

---

## Quick start

1. Install the package with the formats you need:

   ```bash
   pip install "behave-modern-file-report[all]"
   ```

2. Run Behave with a formatter and output file:

   ```bash
   behave -f behave-modern-pdf -o report.pdf features/
   behave -f behave-modern-docx -o report.docx features/
   behave -f behave-modern-txt -o report.txt features/
   ```

   > **Note:** The formatters are registered as `behave-modern-pdf`, `behave-modern-docx`,
   > and `behave-modern-txt` entry points. You can also define shorter aliases in your
   > `behave.ini` if you prefer.

3. Open the generated report file.

---

## Example project

A ready-to-run sample is in [`examples/behave_project`](examples/behave_project):

```bash
cd examples/behave_project
behave -f behave-modern-pdf -o report.pdf
behave -f behave-modern-docx -o report.docx
behave -f behave-modern-txt -o report.txt
```

The included `behave.ini` configures the formatters and sets `bmfr.title`,
`bmfr.project_name`, and `bmfr.pdf_engine = reportlab` so the PDF example works
without WeasyPrint system dependencies.

---

## CLI usage

The formatters are registered as Behave formatter entry points. Use them with
`-f <formatter-name>` and `-o <output-file>`:

```bash
# PDF report (default engine: WeasyPrint)
behave -f behave-modern-pdf -o report.pdf features/

# DOCX report
behave -f behave-modern-docx -o report.docx features/

# TXT report
behave -f behave-modern-txt -o report.txt features/

# Multiple formatters at once
behave \
  -f behave-modern-pdf -o report.pdf \
  -f behave-modern-docx -o report.docx \
  -f behave-modern-txt -o report.txt \
  features/
```

### PDF engine selection

By default, PDF reports are rendered with **WeasyPrint**. WeasyPrint produces the
richest output but needs system libraries (GTK/Pango). If it is not available,
switch to the self-contained **ReportLab** engine:

```bash
behave -f behave-modern-pdf -o report.pdf -D "bmfr.pdf_engine=reportlab" features/
```

---

## Configuration options

All options are passed via Behave's `-D` (userdata) flag with the `bmfr.` prefix.
Format-specific options (`bmfr.<format>.<key>`) take precedence over global options
(`bmfr.<key>`).

| Option | Default | Description |
|--------|---------|-------------|
| `bmfr.title` | `Behave Modern Report` | Report title shown on cover page |
| `bmfr.project_name` | _(empty)_ | Project name shown on cover page |
| `bmfr.logo` | _(empty)_ | Path to a logo image file (PNG, JPEG) |
| `bmfr.primary_color` | `#2563EB` | Primary hex color for branding |
| `bmfr.template` | _(empty)_ | Path to a custom Jinja2 template file or directory |
| `bmfr.only_failed` | `false` | Only include failed scenarios in the report |
| `bmfr.include_attachments` | `true` | Embed attachments in the report |
| `bmfr.attachment_max_size_kb` | `512` | Maximum attachment size in KB |
| `bmfr.max_traceback_lines` | `50` | Maximum traceback lines per error |
| `bmfr.txt_width` | `100` | TXT report line width |
| `bmfr.txt_ascii` | `false` | Use ASCII-only characters in TXT report |
| `bmfr.pdf_engine` | `weasyprint` | PDF engine: `weasyprint` or `reportlab` |

### Format-specific overrides

Any option can be scoped to a specific format:

```bash
# Different title for PDF vs DOCX
behave \
  -f behave-modern-pdf -o report.pdf \
  -f behave-modern-docx -o report.docx \
  -D "bmfr.pdf.title=PDF Report" \
  -D "bmfr.docx.title=DOCX Report" \
  features/
```

---

## Attachments API

The package provides a public API for attaching screenshots, files, text, and JSON
to your test steps. Attachments are embedded inline in the reports.

### Screenshot

```python
from behave_modern_file_report import attach_screenshot

@when("I take a screenshot")
def step_impl(context):
    attach_screenshot(context, context.driver.get_screenshot_as_png(), "login_page.png")
```

Supports multiple source types:

```python
# From bytes
attach_screenshot(context, png_bytes, "page.png")

# From file path
attach_screenshot(context, "/tmp/screenshot.png", "page.png")

# From Selenium WebDriver
attach_screenshot(context, context.driver, "page.png")

# From Playwright Page
attach_screenshot(context, context.page, "page.png")

# From PIL Image
attach_screenshot(context, pil_image, "page.png")
```

### File, text, and JSON

```python
from behave_modern_file_report import attach_file, attach_text, attach_json, log

# Attach a file
attach_file(context, "/tmp/report.csv", "report.csv")

# Attach text content
attach_text(context, "Debug output here", "debug.txt")

# Attach JSON data
attach_json(context, {"key": "value"}, "response.json")

# Log a message
log(context, "Something happened")
```

---

## Custom templates

PDF reports are rendered from Jinja2 templates. You can provide your own template
file or directory:

```bash
behave -f behave-modern-pdf -o report.pdf \
  -D "bmfr.template=/path/to/my_template.html" \
  features/
```

The template receives these context variables:

| Variable | Type | Description |
|----------|------|-------------|
| `run` | `RunSummary` | Full run data with features, scenarios, steps |
| `options` | `ReportOptions` | Resolved options (title, logo, colors, etc.) |
| `css` | `str` | Inline CSS string from `default.css` |
| `logo_b64` | `str` | Base64-encoded logo data URI |

Custom Jinja2 filters are available:

| Filter | Description |
|--------|-------------|
| `format_duration` | Format seconds as `1.23s`, `456ms`, or `0ms` |
| `status_icon` | Return status icon character (`✓`, `✗`, `↷`, `?`, `○`) |

---

## Branding

Customize the look of your reports with logo, colors, title, and project name:

```bash
behave -f behave-modern-pdf -o report.pdf \
  -D "bmfr.logo=assets/logo.png" \
  -D "bmfr.primary_color=#1E90FF" \
  -D "bmfr.title=QA Report" \
  -D "bmfr.project_name=My Project" \
  features/
```

- **PDF**: Logo appears on the cover page, primary color is injected into CSS variables
- **DOCX**: Logo on cover page, primary color applied to headings, badges, and progress bar
- **TXT**: Title shown on cover page

---

## Extras

| Extra | Dependencies | Description |
|-------|-------------|-------------|
| `behave` | `behave>=1.3.0` | Behave framework integration |
| `pdf` | `Jinja2>=3.1`, `weasyprint>=63.0`, `reportlab>=4.0` | PDF report generation |
| `docx` | `python-docx>=1.1` | DOCX report generation |
| `all` | All of the above | Everything in one install |
| `dev` | `all` + `pytest`, `ruff`, `mypy`, `build`, `twine` | Development tools |

```bash
pip install "behave-modern-file-report[all]"
pip install "behave-modern-file-report[dev]"
```

---

## Development

```bash
# Install dev dependencies
make dev

# Run tests
make test

# Lint
make lint

# Type check
make typecheck

# Format
make format

# Build
make build

# Clean
make clean
```

### Testing

The project uses a comprehensive test suite with:

- Unit tests for all writers, formatters, models, and utilities
- Golden file regression tests for TXT and HTML output
- Integration tests with Behave (skipped if Behave is not installed)
- Type checking with mypy and linting with ruff

```bash
make test          # Run all tests
make lint          # Ruff linting
make typecheck     # Mypy type checking
```

---

## License

[MIT](LICENSE) © Mathias Paulenko
