Behave Modern HTML Report

The modern, beautiful, single-file HTML report formatter for Behave. Dark mode, charts, instant search, attachments, zero external requests.

behave-modern-html-report is a drop-in formatter for Behave that produces a single, self-contained HTML file — everything (CSS, JS, fonts, icons, attachments) is embedded so the report works offline, on any machine, forever.

Features

• 🌓 Dark / Light / Auto themes, modern Material-3 inspired UI
• 📊 Interactive charts (status pie, duration histogram, slowest scenarios, tag pass rate, timeline) — pure vanilla JS, no Chart.js CDN
• 🏷️ Tag analytics page: per-tag counts, pass rate, duration, and a dedicated chart
• 📋 Gherkin Rules support: scenarios under a Rule are grouped and tagged correctly (Behave 1.3.x)
• 🔍 Instant client-side search across features, scenarios, steps and tags
• 🎚️ Filter by status with one click
• 📁 Expandable features → scenarios → steps with rich metadata
• 🧯 Modern error viewer with copy-to-clipboard tracebacks
• 🖼️ Attachments: images (with lightbox), JSON, text, binaries
• 🚀 Copy-reproduce-command per scenario (behave features/example.feature:3)
• 📊 Inline step duration bars to spot slow steps at a glance
• ♿ Accessible: keyboard navigation, ARIA labels, reduced-motion support
• 📦 Single HTML file, works offline, no web server, no CDN
• 📌 Fixed sidebar navigation that stays in place while content scrolls
• 🧩 Clean architecture — formatter / collector / models / renderer separation, fully testable
• 🛠️ Extensible — custom CSS/JS, custom title/logo/company, JSON sidecar, future plugin system
• 📋 Step catalog — static analysis formatter that extracts all step definitions with patterns, params, source and metrics

Installation

pip install behave-modern-html-report

Quick start

In your project's behave.ini (or setup.cfg):

[behave.formatters]
modern-html = behave_modern_html_report.formatter:ModernHTMLFormatter
steps-catalog = behave_modern_html_report.step_catalog_formatter:StepCatalogFormatter

Then run:

behave -f modern-html -o report.html

Open report.html in any browser. Done.

You can also generate a step catalog (static analysis of your step definitions, no test execution needed):

behave -f steps-catalog -o steps.html

Configuration

All reporter options are read from behave's userdata section. Set them in behave.ini, setup.cfg, or programmatically from environment.py:

[behave.userdata]
bmr.title         = My Awesome Suite
bmr.company       = Acme Inc.
bmr.logo          = https://example.com/logo.svg
bmr.favicon       = https://example.com/favicon.ico
bmr.theme         = auto          ; auto | dark | light
bmr.primary_color = #3b82f6
bmr.accent_color  = #22c55e
bmr.default_view  = dashboard     ; dashboard | features | scenarios | ...
bmr.hidden_views    = rules,statistics
bmr.expand_by_default = false
bmr.max_slowest   = 10
bmr.show_copy_command = true
bmr.show_environment_vars = true
bmr.footer_text   = Build #12345
bmr.link_to_ci    = https://ci.example.com/build/12345
bmr.json_sidecar  = true          ; writes report.json next to report.html
bmr.custom_css    = path/to/extra.css
bmr.custom_js     = path/to/extra.js

Available options:

• bmr.title — report title (default Behave Modern Report).
• bmr.company — company name shown under the title.
• bmr.logo / bmr.favicon — URL or base64 data URI for a logo/favicon.
• bmr.theme — auto, dark or light.
• bmr.primary_color / bmr.accent_color — override the report colors.
• bmr.default_view — initial view (dashboard, features, scenarios, ...).
• bmr.hidden_views — comma-separated views to hide (e.g. rules,statistics).
• bmr.expand_by_default — expand all sections on load.
• bmr.max_slowest — number of slowest scenarios on the dashboard.
• bmr.show_copy_command — show the copy reproduce command button.
• bmr.show_environment_vars — show the environment variables card.
• bmr.footer_text — custom footer line.
• bmr.link_to_ci — "View in CI" button URL.
• bmr.json_sidecar — write report.json next to the HTML report.
• bmr.custom_css / bmr.custom_js — embed custom CSS/JS files.
• bmr.steps_dir — directory to scan for step definitions when using the steps-catalog formatter (default features/steps).

