behave-modern-file-report

Document-style report formatters for 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
• Installation
• Quick start
• Example project
• CLI usage
• Configuration options
• Attachments API
• Custom templates
• Branding
• Extras
• Development
• 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

# 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:

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

2. Run Behave with a formatter and output file:

   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:

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

# 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:

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:

# 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

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:

# 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

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:

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:

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

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

---

Development

# 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

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

---

License

MIT © Mathias Paulenko