behave-modern-sheets-report

Modern spreadsheet report formatters for Behave BDD — generate CSV, XLSX, and ODS execution reports with multi-sheet layouts, conditional formatting, and automatic trend history.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Format Comparison
• Report Structure
• CLI Usage
• Configuration Options
• Available Columns
• Automatic History & Trends
• Programmatic Usage
• Architecture
• Ecosystem
• Contributing
• Security
• Changelog
• License

Features

Requirements

• Python 3.11 or higher
• Behave >= 1.2.6 (for running BDD tests)
• openpyxl >= 3.1 (optional, for XLSX output)
• odfpy >= 1.4 (optional, for ODS output)

Installation

pip install behave-modern-sheets-report

Extras

Install with multiple extras:

pip install "behave-modern-sheets-report[xlsx,ods]"

For full development setup:

git clone https://github.com/MathiasPaulenko/behave-modern-sheets-report.git
cd behave-modern-sheets-report
pip install -e ".[dev,xlsx,ods]"
pre-commit install

Quick Start

1. Register the formatters in your behave.ini (or the [behave.formatters] section of setup.cfg/tox.ini):

   [behave.formatters]
   csv-modern = behave_modern_sheets_report.csv_formatter:CSVFormatter
   xlsx-modern = behave_modern_sheets_report.xlsx_formatter:XLSXFormatter
   ods-modern = behave_modern_sheets_report.ods_formatter:ODSFormatter
   

2. Run Behave with any (or all) of the formatters:

   behave -f xlsx-modern -o report.xlsx
   

3. Open report.xlsx in Excel, LibreOffice, or Google Sheets.

A ready-to-run demo lives in examples/behave_project — it includes a behave.ini with the formatters already registered and features covering backgrounds, scenario outlines, and a failing step.

Format Comparison

Report Structure

XLSX and ODS reports contain up to four sheets:

CSV reports produce a single flat file with one row per scenario (equivalent to the Details sheet).

Conditional formatting colors

Status mapping

Behave statuses are normalized into canonical values:

CLI Usage

Register the formatters in behave.ini (Behave does not discover entry points automatically):

[behave.formatters]
csv-modern = behave_modern_sheets_report.csv_formatter:CSVFormatter
xlsx-modern = behave_modern_sheets_report.xlsx_formatter:XLSXFormatter
ods-modern = behave_modern_sheets_report.ods_formatter:ODSFormatter

Generate reports:

behave -f csv-modern -o report.csv
behave -f xlsx-modern -o report.xlsx
behave -f ods-modern -o report.ods

Multiple formatters can be used simultaneously to produce all formats in a single run:

behave -f csv-modern -o report.csv -f xlsx-modern -o report.xlsx -f ods-modern -o report.ods

If -o is omitted, CSV output goes to stdout and XLSX/ODS reports are written to report.xlsx/report.ods in the current directory.

You can also set userdata options directly in behave.ini:

[behave.userdata]
report_columns = feature,scenario,status,duration,error
report_only_failed = false
report_delimiter = comma
report_clear_history = false
report_history_path = .behave-sheets-history.json
report_max_history = 100

Configuration Options

All options are passed via Behave's userdata (command-line -D or behave.ini):

Examples

Generate an XLSX report with only failed scenarios and a custom column set:

behave -f xlsx-modern -o report.xlsx \
  -D report_only_failed=true \
  -D report_columns=feature,scenario,status,error \
  -D report_max_history=50

Use a semicolon delimiter for CSV (useful in European locales):

behave -f csv-modern -o report.csv -D report_delimiter=semicolon

Clear history before a fresh run (e.g. after changing the test suite):

behave -f xlsx-modern -o report.xlsx -D report_clear_history=true

Store history in a custom location (e.g. outside the working directory):

behave -f xlsx-modern -o report.xlsx -D report_history_path=/tmp/behave-history.json

Available Columns

The report_columns option accepts any combination of the following column names (comma-separated):

Default columns: feature,scenario,status,duration,tags,error. Unknown column names are ignored; if none of the given names is valid, the defaults are used.

Automatic History & Trends

Every XLSX and ODS run is automatically appended to a JSON history file (.behave-sheets-history.json in the working directory by default); CSV output does not record history. The history feeds the Trends sheet, showing pass rate evolution across runs.

• report_history_path — custom location for the history file.
• report_clear_history — clears all previous entries before appending the current run (useful for fresh starts).
• report_max_history — limits the number of retained entries (oldest are dropped).

History is managed atomically (write to .tmp, then os.replace) to prevent corruption.

History file format

The history file is a JSON array of entry objects:

[
  {
    "run_id": "run_a1b2c3d4e5f6",
    "timestamp": "2025-01-15T10:30:00.123456+00:00",
    "total_features": 3,
    "total_scenarios": 15,
    "passed": 14,
    "failed": 1,
    "skipped": 0,
    "undefined": 0,
    "pass_rate": 93.3,
    "duration": 2.45
  }
]

Programmatic Usage

You can use the collector, writers, and history directly without Behave:

from behave_modern_sheets_report import Collector, CSVWriter, XLSXWriter, History
from pathlib import Path

# Collect results from Behave events
collector = Collector()
collector.start_feature(feature_obj)
collector.start_scenario(scenario_obj)
# Behave announces every step upfront, then reports one result per executed step
for step in scenario_steps:
    collector.start_step(step)
for step in executed_steps:
    collector.end_step(step)
collector.end_scenario()
collector.end_feature()
run_summary = collector.finalize()

# Write CSV (no extra dependencies needed)
with open("report.csv", "w", newline="") as f:
    CSVWriter.write(run_summary, f)

# Write XLSX (requires openpyxl)
history = History(max_entries=50)
trends = history.append(run_summary)
XLSXWriter.write(run_summary, Path("report.xlsx"), trends=trends)

This is useful for integrating the report generation into custom test runners or CI pipelines.

Architecture

Behave Runner
    │
    ├── CSVFormatter ──► Collector ──► RunSummary ──► CSVWriter ──► report.csv
    ├── XLSXFormatter ──► Collector ──► RunSummary ──► XLSXWriter ──► report.xlsx
    └── ODSFormatter ───► Collector ──► RunSummary ──► ODSWriter ───► report.ods
                                        │
                                        └──► History ──► .behave-sheets-history.json
                                                │
                                                └──► Trends sheet

Collector processes Behave events (feature, scenario, step, result) and builds a RunSummary. Writers serialize the summary into the target format. History persists run metrics between executions for trend analysis.

Key design decisions

• Pure data models — models.py has zero external dependencies. Dataclasses can be serialized to any format without importing Behave, openpyxl, or odfpy.
• Single Behave integration point — Collector is the only module that touches Behave objects. Everything else operates on pure dataclasses, making the writers and history fully testable without Behave.
• Opt-in dependencies — CSV works with stdlib alone. openpyxl and odfpy are only imported when their respective writer is called.
• Atomic file I/O — History writes to a .tmp file first, then uses os.replace for an atomic swap. This prevents corruption if the process is killed mid-write.

Ecosystem

Part of the behave-modern-* formatter family:

Contributing

Contributions are welcome! Please read the Contributing Guide and our Code of Conduct before submitting pull requests.

Development commands

make lint        # ruff check + format check
make typecheck   # mypy --strict
make test        # pytest with verbose output
make format      # ruff auto-fix + format
make build       # build sdist + wheel

Security

If you discover a security vulnerability, please refer to our Security Policy for responsible disclosure instructions.

Changelog

See CHANGELOG.md for release history and notable changes.

License

MIT — see LICENSE for full text.

Made with care by Mathias Paulenko