Skip to main content

behave-runner

A unified CLI entry point for the Behave BDD ecosystem.

CI Coverage PyPI Python Docs License

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, XLSX and DOCX 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

Command Description
run Execute Behave tests.
watch Re-run tests when files change.
list List scenarios without executing them.
select Filter scenarios by tags, regex or name.
lint Lint .feature files.
format Format .feature files.
doctor Check project health.
init Initialize a new Behave project.
generate Generate steps or features.
record Record a browser session and generate steps.
report Generate and open reports.
trace View traces or serve a trace dashboard.
steps Manage step libraries.
impact Detect scenarios affected by code changes.
open Open the latest report or trace in the default browser.
config Manage configuration profiles.

Ecosystem

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

Library Category Purpose Extra
behave Core BDD framework. included
behave-kit Core Testing utilities: timeouts, fixtures, hooks. included
behave-model Core Feature and scenario parsing. included
behave-pool Execution Parallel and sharded runs. parallel
behave-priority Execution Priority ordering and smoke flags. priority
behave-retry Execution Retry and flaky report support. retry
behave-trace Debug Trace viewer and UI. trace
behave-doctor Quality Project health and impact analysis. doctor
behave-lint Quality Feature file linting. lint
behave-format Quality Feature file formatting. format
behave-gen Scaffolding Project and feature generation. gen
behave-steplib Steps Step library management. steplib
behave-comments Utility Comment metadata extraction. comments
behave-tables Utility Table helpers. —
wavexis Recording Browser session recording. record
behave-modern-console-report Reporting Console report. report-console
behave-modern-html-report Reporting HTML report. report-html
behave-modern-md-report Reporting Markdown report. report-md
behave-modern-json-report Reporting JSON report. report-json
behave-modern-sheets-report Reporting XLSX/CSV report. report-sheets
behave-modern-file-report Reporting DOCX report. report-file

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.

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

Metadata

Release files for behave-runner 1.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for behave-runner 1.4.1
File Size Uploaded Provenance Actions
behave_runner-1.4.1.tar.gz 117.6 kB With provenance Details for behave_runner-1.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for behave-runner 1.4.1
File Interpreter ABI Platform Actions
behave_runner-1.4.1-py3-none-any.whl Python 3 none any Details for behave_runner-1.4.1-py3-none-any.whl

Total release size: 164.7 kB

Release files / behave_runner-1.4.1.tar.gz

Download URL behave_runner-1.4.1.tar.gz
Size 117.6 kB
Tags Source
SHA-256 checksum
How to use checksums
15cb8a014d40aac09aa7353e9fd130524fe4919c2a58c7009c7973ca15a4cf9a
BLAKE2b-256 checksum
How to use checksums
dbff259be904e4972aea29ef5be61e1baebbdc7d445c34f33df92730d1ea2822
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / behave_runner-1.4.1-py3-none-any.whl

Download URL behave_runner-1.4.1-py3-none-any.whl
Size 47.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
95f753aa90dd9488a93d629ff630c4204d9d30129263a80e51b9d7f3b8e43a92
BLAKE2b-256 checksum
How to use checksums
d26d31d8937465b8942b88baedb00b3c99a616fb7a8d6702513d1b3453332659
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for behave-runner 1.4.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for behave_runner-1.4.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page