behave-toolkit

behave-toolkit helps growing behave suites stay explicit, predictable, and easier to maintain.

It keeps features/environment.py readable, moves repetitive object wiring into YAML, and adds a small set of opt-in helpers only where large Behave suites usually start to hurt: shared object setup, parser registration, reusable variables, cycle-heavy scenarios, logging, and step-library discovery.

Quick start

Build the smallest working integration in a few minutes.

Getting started

Integration examples

Copy full files and hook templates for real Behave projects.

Integration examples

Configuration model

Understand variables, objects, $ref, $var, context injection, and config directories.

Configuration model

Lifecycle hooks

See exactly which helper belongs in import time, before_all, before_feature, and before_scenario.

Lifecycle hooks

Logging and diagnostics

Start with one persistent test log, then scale to named loggers only if you need them.

Logging and diagnostics

Parser helpers

Move Behave custom type registration into YAML without hiding what is happening.

Parser helpers

Scenario cycling

Replay one plain scenario with @cycling(N) while keeping hooks and reports explicit.

Scenario cycling

Step documentation

Generate a Sphinx-ready reference site from your downstream Behave step library.

Step documentation

Compatibility and support

Check supported Python versions, Behave expectations, and what CI validates today.

Compatibility and support

Troubleshooting

Diagnose the most common ConfigError, IntegrationError, parser, and docs-generation problems.

Troubleshooting

API reference

Quick-reference the public functions, manager surface, and error types exposed by the package.

API reference

Maintainer release guide

Run the Release Please, GitHub release, and PyPI publishing flow with confidence.

Maintainer release guide

Choose your path

• If you want the smallest working setup, start with Quick start.

• If you want full files you can adapt directly, go to Integration examples.

• If you want the exact config schema and scope rules, read Configuration model and Lifecycle hooks.

• If you need version or support details before adopting the package, read Compatibility and support.

• If something failed and you want a fix fast, jump to Troubleshooting.

• If you maintain this repository, keep Maintainer release guide bookmarked.

What the toolkit gives you today

• file- or directory-based config loading with deterministic YAML merging

• global, feature, and scenario scoped object activation

• YAML-defined factories resolved from your own code, installed packages, or the standard library

• explicit object references with $ref and reusable config values with $var

• opt-in {{var:name}} substitution inside parsed feature files

• config-driven parser helpers with matcher selection and enum shortcuts

• tag-driven scenario cycling with @cycling(N)

• a small persistent test logger with configure_test_logging(), plus optional YAML-configured named loggers

• Sphinx-ready step documentation with feature examples, typed parameters, and Google-style docstring rendering

• fail-fast ConfigError, IntegrationError, and DocumentationError messages

Recommended reading order

1. Read Quick start to get one clean integration working.

2. Read Integration examples if you want copy-paste templates for real suites.

3. Read Configuration model and Lifecycle hooks to understand the core mental model.

4. Add optional layers only when they solve a real problem: Logging and diagnostics, Parser helpers, Scenario cycling, and Step documentation.

5. Use Compatibility and support, Troubleshooting, and API reference as reference pages.

Project docs vs generated step docs

This site documents the behave-toolkit package itself.

The package also generates documentation for downstream Behave suites via behave-toolkit-docs. That generated output is a separate concern and is documented in Step documentation.

The published GitHub Pages site is versioned by release, with latest pointing at the newest released documentation set.

Note

The currently supported runtime scopes are global, feature, and scenario. Scenario cycling is orthogonal: it multiplies scenario executions, not object scopes.