How it works¶

This page explains the internal architecture of behave-retry so you can understand exactly what happens when you call setup_retry.

Architecture overview¶

behave-retry works by monkey-patching behave.model.Scenario.run with a retry-aware wrapper. This is the same approach used by behave’s own plugin system and is the most reliable way to intercept scenario execution.

┌──────────────────────────────────────────────────┐
│                  behave runner                    │
│                                                   │
│  for each scenario:                               │
│    scenario.run(runner)  ← patched by behave-retry│
│      ┌─────────────────────────────────────────┐  │
│      │         patched_run wrapper             │  │
│      │                                          │  │
│      │  1. Load config & stats from context    │  │
│      │  2. Check retry eligibility (tags)      │  │
│      │  3. Call original_run(self, runner)     │  │
│      │  4. If failed → check retry conditions  │  │
│      │  5. If eligible → reset & retry         │  │
│      │  6. Record stats on final attempt       │  │
│      └─────────────────────────────────────────┘  │
└──────────────────────────────────────────────────┘

The patch lifecycle¶

1. `setup_retry(context, ...)`¶

Called in before_all. This function:

Creates a RetryConfig dataclass from the provided parameters.
Creates a RetryStats instance for tracking.
Stores both on the behave context object (_behave_retry_config, _behave_retry_stats, _behave_retry_attempts, _behave_retry_total).
Calls _patch_scenario_run(context) which:
- Imports behave.model.Scenario.
- Saves the original Scenario.run method.
- Replaces it with patched_run (a closure over context).
- Marks the patch with _behave_retry_patched = True to prevent double-patching.

2. `patched_run(self, runner)`¶

Called by behave for every scenario. This is where the retry loop lives.

Step-by-step flow¶

patched_run(scenario, runner)
│
├─ config or stats missing? → delegate to original_run
│
├─ max_for_scenario == 0? → delegate to original_run (no retry)
├─ should_retry_tag(tags) == False? → delegate to original_run
│
├─ attempt = 0
└─ loop:
     ├─ attempt += 1
     ├─ result = original_run(scenario, runner)
     ├─ store attempt count on context
     │
     ├─ passed? → record stats (if attempt > 1), return False
     │
     ├─ failed:
     │   ├─ check retry_on filter
     │   │   └─ exception doesn't match? → record stats, return True
     │   │
     │   ├─ check retry limit (attempt > max_for_scenario)
     │   │   └─ exhausted? → record stats, return True
     │   │
     │   ├─ check global budget (max_total_retries)
     │   │   └─ exhausted? → record stats, return True
     │   │
     │   ├─ increment global budget counter
     │   ├─ log retry attempt
     │   ├─ call on_retry callback (if set)
     │   ├─ sleep(delay)
     │   ├─ reset scenario state
     │   └─ continue loop

3. Scenario state reset¶

Before each retry, _reset_scenario_state is called. This:

Calls scenario.clear_status() (behave’s built-in reset) or sets scenario.status = None as fallback.
For each step in the scenario:
- Calls step.reset() if available (behave’s built-in step reset).
- Otherwise sets step.status = None.
- Clears step.exception, step.error_message, and step.error if they exist.

This ensures the scenario starts fresh on each retry — behave won’t skip steps that were already “passed” on a previous attempt.

4. `after_scenario_hook(context, scenario)`¶

Called in after_scenario. With the patched Scenario.run, the retry loop is handled automatically. This hook is kept for backward compatibility and tracks the attempt count on the context for scenarios that were never retried (ensuring every scenario has an entry in _behave_retry_attempts).

5. `retry_report(context)`¶

Called in after_all. Reads _behave_retry_stats from the context and returns a formatted summary string. Also logs the summary at INFO level.

Scenario key generation¶

Each scenario is identified by a unique key stored in _behave_retry_attempts and used in RetryStats. The key is generated by _get_scenario_key:

Condition	Key format	Example
`filename`, `line`, and `name` available	`filename:line:name`	`features/login.feature:5:Login with bob`
`filename` and `line` available, no `name`	`filename:line`	`features/login.feature:5`
Only `name` available	`name`	`Login with bob`
Nothing available	`str(scenario)`	`<Scenario object at 0x...>`

Including the name prevents key collisions between Scenario Outline examples that share the same file and line but have different names after placeholder substitution.

Exception extraction¶

When a scenario fails, behave-retry needs to determine what exception caused the failure. Two helpers handle this:

_get_last_exception(scenario) — iterates steps in reverse, finds the last failed step with an exception, and returns the exception instance.
_get_last_exception_type(scenario) — returns type(exception) or None.

Behave assigns Status.failed to AssertionError and Status.error to other exceptions. Both are treated as failures by _step_failed.

Idempotency¶

_patch_scenario_run checks for the _behave_retry_patched attribute on the original Scenario.run. If already patched, it returns immediately. This means calling setup_retry multiple times is safe — the second call updates the config on the context but doesn’t re-patch.

However, the closure in patched_run reads config dynamically via getattr(context, "_behave_retry_config"), so the latest config is always used.

Thread safety¶

Behave runs scenarios sequentially in a single thread. behave-retry is not designed for concurrent scenario execution and does not use any locking. This is consistent with behave’s own execution model.