Python API
behave-runner can also be used as a Python library. The public API is
kept small and lives mainly under behave_runner.core. This page is
auto-generated from the source docstrings with mkdocstrings.
Entry point
The behave_runner.__main__:main function is the same entry point used by
the behave-runner console script.
For programmatic use, create a RunConfig and call run:
from behave_runner.core.orchestrator import RunConfig, run
config = RunConfig(features=["features"], tags=["@smoke"])
exit_code = run(config)
Core modules
Orchestrator
behave_runner.core.orchestrator
Orchestrator — builds behave commands from RunConfig.
RunConfig
dataclass
Configuration for a behave run.
Source code in behave_runner/core/orchestrator.py
74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 | |
__post_init__
Validate field types and values.
Source code in behave_runner/core/orchestrator.py
build_behave_command
Build the behave command as a list of strings for subprocess.
All optional features (parallel, trace, report formatters) are passed directly to behave as flags. Behave handles them natively or via installed formatter packages.
Uses "python -m behave" instead of "behave" to ensure the same Python interpreter (and its installed packages) is used.
Source code in behave_runner/core/orchestrator.py
166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 | |
report_formatter_package
run
Execute behave with the given config. Return exit code.
All optional features (parallel, trace, report formatters, retries, priority) are passed to behave via command-line flags and environment variables. Behave handles them natively or via installed packages.
config.timeout is a global timeout in seconds for the whole run;
0 means no timeout. When it expires the behave process is killed
and the run exits with code 124.
Source code in behave_runner/core/orchestrator.py
validate_shard
Validate a shard string in the format 'i/n' (e.g. '1/3').
Raises ValueError if the format is invalid or the shard index is out of range.
Source code in behave_runner/core/orchestrator.py
Configuration
behave_runner.core.config
Config file parsing for [tool.behave-runner] section.
load_config
Load [tool.behave-runner] config from pyproject.toml or behave.ini.
Config files are searched from the project root (nearest ancestor with a pyproject.toml), matching how behave itself discovers configuration.
Source code in behave_runner/core/config.py
load_defaults
Load the base [tool.behave-runner] values (excluding 'profiles').
These are the project-wide defaults that apply to every run. Profile values loaded via load_profile() are merged on top of them.
Source code in behave_runner/core/config.py
load_profile
Load a specific profile from config. Raises ConfigError if not found.
Source code in behave_runner/core/config.py
Dependency checking
behave_runner.core.deps
Optional dependency checking with graceful degradation.
check_optional
Check if an optional package is installed. Print warning if not.
Source code in behave_runner/core/deps.py
is_installed
Silently check if a package is installed.
Uses importlib.util.find_spec so the check does not execute module
code: importing an optional package may pull in heavy transitive
dependencies or trigger side effects just to answer "is it installed?".
Source code in behave_runner/core/deps.py
resolve_executable
Resolve a console script name to a path next to the current interpreter.
External behave-* tools are checked for via importlib but invoked as
console scripts. When the interpreter's Scripts/bin directory is not on
PATH (venv not activated, pip install --user, etc.), the package
is importable but the script cannot be found by name. Prefer the script
located next to sys.executable, then the per-user scripts directory;
fall back to the bare name so PATH resolution still works.
Source code in behave_runner/core/deps.py
run_external
Run an external CLI tool via subprocess, handling common errors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cmd
|
list[str]
|
Command list to execute (passed to subprocess.run with shell=False). |
required |
tool_name
|
str
|
Human-readable tool name for error messages. |
required |
install_hint
|
str
|
Package name for the install instruction in error messages. |
required |
Returns:
| Type | Description |
|---|---|
int
|
The tool's exit code, or 2 if the tool is not found or raises OSError. |
Source code in behave_runner/core/deps.py
Output management
behave_runner.core.output
Output directory management for reports.
clean_output_dir
Remove all contents of the output directory.
Symlinks are unlinked rather than followed to prevent deleting files outside the output directory.
Source code in behave_runner/core/output.py
ensure_output_dir
Create output directory if it doesn't exist. Return the path.
Raises FileExistsError if the path exists but is not a directory.
Source code in behave_runner/core/output.py
find_latest_report
Find the most recently modified report file in output_dir.
Source code in behave_runner/core/output.py
open_latest_report
Find and open the latest report in the browser.
Returns True when a report was found and opened; False otherwise so callers can exit non-zero — "nothing to open" must not look like success.
Source code in behave_runner/core/output.py
File watcher
behave_runner.core.watcher
Polling-based file watcher with debounce.
FileWatcher
Polling-based file watcher with debounce.
Source code in behave_runner/core/watcher.py
run
Run the watcher loop. Blocks until stopped.
Source code in behave_runner/core/watcher.py
Feature parsing
behave_runner.core.features
Shared feature file parsing utilities.
ScenarioInfo
Bases: TypedDict
Information about a single scenario collected from a feature file.
Source code in behave_runner/core/features.py
collect_scenarios
collect_scenarios(feature_paths: Sequence[Path | str], tags: list[str] | None = None, pattern: str | None = None, feature_name: str | None = None) -> list[ScenarioInfo]
Parse feature files and collect scenarios matching all filters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
feature_paths
|
Sequence[Path | str]
|
Paths to feature files or directories. Behave's 'file.feature:LINE' location syntax is also accepted. |
required |
tags
|
list[str] | None
|
Tag filters using behave semantics: comma-separated items are OR-ed, '~@tag' negates, and v2 expressions ('@a and not @b') are supported. Multiple entries are AND-ed. |
None
|
pattern
|
str | None
|
Regex pattern to match scenario names. |
None
|
feature_name
|
str | None
|
Case-insensitive substring to filter feature names. |
None
|
Source code in behave_runner/core/features.py
matches_tags
matches_tags(scenario_tags: list[str], include_tags: list[str] | None = None, exclude_tags: list[str] | None = None) -> bool
Check if scenario matches include tags (AND) and excludes none.
If no include tags are specified, all scenarios pass the include check. If no exclude tags are specified, no scenarios are excluded.
Utilities
behave_runner.utils
Utility functions for behave-runner.
find_project_root
Find project root by looking for pyproject.toml or behave.ini.
Source code in behave_runner/utils.py
make_stdout_safe
Reconfigure stdout to replace unencodable chars instead of crashing.
Scenario names with emoji/CJK raise UnicodeEncodeError on legacy Windows consoles (cp1252) when printed directly.
Source code in behave_runner/utils.py
open_in_browser
Open a URL in the default browser.
Set BEHAVE_RUNNER_NO_BROWSER=1 to skip opening the browser.
Browser launch failures (e.g. headless Linux) are logged, not raised.
Source code in behave_runner/utils.py
Exceptions
behave_runner.exceptions
Custom exceptions for behave-runner.
BehaveRunnerError
ConfigError
Bases: BehaveRunnerError
Raised when there is a configuration error.
DependencyMissingError
Bases: BehaveRunnerError
Raised when an optional dependency is required but not installed.