See docs/configuration.md for the full reference.

Behave 1.3.x and Gherkin Rules compatibility

behave-modern-html-report is tested against Behave 1.3.x and fully supports the Gherkin Rule keyword.

• Scenarios under a Rule keep their parent rule name and inherit their Rule tags correctly.
• Extended final statuses (error, hook_error, cleanup_error, xfailed, xpassed, pending_warn) are normalised and displayed in the UI.
• Error-like statuses are grouped as failures for feature status and tag analytics.

Feature: Checkout

  Rule: Payment required
    @payment
    Scenario: Card payment succeeds
      Given the user has items in cart
      When they pay with a valid card
      Then the order is confirmed

Attachments from your environment.py

Use the public helper API — no need to reach into the formatter:

from behave_modern_html_report import attach_screenshot, attach_text, log

def after_step(context, step):
    if step.status == "failed":
        attach_screenshot(context, context.browser, name="failure.png")
        attach_text(context, str(step.exception), name="error.txt")
        log(f"URL at failure: {context.browser.current_url}")

The helpers also work with Playwright, Selenium, PIL images, bytes, files, and JSON data.

Step Catalog

The package also includes a step catalog formatter that statically analyses your features/steps/ directory and produces an HTML catalog of all step definitions — without running the suite.

Register it in behave.ini:

[behave.formatters]
steps-catalog = behave_modern_html_report.step_catalog_formatter:StepCatalogFormatter

Then run:

behave -f steps-catalog -o steps.html

The catalog includes:

• All @given, @when, @then and @step decorated functions.
• Step pattern, function name, file path and line number.
• Extracted parameters from {placeholder} patterns.
• Function docstrings and source code snippets.
• Metrics: total steps, by keyword, by file, parameterised, documented, regex.
• Searchable, sortable table with keyword filters.
• Detail panel showing the full source code of each step.

You can customise the steps directory with bmr.steps_dir:

[behave.userdata]
bmr.steps_dir = features/steps

Programmatic usage

from behave_modern_html_report import scan_directory
from behave_modern_html_report.step_catalog_formatter import render_catalog
from pathlib import Path

catalog = scan_directory(Path("features/steps"))
html = render_catalog(catalog, title="My Step Catalog")
Path("steps.html").write_text(html, encoding="utf-8")

Screenshots

Generate a demo without running Behave

python examples/demo_generator/generate_demo.py

This builds examples/demo_generator/demo-report.html with a realistic-looking suite — useful for previews, screenshots, and design iteration.

Report screenshots

Architecture

behave events
    │
    ▼
 formatter.py ── thin adapter
    │
    ▼
 collector.py ── builds the model tree
    │
    ▼
   models.py  ── pure dataclasses
                (Execution → Feature → Rule-aware Scenario → Step)
    │
    ▼
 statistics.py ── aggregates counters, durations, buckets
    │
    ▼
 renderer.py  + templates/ + assets/  ── Jinja2 → single HTML file

The renderer is independent of Behave, so any tool that can produce an Execution object (e.g. a JSON loader) can use it.

Development

pip install -e ".[dev]"
pytest
ruff check .

Documentation

• Usage — installation, basic configuration, and running.
• Configuration — all reporter options and userdata keys.
• Report views — what each view shows.
• Step catalog — static analysis of step definitions.
• Examples — demo generator and functional Behave project.
• Architecture — how the formatter is structured.
• Contributing — local setup, checks, and conventions.

License

MIT © Mathias Paulenko