Execution Report¶

The report module provides execution report collection, rendering, and serialization.

ReportEntry¶

class behave_priority.report.ReportEntry(index, feature_name, scenario_name, priority, status, duration, is_critical)[source]¶

Bases: object

Single scenario entry in the execution report.

Variables:

index – 1-based position in execution order.
feature_name – Name or filename of the parent feature.
scenario_name – Display name of the scenario.
priority – Resolved priority value.
status – Execution status ("passed", "failed", etc.).
duration – Execution time in seconds.
is_critical – Whether the scenario has the critical tag.

The ReportEntry dataclass represents a single scenario in the execution report. Each entry is immutable and hashable.

Fields¶

ReportEntry Fields¶
Field	Type	Description
`index`	`int`	1-based position in execution order.
`feature_name`	`str`	Name or filename of the parent feature.
`scenario_name`	`str`	Display name of the scenario.
`priority`	`int`	Resolved priority value.
`status`	`str`	Execution status: `"passed"`, `"failed"`, `"skipped"`, etc.
`duration`	`float`	Execution time in seconds.
`is_critical`	`bool`	Whether the scenario has the critical tag (including rule-level).

ReportSummary¶

class behave_priority.report.ReportSummary(total, passed, failed, skipped, undefined=0, untested=0, critical_total=0, critical_passed=0, critical_failed=0, critical_skipped=0, total_duration=0.0, skipped_duration=0.0, time_saved=0.0)[source]¶

Bases: object

Aggregate statistics from the report.

Variables:

total – Total number of recorded scenarios.
passed – Number of passed scenarios.
failed – Number of failed scenarios.
skipped – Number of skipped scenarios.
undefined – Number of undefined scenarios.
untested – Number of scenarios with a status not matching any known category.
critical_total – Total number of critical scenarios.
critical_passed – Number of passed critical scenarios.
critical_failed – Number of failed critical scenarios.
critical_skipped – Number of skipped critical scenarios.
total_duration – Sum of all scenario durations in seconds.
skipped_duration – Sum of skipped scenario durations in seconds.
time_saved – Estimated time saved by skipping scenarios, using priority-bucketed averages of executed scenario durations.

property pass_rate: float¶

Percentage of passed scenarios excluding skipped and undefined.

Returns:: Pass rate as a percentage (0.0 to 100.0).

The ReportSummary dataclass provides aggregate statistics across all report entries.

Properties¶

``time_saved``: Estimated time saved by fail-fast skipping. Since skipped scenarios have duration=0 (they never ran), the saved time is estimated using priority-bucketed averages: each skipped scenario’s estimated duration is the average duration of executed scenarios in the same priority bucket (buckets of 100), falling back to the global average.

time_saved = sum(avg(executed_in_bucket) for each skipped)

``pass_rate``: Percentage of passed scenarios excluding skipped and undefined ones. Returns 0.0 when no scenarios were executed.

pass_rate = (passed / (total - skipped - undefined)) * 100

PriorityReport¶

class behave_priority.report.PriorityReport(config)[source]¶

Bases: object

Collects and renders execution order with priorities and timing.

__init__(config)[source]¶

Initialize the report collector.

Parameters:: config (PriorityConfig) – Configuration that controls report behavior.

property entries: tuple[ReportEntry, ...]¶

Recorded scenario entries, in execution order.

Returns:: A tuple of ReportEntry objects.

record(*, scenario_name, feature_name, priority, status, duration, is_critical)[source]¶

Record a scenario execution result.

Parameters:

scenario_name (str) – Display name of the scenario.
feature_name (str) – Name or filename of the parent feature.
priority (int) – Resolved priority value.
status (str) – Execution status ("passed", "failed", etc.).
duration (float) – Execution time in seconds.
is_critical (bool) – Whether the scenario has the critical tag.

Return type:

None

render()[source]¶

Render the full report as a formatted string.

