behave-runner

A unified CLI entry point for the Behave BDD ecosystem.

behave-runner is a single, extensible command-line interface for the Behave BDD ecosystem. It wraps common Behave workflows into focused subcommands and degrades gracefully when optional plugins are not installed.

Why behave-runner?

• One CLI for everything — run, list, filter, lint, format, watch, report, trace, generate and analyze scenarios from one tool.
• Plugin-friendly — optional extras add parallel execution, retries, priority ordering, trace viewers, report formatters, step libraries and more without breaking core behavior.
• Fast feedback — watch mode, impact analysis and rich terminal output keep the test loop tight.
• Project scaffolding — initialize a new Behave project, generate steps or features, and validate project health with doctor.

Features

• Run, list, select, lint, format, watch, report, trace, steps, impact, generate, init, config, open and record commands.
• Optional parallel execution, sharding, retries and priority ordering.
• Configuration profiles via pyproject.toml or behave.ini.
• Watch mode that re-runs tests when files change.
• Reports in console, HTML, Markdown, JSON, sheets and file formats.
• Trace viewer and web dashboard support.
• Step library management and feature/step generation.
• Impact analysis to detect scenarios affected by code changes.
• Graceful degradation when optional extras are missing.

Requirements

• Python 3.11 or higher
• Core dependencies (behave, behave-kit, behave-model) are installed automatically

Installation

pip install behave-runner

To install all optional extensions:

pip install "behave-runner[all]"

For development:

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

Getting Started

1. Initialize a project

behave-runner init --name my-project

This creates a standard Behave layout: features/, features/steps/ and environment.py inside the named project directory.

2. List scenarios

behave-runner list

Shows every scenario in the project without running anything.

3. Run the suite

behave-runner run

Runs every feature. You can also target a specific feature or tag:

behave-runner run --tags @smoke
behave-runner run features/login.feature

4. Filter with select

behave-runner select --tags @smoke
behave-runner select --pattern "login"

5. Watch files

behave-runner watch

Re-runs behave-runner run whenever a .feature, .py or config file changes. Press Ctrl+C to stop.

6. Lint and format

behave-runner lint
behave-runner format

7. Reports and traces

behave-runner report generate --format html
behave-runner report show

With behave-trace installed:

behave-runner trace show

Configuration

You can store profiles in pyproject.toml:

[tool.behave-runner]
parallel = 4

[tool.behave-runner.profiles.smoke]
tags = ["@smoke"]

[tool.behave-runner.profiles.ci]
parallel = 8
format = "json"

Or use a classic behave.ini file. Run behave-runner config show to inspect configuration.

Commands

Ecosystem

behave-runner is the entry point for the BehaveLib ecosystem. The libraries below can be installed individually or through behave-runner extras.

Install groups:

# Execution extras
pip install "behave-runner[parallel,priority,retry]"

# Reporting extras
pip install "behave-runner[report-html,report-json]"

# Everything
pip install "behave-runner[all]"

Documentation

Full documentation is available at:

https://mathiaspaulenko.github.io/behave-runner/

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for guidelines.

Links

• Repository: https://github.com/MathiasPaulenko/behave-runner
• Issues: https://github.com/MathiasPaulenko/behave-runner/issues
• Discussions: https://github.com/MathiasPaulenko/behave-runner/discussions
• PyPI: https://pypi.org/project/behave-runner/
• Changelog: https://github.com/MathiasPaulenko/behave-runner/blob/main/CHANGELOG.md

Acknowledgements

behave-runner is built on top of the Behave BDD framework and the BehaveLib ecosystem of plugins. It uses Typer for the CLI and Rich for terminal output.

License

MIT