behave-retry

Automatic retry for failed Behave scenarios — real re-execution, tag overrides, exception filtering, and flakiness stats.

Overview

Behave has no built-in retry mechanism. When a scenario fails due to flakiness — timing issues, network instability, race conditions — there’s no way to re-run it automatically. behave-retry fills that gap.

Key features

  • Global retry — retry all failed scenarios up to N times

  • Tag-filtered retry — only retry scenarios with specific tags

  • Exception-filtered retry — only retry on specific exception types (classes or string names)

  • Per-scenario override — @retry:N tag overrides global config, with Feature-level inheritance

  • Global retry budget — limit total retries across all scenarios

  • Retry delay and backoff — configurable delay with exponential backoff

  • On-retry callback — custom logic before each retry (cleanup, screenshots, logging)

  • Flakiness stats — human-readable summary and machine-readable JSON export

  • Scenario Outline support — unique keys per example, independent retry counts

  • Zero runtime dependencies — only behave needed for development

  • Type-safe — py.typed marker, full type hints, mypy clean

Quick example

# environment.py
from behave_retry import setup_retry, after_scenario_hook, retry_report

def before_all(context):
    setup_retry(context, max_retries=3)

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

def after_all(context):
    print(retry_report(context))

Where to start