Column widths for Feature and Scenario names are computed dynamically from the actual content, with a maximum of 40 characters to avoid excessive width. Names longer than the computed width are truncated with ....

Return type:: str
Returns:: A human-readable report with a table of entries and summary.

summary()[source]¶

Compute aggregate statistics.

The time_saved estimation uses priority-bucketed averages: skipped scenarios are grouped into priority buckets (size 100) and each bucket’s average executed duration is used as the estimate. Buckets without executed scenarios fall back to the global average.

Return type:: ReportSummary
Returns:: A ReportSummary with counts, durations, and estimated time saved.

to_csv()[source]¶

Serialize report entries to a CSV string.

The summary is not included in CSV output. Each row represents one scenario entry.

Return type:: str
Returns:: A CSV string with a header row and one row per entry.

to_dict()[source]¶

Serialize report to a dictionary.

Return type:: dict[str, Any]
Returns:: A dict with "entries" and "summary" keys.

to_json(*, indent=2)[source]¶

Serialize report to a JSON string.

Parameters:: indent (int) – Number of spaces for indentation. Use 0 or negative for compact output.
Return type:: str
Returns:: A JSON string with "entries" and "summary" keys.

Methods¶

PriorityReport Methods¶
Method	Description
`record()`	Record a scenario execution result. Called by `after_scenario_hook`.
`render()`	Render the full report as a formatted string table.
`summary()`	Compute and return a `ReportSummary` with aggregate statistics.
`to_dict()`	Serialize the report to a dictionary (JSON-compatible).
`to_json()`	Serialize the report to a JSON string.
`to_csv()`	Serialize the entries to a CSV string (summary not included).

The entries property returns the recorded ReportEntry objects as an immutable tuple, in execution order.

Rendered Output¶

The render() method produces a human-readable table:

Priority Execution Report
=========================

  #  Priority  Feature   Scenario          Status    Duration
------------------------------------------------------------------
  1         1  Login     Successful login  passed       1.23s
  2         2  Login     Failed login      failed       0.45s
  3         3  Login     Account locked    skipped      0.00s

Summary:
  Critical: 0/1 passed
  Total: 1 passed, 1 failed, 1 skipped
  Time saved by fail-fast: 1.23s (estimated, 1 scenario(s) skipped)

Column widths for Feature and Scenario names are computed dynamically from the actual content, with a maximum of 40 characters. Names longer than the computed width are truncated with .... The minimum column width is the length of the header label ("Feature" or "Scenario") to ensure proper alignment.

Dictionary Serialization¶

The to_dict() method returns a JSON-compatible dictionary:

{
    "entries": [
        {
            "index": 1,
            "feature_name": "Login",
            "scenario_name": "Successful login",
            "priority": 1,
            "status": "passed",
            "duration": 1.23,
            "is_critical": False
        },
        ...
    ],
    "summary": {
        "total": 3,
        "passed": 1,
        "failed": 1,
        "skipped": 1,
        "undefined": 0,
        "untested": 0,
        "critical_total": 1,
        "critical_passed": 0,
        "critical_failed": 0,
        "critical_skipped": 1,
        "total_duration": 1.68,
        "skipped_duration": 0.0,
        "pass_rate": 50.0,
        "time_saved": 1.23
    }
}

This format is suitable for REST API responses, file storage, or further processing.

Examples¶

Recording scenarios:

from behave_priority import PriorityConfig, PriorityReport

config = PriorityConfig()
report = PriorityReport(config)

report.record(
    scenario_name="Login test",
    feature_name="Auth",
    priority=1,
    status="passed",
    duration=1.5,
    is_critical=True,
)

Getting summary statistics:

summary = report.summary()
print(f"Pass rate: {summary.pass_rate:.1f}%")
print(f"Time saved: {summary.time_saved:.2f}s")

Exporting to JSON:

import json

data = report.to_dict()
json_str = json.dumps(data, indent=2)