behave-steplib 1.0.1.dev0__tar.gz

behave_steplib-1.0.1.dev0/.gitignore

@@ -0,0 +1,76 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Sphinx documentation build
+docs/_build/
+
+# Project-specific reference folder (not for public release)
+ref/

behave_steplib-1.0.1.dev0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-07-27
+
+### Added
+
+- **Core package** (`steplib.core`): `@step` decorator, `StepInfo` metadata,
+  `StepRegistry` with behave integration, `Param` dataclass with `TypeRegistry`,
+  `SteplibState` lifecycle management, i18n pattern expansion and validation,
+  static step contract validation, ecosystem integration helpers
+  (`behave-kit`, `behave-tables`, `behave-data`).
+- **API module** (`steplib.modules.api`): HTTP testing steps with stdlib
+  (urllib), httpx and requests backends. Configuration, requests, assertions
+  (status, body, JSON path, headers), response storage and table comparison.
+- **Web module** (`steplib.modules.web`): Browser testing steps with Selenium
+  (Chrome, Firefox, headless). Navigation, page title, URL, element presence
+  and page content assertions.
+- **DB module** (`steplib.modules.db`): Database testing steps with SQLAlchemy.
+  Connection configuration, query execution, row count and column assertions.
+- **Kafka module** (`steplib.modules.kafka`): Kafka producer/consumer testing
+  steps with kafka-python-ng. Bootstrap configuration, produce, consume,
+  message count and content assertions.
+- **Behave integration** (`steplib.behave`): `autoload(context)` for entry-point
+  discovery, `load(context, *modules)` for explicit loading, `before_all` and
+  `after_scenario` hooks.
+- **CLI** (`steplib.cli`): `steplib list / show / validate / init` powered by
+  Typer with table and JSON output formats.
+- **i18n**: Spanish (`es`) and Portuguese (`pt`) translations for all steps.
+  Both `i18n` dictionary and stacked decorator patterns supported.
+- **Tests**: 164 tests covering core, modules, CLI and behave integration.
+  Coverage gate at 80% (current: 82%).
+- **CI/CD**: GitHub Actions workflows for CI (lint, typecheck, test, coverage),
+  release (build, PyPI publish with attestations, GitHub release) and docs
+  (Sphinx + furo, GitHub Pages deployment).
+- **Documentation**: Sphinx documentation with furo theme, autodoc API
+  reference, getting started guides, module references and architecture docs.
+- **Community files**: `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, `SECURITY.md`,
+  pull request template, bug report and feature request issue templates.
+- **Project setup**: `pyproject.toml` with hatchling + hatch-vcs, `Makefile`,
+  `LICENSE` (MIT), `steplib/py.typed` marker, `.markdownlint.json`.
+
+### Technical
+
+- `mypy --strict` clean across 38 source files.
+- `ruff` clean with `E`, `F`, `W`, `I`, `N`, `UP`, `B`, `SIM` rules.
+- Python 3.11+ required.
+- Zero mandatory runtime dependencies beyond `behave`, `parse` and `typer`.

behave_steplib-1.0.1.dev0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mathias Paulenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

behave_steplib-1.0.1.dev0/PKG-INFO

@@ -0,0 +1,303 @@
+Metadata-Version: 2.4
+Name: behave-steplib
+Version: 1.0.1.dev0
+Summary: Librería de steps reusable para behave con soporte multitecnología e i18n.
+Project-URL: Homepage, https://github.com/MathiasPaulenko/behave-steplib
+Project-URL: Documentation, https://mathiaspaulenko.github.io/behave-steplib
+Project-URL: Repository, https://github.com/MathiasPaulenko/behave-steplib
+Project-URL: Issues, https://github.com/MathiasPaulenko/behave-steplib/issues
+Project-URL: Changelog, https://github.com/MathiasPaulenko/behave-steplib/blob/main/CHANGELOG.md
+Author: Mathias Paulenko
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,bdd,behave,db,i18n,kafka,steps,web
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: behave>=1.3.0
+Requires-Dist: parse>=1.19
+Requires-Dist: typer>=0.12
+Provides-Extra: all
+Requires-Dist: behave-data>=1.0.2; extra == 'all'
+Requires-Dist: behave-kit>=1.3.1; extra == 'all'
+Requires-Dist: behave-tables>=1.3.1; extra == 'all'
+Requires-Dist: httpx>=0.27; extra == 'all'
+Requires-Dist: kafka-python-ng>=2.0; extra == 'all'
+Requires-Dist: selenium>=4.0; extra == 'all'
+Requires-Dist: sqlalchemy>=2.0; extra == 'all'
+Provides-Extra: api
+Requires-Dist: httpx>=0.27; extra == 'api'
+Provides-Extra: data
+Requires-Dist: behave-data>=1.0.2; extra == 'data'
+Provides-Extra: db
+Requires-Dist: sqlalchemy>=2.0; extra == 'db'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: responses>=0.25; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo>=2024.0; extra == 'docs'
+Requires-Dist: myst-parser>=3.0; extra == 'docs'
+Requires-Dist: sphinx-autodoc-typehints>=2.0; extra == 'docs'
+Requires-Dist: sphinx>=7.0; extra == 'docs'
+Provides-Extra: kafka
+Requires-Dist: kafka-python-ng>=2.0; extra == 'kafka'
+Provides-Extra: kit
+Requires-Dist: behave-kit>=1.3.1; extra == 'kit'
+Provides-Extra: tables
+Requires-Dist: behave-tables>=1.3.1; extra == 'tables'
+Provides-Extra: web
+Requires-Dist: selenium>=4.0; extra == 'web'
+Description-Content-Type: text/markdown
+
+# behave-steplib
+
+Reusable step libraries for [Behave](https://github.com/behave/behave) BDD — share, discover and install step definitions across projects. Zero mandatory dependencies; each technology is an optional extra.
+
+[![CI](https://github.com/MathiasPaulenko/behave-steplib/actions/workflows/ci.yml/badge.svg)](https://github.com/MathiasPaulenko/behave-steplib/actions/workflows/ci.yml)
+[![Release](https://github.com/MathiasPaulenko/behave-steplib/actions/workflows/release.yml/badge.svg)](https://github.com/MathiasPaulenko/behave-steplib/actions/workflows/release.yml)
+[![PyPI](https://img.shields.io/pypi/v/behave-steplib.svg)](https://pypi.org/project/behave-steplib/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 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
+
+```bash
+pip install behave-steplib            # core only (behave, parse, typer)
+pip install behave-steplib[api]       # + httpx HTTP client
+pip install "behave-steplib[api,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 |
+| `[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 | Documentation tools |
+| `[all]` | api, web, db, kafka, kit, data, tables | Everything except dev/docs |
+
+## Quickstart
+
+### Level 1 — Automatic wiring
+
+Add three hooks to your `environment.py` and every installed step is wired automatically:
+
+```python
+# 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:
+
+```bash
+steplib init
+```
+
+### Level 2 — Explicit load
+
+Load only the modules you need by dotted path:
+
+```python
+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:
+
+```python
+from steplib.behave import autoload
+
+def before_all(context):
+    context.steplib = autoload(
+        context,
+        categories=["api"],
+        backends={"api": "httpx"},
+    )
+```
+
+### Example feature
+
+```gherkin
+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:
+
+```gherkin
+# 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.
+
+```gherkin
+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).
+
+```gherkin
+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, ...).
+
+```gherkin
+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.
+
+```gherkin
+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
+
+```bash
+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:
+
+```python
+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:
+
+```toml
+# pyproject.toml
+[project.entry-points."steplib.plugins"]
+mycompany = "mycompany.steps:register"
+```
+
+Once installed, `autoload(context)` discovers your package automatically.
+
+## Development
+
+```bash
+make dev        # install with api, 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>.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

