Quickstart¶

A complete walkthrough from install to running your first feature.

1. Install¶

pip install "behave-steplib[api]"

2. Set up your environment¶

Create 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

This writes features/environment.py with the scaffold above.

3. Write a 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"

4. Run¶

behave

Loading specific modules¶

If you prefer to load only specific modules instead of auto-discovering all installed plugins:

from steplib.behave import load

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

You can pass multiple module paths:

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

Filtering by category or backend¶

autoload accepts optional filters to narrow which steps are registered with behave. This is useful when you have multiple extras installed but only want a subset active in a given run.

from steplib.behave import autoload

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

categories — only keep steps whose category is in the list.
backends — mapping of category to backend name; only keep steps whose backend matches. Steps without a backend are always kept.

Multilingual features¶

Steps are defined in English and translated to Spanish and Portuguese. All patterns are registered with behave simultaneously, so you can mix languages in the same project without configuration:

# English
When I send a GET request to "/users"

# Spanish
Cuando envío una petición GET a "/users"

# Portuguese
Quando envio uma requisição GET para "/users"

See Internationalization (i18n) for details on adding translations.

Next steps¶

Autoload and Load — full reference for autoload and load.
CLI — inspect and validate your step library from the terminal.
API Module — complete API step reference.