Tag Priority Parsing¶

The parser module provides functions for extracting priority values from behave tag lists and resolving the effective priority for a scenario.

class behave_priority.parser.Taggable(*args, **kwargs)[source]¶

Bases: Protocol

Protocol for objects with tags (Scenario, Feature).

Variables:: tags (list[str]) – List of tag strings as behave stores them (without ‘@’ prefix).

behave_priority.parser.parse_priority(tags: list[str]) → int | None[source]¶

Parse @priority(N) from a tag list.

Parameters:: tags – List of tag strings (without ‘@’ prefix, as behave stores them).
Returns:: Priority integer, or None if no priority tag found.
Raises:: PriorityParseError – If a priority tag exists but has invalid syntax.

behave_priority.parser.parse_feature_priority(tags: list[str]) → int | None[source]¶

Parse @feature-priority(N) from a tag list.

Same semantics as parse_priority but for feature-level tags.

Parameters:: tags – List of tag strings (without ‘@’ prefix, as behave stores them).
Returns:: Priority integer, or None if no feature-priority tag found.
Raises:: PriorityParseError – If a feature-priority tag exists but has invalid syntax.

behave_priority.parser.resolve_priority(scenario_tags: list[str], feature_tags: list[str], config: PriorityConfig, rule_tags: list[str] | None = None) → int[source]¶

Resolve effective priority for a scenario.

Precedence: scenario > rule > feature > default.

Parameters:

scenario_tags – Tags on the scenario (without ‘@’ prefix).
feature_tags – Tags on the parent feature (without ‘@’ prefix).
config – Configuration containing the default priority fallback.
rule_tags – Tags on the parent rule (Gherkin v6), if any.

Returns:

The effective priority integer for the scenario.

behave_priority.parser.is_critical(tags: list[str], critical_tag: str = 'critical') → bool[source]¶

Check if a tag list contains the critical tag.

Both the tags and critical_tag are normalized by stripping a leading ‘@’ prefix and whitespace before comparison.

Parameters:

tags – List of tag strings to search.
critical_tag – The tag name that marks a scenario as critical. Defaults to "critical".

Returns:

True if the critical tag is present in the tag list.

Tag Syntax¶

Priority tags use a function-like syntax inside Gherkin tags:

Tag Patterns¶
Pattern	Scope	Description
`@priority(N)`	Scenario, Rule	Sets priority to `N` (an integer). Lower numbers run first.
`@feature-priority(N)`	Feature	Sets the default priority for all scenarios in the feature.

Both positive and negative integers are accepted:

@priority(1)     # Valid
@priority(0)     # Valid
@priority(-5)    # Valid
@priority(abc)   # Invalid — raises PriorityParseError
@priority(1.5)   # Invalid — raises PriorityParseError

Tag Normalization¶

Tags are normalized before parsing:

Leading/trailing whitespace is stripped.
Leading @ characters are removed (behave stores tags without @).

This means " @priority(1) " and "@priority(1)" and "priority(1)" are all equivalent.

Priority Resolution¶

resolve_priority() determines the effective priority for a scenario by checking tags at multiple levels:

Scenario @priority(N)  →  use N
        ↓ (not found)
Rule @priority(N)      →  use N
        ↓ (not found)
Feature @feature-priority(N)  →  use N
        ↓ (not found)
config.default_priority  →  use default (999)

This cascade ensures that scenarios can override rule-level priorities, which in turn override feature-level priorities.

Critical Tag Detection¶

is_critical() checks whether a tag list contains the configured critical tag. Both the tags and the critical_tag parameter are normalized (stripped of @ and whitespace) before comparison:

from behave_priority import is_critical

is_critical(["critical"])            # True
is_critical(["@critical"])           # True
is_critical([" critical "])          # True
is_critical(["smoke"])               # False
is_critical(["critico"], "critico")  # True (custom critical tag)

Protocol¶

The Taggable protocol defines the minimum interface required for tag-based operations. Any object with a tags attribute (a list of strings) satisfies this protocol.

Examples¶

Parsing scenario priority:

from behave_priority import parse_priority

parse_priority(["smoke", "priority(1)"])      # → 1
parse_priority(["priority(3)", "priority(1)"])  # → 3 (first match)
parse_priority(["smoke"])                      # → None
parse_priority(["priority(abc)"])              # → raises PriorityParseError

Resolving effective priority:

from behave_priority import PriorityConfig, resolve_priority

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

# Scenario tag wins
resolve_priority(["priority(1)"], ["feature-priority(10)"], config)
# → 1

# Rule tag wins over feature
resolve_priority([], ["feature-priority(10)"], config, rule_tags=["priority(3)"])
# → 3

# Feature tag wins over default
resolve_priority([], ["feature-priority(10)"], config)
# → 10

# Default fallback
resolve_priority([], [], config)
# → 999