behave_steplib-1.0.1.dev0/README.md

@@ -0,0 +1,237 @@
+# behave-steplib
+
+Reusable step libraries for [Behave](https://github.com/behave/behave) BDD — share, discover and install step definitions across projects. Zero mandatory dependencies; each technology is an optional extra.
+
+[![CI](https://github.com/MathiasPaulenko/behave-steplib/actions/workflows/ci.yml/badge.svg)](https://github.com/MathiasPaulenko/behave-steplib/actions/workflows/ci.yml)
+[![Release](https://github.com/MathiasPaulenko/behave-steplib/actions/workflows/release.yml/badge.svg)](https://github.com/MathiasPaulenko/behave-steplib/actions/workflows/release.yml)
+[![PyPI](https://img.shields.io/pypi/v/behave-steplib.svg)](https://pypi.org/project/behave-steplib/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 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
+
+```bash
+pip install behave-steplib            # core only (behave, parse, typer)
+pip install behave-steplib[api]       # + httpx HTTP client
+pip install "behave-steplib[api,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 |
+| `[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 | Documentation tools |
+| `[all]` | api, web, db, kafka, kit, data, tables | Everything except dev/docs |
+
+## Quickstart
+
+### Level 1 — Automatic wiring
+
+Add three hooks to your `environment.py` and every installed step is wired automatically:
+
+```python
+# 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:
+
+```bash
+steplib init
+```
+
+### Level 2 — Explicit load
+
+Load only the modules you need by dotted path:
+
+```python
+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:
+
+```python
+from steplib.behave import autoload
+
+def before_all(context):
+    context.steplib = autoload(
+        context,
+        categories=["api"],
+        backends={"api": "httpx"},
+    )
+```
+
+### Example feature
+
+```gherkin
+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:
+
+```gherkin
+# 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.
+
+```gherkin
+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).
+
+```gherkin
+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, ...).
+
+```gherkin
+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.
+
+```gherkin
+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
+
+```bash
+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:
+
+```python
+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:
+
+```toml
+# pyproject.toml
+[project.entry-points."steplib.plugins"]
+mycompany = "mycompany.steps:register"
+```
+
+Once installed, `autoload(context)` discovers your package automatically.
+
+## Development
+
+```bash
+make dev        # install with api, 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>.
+
+## License
+
+MIT — see [LICENSE](LICENSE).