behave-doctor

Lint, diagnose, and analyze the impact of changes in your Behave BDD test suites — without running a single test.

behave-doctor inspects your Behave .feature files and Python step definitions without executing them, surfacing issues like unused step definitions, undefined steps, oversized features, inconsistent tags, and circular import dependencies — before they slow down your test suite or confuse your team.

It also includes an impact analysis command: tell it which files you changed, and it tells you exactly which scenarios are affected — so you can run only the tests that matter instead of the full suite.

Why behave-doctor?

Behave suites grow organically. Over time:

• Step definitions drift from feature files — unused definitions pile up, undefined steps cause runtime failures.
• Tags accumulate without consistency — @SmokeTest, @smoke_test, and @smoke-test all coexist, breaking tag filters.
• Features balloon in size — 50-scenario features become impossible to review or maintain.
• Circular imports between step modules cause ImportError at runtime.
• No visibility into suite health — how many steps are defined? How many are actually used? How complex are your scenarios?

behave-doctor catches all of these statically — no test execution required, no side effects, no network calls. It parses .feature files with behave-model and analyzes Python step definitions with the AST — never importing or executing them.

Features

• 20 diagnostic rules across 5 categories:
  • Structure (BD101-104) — feature, scenario, step, and tag counts.
  • Quality (BD201-205) — duplicate definitions, missing tags, oversized features, inconsistent tag casing, ambiguous step matches.
  • Coverage (BD301-305) — unused step definitions, undefined steps, unused tags, orphan scenarios, unparseable feature files.
  • Complexity (BD401-403) — scenario step count, step parameter count, feature file size.
  • Dependencies (BD501-503) — circular imports, unused imports, missing step modules.
• Impact analysis — given a list of changed .py or .feature files, determines which scenarios are affected and outputs names suitable for behave --name, JSON, or human-readable text.
• 4 output formats: human-readable text (with ANSI colors), JSON, SARIF 2.1.0 for GitHub Code Scanning, and names for impact analysis.
• Minimal runtime dependencies — only behave/behave-model (parsing and matching) and typer (CLI). Pure Python, fully typed, mypy --strict clean, ruff clean.
• Configurable via [tool.behave-doctor] in pyproject.toml — per-rule thresholds, enable/disable, severity filtering, tag exclusions.
• Python API for embedding in custom tooling, IDE plugins, or CI integrations.
• CLI with scan, impact, list-rules, explain, stats, and graph subcommands.
• 97% test coverage — 313 tests across unit and integration suites.

Installation

pip install behave-doctor

Requirements: Python 3.11+. The behave and behave-model packages (for .feature parsing and step matching) and typer (for the CLI) are installed automatically.

Quick start

behave-doctor scan .

Scanning . ...
Found 12 features, 47 scenarios, 213 steps, 89 step definitions.

BD101  INFO      12 features found
BD102  INFO      47 scenarios found
BD103  INFO      213 steps found
BD201  ERROR     Duplicate step definition for pattern 'the user is logged in' in: ...
BD301  WARNING   Unused step definition: "the user clicks submit"  (features/steps/auth.py:42)
BD302  ERROR     Undefined step: "Given the database is seeded"  (features/login.feature:18)

3 errors, 1 warning in 0.42s

Exit codes: 0 = clean, 1 = issues found, 2 = scan error.

Impact analysis

Tell behave-doctor which files you changed, and it tells you which scenarios are affected — so you can run only the tests that matter.

# Which scenarios are affected by changes to login_steps.py?
behave-doctor impact . --changed-files features/steps/login_steps.py

Impact analysis: 1 changed files

Changed files:
  - /path/to/features/steps/login_steps.py (4 step definitions)

Affected scenarios (4):
  /path/to/features/login.feature:3  Successful login
  /path/to/features/login.feature:11  Failed login
  /path/to/features/search.feature:5  Search by keyword
  /path/to/features/search.feature:12  Search with filter

Affected features (2):
  /path/to/features/login.feature
  /path/to/features/search.feature

Get scenario names for behave --name:

behave-doctor impact . --changed-files features/steps/login_steps.py --format names

Successful login
Failed login
Search by keyword
Search with filter

Pipe directly to Behave:

behave-doctor impact . --changed-files features/steps/login_steps.py --format names | xargs -I{} behave --name "{}"

JSON output for CI integration:

behave-doctor impact . --changed-files features/steps/login_steps.py --format json

Impact analysis understands Background steps — if a changed step definition is used in a feature's Background, all scenarios in that feature are affected.

Rules

Explore rules from the CLI:

behave-doctor list-rules          # list all 20 rules
behave-doctor explain BD301       # explain a specific rule

Configuration

All options have sensible defaults — configuration is optional.

# pyproject.toml
[tool.behave-doctor]
features_dir = "features/"          # default: features/
steps_dir = "features/steps/"       # default: features/steps/
min_severity = "info"               # default: info (show errors, warnings, and info)
exclude_tags = ["@smoke", "@wip"]   # tags excluded from BD303

