Configuration¶

The PriorityConfig dataclass controls all behavior of behave-priority. It is immutable (frozen) and validated at construction time.

class behave_priority.config.PriorityConfig(order=False, reverse=False, priority_tag=None, stop_after_failures=None, stop_on_critical=False, critical_tag='critical', default_priority=999, report=False, report_format='text', parallel_coord=False)[source]¶

Bases: object

Immutable configuration for priority execution.

All configuration is programmatic — no CLI flags.

Variables:

order – Sort scenarios by priority (highest first).
reverse – Reverse sort order (lowest priority first).
priority_tag – Tag name to run first (e.g. "smoke").
stop_after_failures – Stop after N failed scenarios, or None to disable.
stop_on_critical – Stop if any critical scenario fails.
critical_tag – Tag name that marks a scenario as critical.
default_priority – Priority for scenarios without a priority tag.
report – Print execution report after run.
report_format – Output format for the report ("text", "json", or "csv").
parallel_coord – Enable cross-process fail-fast coordination via BEHAVE_PRIORITY_COORD_DIR env var. When True and the env var is set, workers share failure state via a file-based coordinator.

Raises:

ValueError – If stop_after_failures is not a positive integer (or None), if critical_tag or priority_tag is an empty string, if default_priority is negative, or if report_format is not one of "text", "json", "csv".

Configuration Fields¶

Configuration Options¶
Field	Type	Default	Description
`order`	`bool`	`False`	Sort scenarios by priority (highest first). When `True`, scenarios are reordered so that lower priority numbers execute first.
`reverse`	`bool`	`False`	Reverse sort order. When `True`, higher priority numbers execute first. Useful when priority numbers represent severity rather than execution order.
`priority_tag`	`str \| None`	`None`	Tag name to run first (e.g. `"smoke"`). Scenarios with this tag are moved to the front of execution, before any priority-based sorting.
`stop_after_failures`	`int \| None`	`None`	Stop after N failed scenarios. `None` disables this fail-fast strategy. Must be a positive integer if provided.
`stop_on_critical`	`bool`	`False`	Stop execution if any scenario tagged `@critical` fails.
`critical_tag`	`str`	`"critical"`	Tag name that marks a scenario as critical. Both the tag and the `critical_tag` config value are normalized (stripped of `@` prefix and whitespace) before comparison.
`default_priority`	`int`	`999`	Priority assigned to scenarios without any priority tag. Must be non-negative.
`report`	`bool`	`False`	Print the execution report after the run via `priority_report()`.
`report_format`	`"text" \| "json" \| "csv"`	`"text"`	Output format for the report. `"json"` includes entries and summary; `"csv"` writes one row per scenario entry.
`parallel_coord`	`bool`	`False`	Enable cross-process fail-fast coordination via the `BEHAVE_PRIORITY_COORD_DIR` environment variable.

Validation¶

The following validations are performed at construction time:

stop_after_failures must be a positive integer or None (booleans and floats are rejected).
critical_tag must not be an empty string.
priority_tag must not be an empty string if provided (None is valid).
default_priority must be non-negative.
report_format must be one of "text", "json", "csv".

Invalid values raise ValueError with a descriptive message.

Examples¶

Basic priority ordering:

from behave_priority import PriorityConfig

config = PriorityConfig(order=True)

Priority ordering with fail-fast:

config = PriorityConfig(
    order=True,
    stop_after_failures=3,
    report=True,
)

Smoke tests first, stop on critical failure:

config = PriorityConfig(
    order=True,
    priority_tag="smoke",
    stop_on_critical=True,
    critical_tag="critical",
    report=True,
)

Reversed order (highest priority number first):

config = PriorityConfig(order=True, reverse=True)

Custom default priority:

config = PriorityConfig(order=True, default_priority=100)

Immutability¶

PriorityConfig is a frozen dataclass with slots=True. Once created, its fields cannot be modified:

config = PriorityConfig(order=True)
config.order = False  # Raises FrozenInstanceError

This ensures that configuration remains consistent throughout the test run.