Configuration Guide¶

This guide covers all configuration options in detail.

Basic Configuration¶

The simplest configuration enables priority ordering:

setup_priority(context, order=True)

This sorts scenarios by @priority(N) tags (lowest first) and features by their best scenario’s priority.

Full Configuration¶

All available options:

setup_priority(
    context,
    order=True,              # Sort by priority
    reverse=False,           # Reverse sort (highest first)
    priority_tag="smoke",    # Run @smoke scenarios first
    stop_after_failures=3,   # Stop after 3 failures
    stop_on_critical=True,   # Stop if @critical fails
    critical_tag="critical", # Custom critical tag name
    default_priority=999,    # Priority for untagged scenarios
    report=True,             # Print report after run
    report_format="text",    # "text" | "json" | "csv"
    parallel_coord=False,    # Cross-process fail-fast coordination
)

Option Details¶

order¶

When True, scenarios within each feature are sorted by their resolved priority. Features are also sorted by their best (lowest) scenario priority.

When False, no sorting occurs. Scenarios run in behave’s default order (file order), unless reverse or priority_tag are set — both options also enable sorting.

reverse¶

When True, the sort order is reversed: higher priority numbers run first. This is useful when priority represents severity (e.g. priority 5 = most severe = should run first).

Setting reverse=True enables sorting on its own; it does not require order=True.

priority_tag¶

A tag name (without @) that marks scenarios to run first, regardless of their priority number. Scenarios with this tag get a primary sort key of 0, while all others get 1.

Common use case: priority_tag="smoke" runs all @smoke scenarios before any other scenarios, even if they have higher priority numbers.

Setting priority_tag enables sorting on its own; it does not require order=True.

stop_after_failures¶

Stop execution after N scenarios fail. Remaining scenarios are skipped and recorded in the report.

Set to None to disable this fail-fast strategy.

Must be a positive integer if provided. 0 and negative values raise ValueError.

stop_on_critical¶

When True, execution stops immediately after any scenario tagged @critical (or the configured critical_tag) fails.

This is useful for smoke tests where a critical failure means the rest of the suite is meaningless.

critical_tag¶

The tag name that marks a scenario as critical. Defaults to "critical".

Both the tag and this config value are normalized (stripped of @ prefix and whitespace) before comparison, so "@critical" and "critical" are equivalent.

default_priority¶

The priority assigned to scenarios without any @priority(N) tag. Defaults to 999, which places untagged scenarios last.

Must be non-negative.

report¶

When True, the execution report is printed to stdout via priority_report(context) in after_all.

The report can also be accessed programmatically via get_report(context) regardless of this setting.

The report is written to the real stdout, so it stays visible even when behave captures output during hooks (the default).

report_format¶

Controls the output format of the report printed by priority_report:

"text" (default) — human-readable table with summary.
"json" — machine-readable JSON with entries and summary.
"csv" — one row per scenario entry (no summary).

parallel_coord¶

When True, workers coordinate fail-fast across processes using JSON files in the directory named by the BEHAVE_PRIORITY_COORD_DIR environment variable. If the variable is not set, a warning is emitted and coordination is disabled. See parallel for details.

Environment Variables¶

The following environment variables can be used as defaults when setup_priority is called without the corresponding argument (or with the argument set to None):

Environment variables¶
Variable	Type	Default	Argument
`BEHAVE_PRIORITY_ORDER`	`0` / `1`	`0`	`order`
`BEHAVE_PRIORITY_REVERSE`	`0` / `1`	`0`	`reverse`
`BEHAVE_PRIORITY_FAIL_FAST`	`0` / `1`	`0`	`stop_on_critical`
`BEHAVE_PRIORITY_STOP_AFTER`	integer	(disabled)	`stop_after_failures`
`BEHAVE_PRIORITY_REPORT`	`0` / `1`	`0`	`report`
`BEHAVE_PRIORITY_PARALLEL_COORD`	`0` / `1`	`0`	`parallel_coord`
`BEHAVE_PRIORITY_COORD_DIR`	string	(none)	(used by `ParallelCoordinator`)

Explicit arguments always take precedence over environment variables. This is useful for CI runners or wrappers that invoke behave and want to control priority ordering and fail-fast behavior via the shell.

Example:

export BEHAVE_PRIORITY_ORDER=1
export BEHAVE_PRIORITY_FAIL_FAST=1
export BEHAVE_PRIORITY_STOP_AFTER=3
export BEHAVE_PRIORITY_REPORT=1
behave

Validation Errors¶

Invalid configuration raises ValueError at construction time:

PriorityConfig(stop_after_failures=0)    # ValueError
PriorityConfig(stop_after_failures=-1)   # ValueError
PriorityConfig(critical_tag="")          # ValueError
PriorityConfig(priority_tag="")          # ValueError
PriorityConfig(default_priority=-1)      # ValueError

Immutability¶

PriorityConfig is frozen and uses slots=True for memory efficiency. Once created, it cannot be modified. This ensures consistent behavior throughout the test run.

Common Patterns¶

Smoke tests first with fail-fast:

setup_priority(
    context,
    order=True,
    priority_tag="smoke",
    stop_on_critical=True,
    report=True,
)

CI pipeline with failure threshold:

setup_priority(
    context,
    order=True,
    stop_after_failures=5,
    report=True,
)

Severity-based ordering (highest number = most severe = runs first):

setup_priority(
    context,
    order=True,
    reverse=True,
    report=True,
)

No sorting, just fail-fast and reporting:

setup_priority(
    context,
    stop_after_failures=1,
    report=True,
)