[tool.behave-doctor.rules.BD101]    # disable a rule
enabled = false

[tool.behave-doctor.rules.BD203]    # adjust a threshold
max_scenarios = 15

[tool.behave-doctor.rules.BD401]
max_steps = 8

[tool.behave-doctor.rules.BD402]
max_params = 3

[tool.behave-doctor.rules.BD403]
max_lines = 200

CLI flags override config file values:

behave-doctor scan . --severity error --rules BD301,BD302 --exclude-rules BD101

Output formats

# Human-readable (default, with ANSI colors)
behave-doctor scan . --format text

# JSON for CI integration and custom tooling
behave-doctor scan . --format json

# SARIF 2.1.0 for GitHub Code Scanning
behave-doctor scan . --format sarif -o behave-doctor.sarif

Python API

Scanning

from behave_doctor import scan_project, Severity

report = scan_project("path/to/project")

# Filter diagnostics by severity
errors = [d for d in report.diagnostics if d.severity is Severity.ERROR]
for d in errors:
    print(f"{d.rule_id}: {d.message} at {d.file}:{d.line}")

# Access statistics
stats = report.statistics
print(f"{stats.features} features, {stats.scenarios} scenarios")
print(f"{stats.unused_step_definitions} unused, {stats.undefined_steps} undefined")

# Exit code: 0 = clean, 1 = issues found
print(f"Exit code: {report.exit_code}")

Custom configuration:

from behave_doctor import scan_project, DoctorConfig, Severity

config = DoctorConfig(
    features_dir="my_features",
    steps_dir="my_steps",
    min_severity=Severity.WARNING,
    rules={"BD101": {"enabled": False}, "BD401": {"max_steps": 5}},
)
report = scan_project("path/to/project", config=config)

Impact analysis

from behave_doctor import impact_analysis, format_impact

result = impact_analysis(
    "path/to/project",
    changed_files=["features/steps/login_steps.py"],
)

# Affected scenario names (suitable for behave --name)
for name in result.scenario_names:
    print(name)

# Summary counts
print(f"{result.summary.scenarios_affected} scenarios affected")
print(f"{result.summary.features_affected} features affected")

# Format as text, JSON, or names
print(format_impact(result, "text"))
print(format_impact(result, "json"))
print(format_impact(result, "names"))

CI/CD

GitHub Actions (basic lint)

- run: pip install behave-doctor
- run: behave-doctor scan . --no-color

GitHub Code Scanning (SARIF)

- run: pip install behave-doctor
- run: behave-doctor scan . --format sarif -o behave-doctor.sarif
  continue-on-error: true
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: behave-doctor.sarif

Pre-commit hook

repos:
  - repo: https://github.com/MathiasPaulenko/behave-doctor
    rev: v1.4.0
    hooks:
      - id: behave-doctor
        args: ["scan", "--severity", "warning", "--no-color"]

How it works

behave-doctor never executes your code. It works in four phases:

1. Scan — behave-model parses .feature files into an AST. The step scanner uses Python's ast module to extract @given/@when/@then decorators from step modules — without importing them.
2. Match — Each feature step is matched against step definitions using Behave's own matcher classes (parse, cfparse, re, re0), honouring use_step_matcher calls in each module. The dependency graph records which definitions are used and which are not.
3. Analyze — 20 rules visit the project, step definitions, and dependency graph to produce diagnostics.
4. Report — Diagnostics are formatted as text, JSON, or SARIF and written to stdout or a file.

Documentation

Full documentation at https://mathiaspaulenko.github.io/behave-doctor/:

• Installation
• Quick Start
• CLI Reference
• Rules
• Configuration
• Reporters
• Python API
• CI/CD
• Architecture
• FAQ

Supply chain & trust

• Trusted Publishing (OIDC) — releases to PyPI use Trusted Publishing via GitHub Actions OIDC. No long-lived API tokens are stored in secrets.
• Pinned actions — all GitHub Actions are pinned to specific versions (e.g. @v4, @v1.12.4).
• Minimal dependencies — only behave/behave-model (parsing and matching) and typer (CLI) at runtime. No transitive dependency tree to audit.
• No code execution — behave-doctor never imports or executes your step definitions. It uses Python's ast module for static analysis only.
• py.typed marker — the package ships with inline type hints.
• Reproducible builds — hatchling build backend with no dynamic metadata.

Development

git clone https://github.com/MathiasPaulenko/behave-doctor.git
cd behave-doctor
pip install -e ".[dev]"
pre-commit install

See CONTRIBUTING.md for full guidelines.

License

MIT — © Mathias Paulenko

Acknowledgements

• behave-model — the .feature file parser that powers behave-doctor's analysis.
• typer — the CLI framework that makes behave-doctor's command-line interface clean and ergonomic.
• ruff and mypy — the tools that keep behave-doctor's codebase clean and fully typed.