behave-priority

Priority-based execution for Behave BDD. Execute scenarios ordered by priority, with fail-fast and smoke-first support.

Problem

Behave executes scenarios in file order. There is no way to:

• Run critical tests first
• Stop after N failures (intelligent fail-fast)
• Run smoke tests before regression
• Guarantee coverage when time is limited

In CI, if critical tests fail, you waste time waiting for the full regression suite to finish.

Solution

behave-priority reorders scenario execution by priority tags and provides fail-fast controls — all configured programmatically in environment.py, no CLI flags needed.

Features

Priority tags

• @priority(1) tag on scenarios — lower number = higher priority
• @feature-priority(1) at feature level — applies to all scenarios in the feature
• Scenario-level @priority(N) overrides feature-level priority
• Scenarios without priority tag default to lowest priority (executed last)

Execution ordering

• order=True — executes scenarios from highest to lowest priority
• priority_tag="smoke" — executes scenarios with that tag first, then the rest
• reverse=True — executes lowest priority first (useful for debugging)

Fail-fast

• stop_after_failures=N — stops execution after N failed scenarios
• stop_on_critical=True — stops if any @critical scenario fails
• Combines with order=True: run critical first, stop if they fail, skip regression

Parallel coordination

When running with behave --parallel=N, each worker is a separate process. By default, fail-fast is per-worker only. To coordinate fail-fast across all workers:

1. Set the BEHAVE_PRIORITY_COORD_DIR environment variable to a shared directory path
2. Pass parallel_coord=True to setup_priority

export BEHAVE_PRIORITY_COORD_DIR=/tmp/behave_priority_coord
behave --parallel=4

setup_priority(
    context,
    order=True,
    stop_after_failures=3,
    parallel_coord=True,
)

Each worker writes its failure state to a JSON file in the coordination directory. stop_after_failures and stop_on_critical are evaluated globally across all workers. Call cleanup_parallel_coord(context) in after_all to remove the worker's file.

Reporting

• report=True — prints execution order with priorities and timing
• report_format="text" (default) — human-readable table with summary
• report_format="json" — machine-readable JSON with entries and summary
• report_format="csv" — CSV with one row per scenario entry
• Shows: scenario name, priority value, status (passed/failed/skipped), duration
• Summary: how many critical passed, how many failed, total time saved by fail-fast
• time_saved estimation uses priority-bucketed averages (scenarios grouped by priority range 0-99, 100-199, etc.)

Example with JSON output for CI/CD integration:

setup_priority(
    context,
    order=True,
    report=True,
    report_format="json",
)

Installation

pip install behave-priority

For development:

pip install -e ".[dev]"

Quick start

In your features/environment.py:

from behave_priority import (
    setup_priority,
    before_scenario_hook,
    after_scenario_hook,
    priority_report,
)


def before_all(context):
    setup_priority(
        context,
        order=True,
        stop_after_failures=3,
        stop_on_critical=True,
        report=True,
    )


def before_scenario(context, scenario):
    before_scenario_hook(context, scenario)


def after_scenario(context, scenario):
    after_scenario_hook(context, scenario)


def after_all(context):
    priority_report(context)

In your .feature files:

Feature: User authentication

  @priority(1)
  @critical
  Scenario: Login with valid credentials
    Given a registered user
    When the user logs in
    Then the user should be authenticated

  @priority(2)
  Scenario: Login with invalid password
    Given a registered user
    When the user logs in with wrong password
    Then the login should fail

  @priority(5)
  Scenario: Remember me checkbox
    Given a registered user
    When the user checks remember me
    Then the session should persist

API reference

setup_priority(context, **kwargs)

Configures priority execution in before_all. All parameters are optional.

Configuration can be passed explicitly or via environment variables when arguments are None.

Environment variables are only read when the argument is not provided (or passed as None). Explicit arguments take precedence.

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

Hook functions

• before_scenario_hook(context, scenario) — skips scenario if fail-fast triggered
• after_scenario_hook(context, scenario) — records result, checks fail-fast
• priority_report(context) — prints execution report in after_all
• cleanup_parallel_coord(context) — removes worker file from coordination directory in after_all

PriorityConfig

Immutable frozen dataclass with all configuration options. Can be constructed directly for advanced use cases.

Parser functions

• parse_priority(tags) -> int | None — parse @priority(N) from a tag list
• parse_feature_priority(tags) -> int | None — parse @feature-priority(N) from a tag list
• resolve_priority(scenario_tags, feature_tags, config, rule_tags=None) -> int — resolve effective priority (scenario > rule > feature > default)
• is_critical(tags, critical_tag) -> bool — check if scenario is critical

Exceptions

• PriorityError — base exception for all behave-priority errors
• PriorityParseError — raised when a priority tag has invalid syntax

Architecture

behave_priority/
├── __init__.py          # Public exports
├── exceptions.py        # PriorityError, PriorityParseError
├── config.py            # PriorityConfig (frozen dataclass)
├── parser.py            # Tag priority parsing
├── sorter.py            # ScenarioSorter — reorders behave's runner
├── hooks.py             # setup_priority, hook functions, PriorityState
├── parallel.py          # ParallelCoordinator — cross-process fail-fast
└── report.py            # PriorityReport, ReportEntry, ReportSummary

How it works

1. before_all: setup_priority() reads config, sorts features and scenarios by priority
2. before_scenario: hook skips scenario if fail-fast was triggered
3. after_scenario: hook records result, checks fail-fast conditions
4. after_all: priority_report() prints execution report if enabled

Use cases

1. CI critical-first: Run @priority(1) scenarios first. If any fail, stop immediately. Don't waste 20 minutes on regression.
2. Smoke tests: Tag smoke tests @priority(1) @critical, run with stop_on_critical=True. Get smoke results in 30 seconds.
3. Time-limited runs: In PR pipelines with time budget, order=True ensures most important tests run first.
4. Debugging: reverse=True runs obscure/edge-case tests first while you're fresh.

Requirements

• Python >= 3.11
• behave >= 1.2.6

Development

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check behave_priority/ tests/

# Type check
mypy --strict behave_priority/

# Coverage
pytest --cov=behave_priority --cov-report=term-missing

Limitations

Parallel execution (--parallel)

When behave runs with --parallel=N, each worker process gets its own isolated PriorityState. This has the following consequences:

• Scenario reordering: Each worker sorts only its own subset of scenarios. Global priority ordering across workers is not guaranteed. A @priority(1) scenario assigned to worker 2 may run after a @priority(5) scenario in worker 1.
• Fail-fast (stop_after_failures): By default, only stops scenarios within the same worker. With parallel_coord=True and BEHAVE_PRIORITY_COORD_DIR set, failure counts are aggregated globally across all workers. See Parallel coordination.
• Critical stop (stop_on_critical): By default per-worker only. With parallel_coord=True, a critical failure in any worker triggers stop in all workers.
• Counters: failed_count, executed_count, critical_failed, and should_stop are all per-process. The final report reflects only the worker that generated it.
• Reports: Generated independently per worker. Each worker prints its own report covering only the scenarios it executed. There is no merged or aggregated report.
• time_saved estimation: Inaccurate in parallel mode. The estimation assumes sequential execution; with N workers, skipped scenarios in one worker overlap with execution in others.
• priority_tag: Scenarios matching the priority tag are sorted first within each worker, but not globally across workers.

License

MIT