behave-steplib 1.1.0

Reusable step library for behave with multi-technology support and i18n.

behave-steplib

Reusable step libraries for Behave BDD — share, discover and install step definitions across projects. Zero mandatory dependencies; each technology is an optional extra.

Why behave-steplib?

Writing BDD step definitions for HTTP APIs, web browsers, databases and Kafka is repetitive. Every project re-implements the same "send a request", "check the status code", "query the database" steps. behave-steplib provides a curated, typed, multilingual library of reusable steps that you install once and share across projects.

• Modular — api, web, db, kafka modules activated via extras and lazy imports. Install only what you need.
• Auto-registered — autoload(context) discovers every installed step via Python entry points and registers it with behave in one line.
• Multilingual — steps defined in English with es and pt translations; all patterns are registered with behave so matching works regardless of the language used in feature files.
• Typed — full type hints, mypy --strict clean, py.typed marker included.
• CLI — steplib list / show / validate / init powered by Typer for inspecting and validating your step library from the terminal.
• Pluggable — third-party packages can register steps via the steplib.plugins entry point group; autoload discovers them automatically.
• Ecosystem — integrates with behave-kit (soft assertions), behave-tables (table conversion) and behave-data (test data loading) when installed.
• Backends — each module supports multiple backends (e.g. stdlib/httpx/requests for API, selenium for web) selectable at autoload time.

Installation

pip install behave-steplib            # core only (behave, parse, typer)
pip install behave-steplib[api]       # + httpx HTTP client
pip install behave-steplib[requests]  # + requests HTTP client
pip install "behave-steplib[api,requests,web,db,kafka]"  # + all technology extras
pip install "behave-steplib[all]"     # + every technology extra
pip install behave-steplib[dev]       # + pytest, ruff, mypy, build, twine

Extra	Packages	Description
[api]	httpx	HTTP API testing with httpx
[requests]	requests	HTTP API testing with requests
[web]	selenium	Browser testing with Selenium
[db]	sqlalchemy	Database testing with SQLAlchemy
[kafka]	kafka-python-ng	Kafka producer/consumer testing
[kit]	behave-kit	Soft assertions, typed context, fixtures
[data]	behave-data	Test data loading (CSV, JSON, YAML, Excel)
[tables]	behave-tables	Table conversion helpers
[dev]	pytest, ruff, mypy, build, twine	Development tools
[docs]	sphinx, furo, myst-parser, sphinx-autodoc-typehints	Documentation tools
[all]	api, requests, web, db, kafka, kit, data, tables	Everything except dev/docs

Requirements

• Python 3.11+ (tested on CPython 3.11, 3.12, 3.13 and 3.14)
• behave — the only mandatory runtime dependency alongside parse and typer

Quickstart

Level 1 — Automatic wiring

Add three hooks to your environment.py and every installed step is wired automatically:

# features/environment.py
from steplib.behave import autoload

def before_all(context):
    context.steplib = autoload(context)

def before_scenario(context, scenario):
    context.steplib.reset()

def after_scenario(context, scenario):
    context.steplib.cleanup()

Or generate it with the CLI:

steplib init

Level 2 — Explicit load

Load only the modules you need by dotted path:

from steplib.behave import load

def before_all(context):
    context.steplib = load(context, "steplib.modules.api.steps")

Level 3 — Filtered autoload

When multiple extras are installed, narrow which steps are active:

from steplib.behave import autoload

def before_all(context):
    context.steplib = autoload(
        context,
        categories=["api"],
        backends={"api": "httpx"},
    )

Example feature

Feature: API health check

  Scenario: GET users returns 200
    Given the API base url is "https://api.example.com"
    When I send a GET request to "/users"
    Then the response status is 200
    And the response body is valid JSON
    And the JSON path "$.users[0].name" equals "Ada"

Multilingual features

Steps are defined in English and translated to Spanish and Portuguese. All patterns are registered with behave — no language switch needed:

# es
Cuando envío una petición GET a "/users"
Entonces el estado de la respuesta es 200

# pt
Quando envio uma requisição GET para "/users"
Então o status da resposta é 200

Modules

API

HTTP API testing with stdlib (urllib), httpx or requests backends.

Given the API base url is "https://api.example.com"
When I send a GET request to "/users"
Then the response status is 200
And the JSON path "$.users[0].name" equals "Ada"
And the response header "Content-Type" is "application/json"

Web

Browser testing with Selenium (Chrome, Firefox, headless).

Given the web base url is "https://example.com"
When I navigate to "/login"
Then the page title is "Login"
And the element id "username" is present
And the page contains "Sign In"

DB

Database testing with SQLAlchemy (SQLite, PostgreSQL, MySQL, ...).

Given the database connection string is "sqlite:///test.db"
When I execute the SQL query "SELECT * FROM users"
Then the query returns 3 rows
And the column "name" in the first row equals "Ada"

Kafka

Kafka producer and consumer testing with kafka-python-ng.

Given the Kafka bootstrap servers are "localhost:9092"
When I produce a message to topic "events" with key "id" and value "hello"
And I consume messages from topic "events"
Then the consumed messages count is 1
And a consumed message contains "hello"

CLI

steplib list                         # list all registered steps
steplib list --category api          # filter by category
steplib list --backend httpx         # filter by backend
steplib list --json                  # output as JSON
steplib show "I send a {method} request to {url}"
steplib validate                     # validate step contracts
steplib init                         # generate features/environment.py

Writing custom steps

Use the @step decorator to define your own steps with full metadata:

from steplib import Param, step

@step(
    "the invoice total is {total:f}",
    category="invoice",
    description="Assert the invoice total matches.",
    parameters=[Param("total", type=float, required=True)],
    example='Then the invoice total is 19.99',
    i18n={
        "es": "el total de la factura es {total:f}",
        "pt": "o total da fatura é {total:f}",
    },
    tags=["invoice"],
    version="1.0.0",
)
def step_invoice_total(context, total):
    assert context.invoice.total == total

Register steps in a register(registry) function and declare an entry point:

# pyproject.toml
[project.entry-points."steplib.plugins"]
mycompany = "mycompany.steps:register"

Once installed, autoload(context) discovers your package automatically.

Development

make dev        # install with api, requests, dev and docs extras
make lint       # ruff + mypy --strict
make test-cov   # pytest with >=80% coverage gate
make docs-build # build Sphinx documentation
make build      # build sdist + wheel

Documentation

Full documentation is available at https://mathiaspaulenko.github.io/behave-steplib.

Acknowledgements

• Behave — the BDD framework this library extends.
• parse — pattern matching for step definitions.
• Typer — CLI framework.
• Sphinx + furo — documentation.

License

MIT — see LICENSE.