behave-gen

A CLI toolkit for scaffolding and evolving Behave BDD projects.

behave-gen helps you create, extend, and maintain Behave (Python BDD) projects. It scaffolds new projects, generates .feature files and concrete step definitions, integrates ecosystem tools (behave-doctor, behave-lint, behave-format), and migrates Cucumber projects to Behave.

Features

Installation

pip install behave-gen

Requirements

• Python 3.11 or newer.
• A working pip / venv environment.

Optional extras extend functionality as shown below.

With optional extras:

pip install behave-gen[doctor,lint,format,openapi]
pip install behave-gen[all]

Quick start

# Create a new Behave project
behave-gen init my-project
cd my-project

# Add a feature file
behave-gen add feature login

# Add HTTP step definitions
behave-gen add steps --lib http

# Generate steps from a wavexis recording
behave-gen add steps --from-recording recording.yaml

# Combine a step library with a recording (library first, then dedup)
behave-gen add steps --lib http --from-recording recording.yaml

# Check project health
behave-gen check

# Run tests
behave

Generating from an OpenAPI spec

behave-gen from-openapi spec.yaml --out-dir gen --step-lib http --tag api

This produces .feature files grouped by path, each with scenarios that use the HTTP step library syntax. The --step-lib http flag also generates a concrete, runnable http_steps.py module.

Generating steps from a wavexis recording

Use wavexis to record browser interactions, then generate Behave step definitions and a feature file from the recording:

# Record a flow with wavexis (produces recording.yaml)
# Then generate steps and a feature file:
behave-gen add steps --from-recording recording.yaml

This produces:

• features/steps/recorded_steps.py — Python step definitions with real browser actions via context.page (Playwright/wavexis page object).
• features/recorded.feature — a Gherkin feature file representing the recorded flow.

Supported action types: navigate, click (by selector or text), type, and scroll. Unsupported actions are silently skipped. Steps are deduplicated against existing step definitions in the project.

You can combine --from-recording with --lib to add a step library first, then generate recording-derived steps deduplicated against it.

Migrating from Cucumber

behave-gen migrate path/to/cucumber-project --out-dir migrated

Feature files are copied into a Behave features/ layout. Java step definitions are not auto-translated; use behave-gen add steps to generate Python equivalents.

Examples

The examples/ directory contains ready-to-run projects that demonstrate each workflow:

• basic-project — init + add feature + add steps with HTTP and auth step libraries.
• openapi-project — from-openapi generating features and HTTP steps from a Petstore OpenAPI 3.0 spec.
• migrated-project — migrate converting a Cucumber (Java) project to Behave feature files.

See examples/README.md for details.

Architecture

behave_gen/
  cli/            Typer CLI application
  commands/       One module per CLI command
  generators/     Pluggable code generators (OpenAPI, Postman, Swagger)
  plugins/        Source-specific parsers and builders
  step_libraries/ Built-in step library templates (HTTP, auth)
  templates/      Project and feature templates
  config.py       [tool.behave-gen] configuration model
  diagnostics.py  Optional-dependency handling
  paths.py        Path resolution and validation helpers
  project.py      Project detection and state
  recording.py    Wavexis recording parser and step generator

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. @v7, @v1.14.1).
• Minimal dependencies — only behave, behave-model, and typer at runtime. All other dependencies are optional extras.
• 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-gen.git
cd behave-gen
pip install -e ".[dev,docs]"
pre-commit install

See CONTRIBUTING.md for full guidelines.

Documentation

Full documentation, including the CLI reference, configuration guide, and Python API docs, is published at mathiaspaulenko.github.io/behave-gen.

Acknowledgements

• Built on top of Behave and the Python packaging ecosystem.
• Template and scaffolding patterns inspired by the Python open source community's emphasis on minimal, composable tools.

License

MIT