Migration Guide¶

From raw Behave to behave-kit¶

behave-kit is designed as a drop-in enhancement — no breaking changes to your existing Behave suite. You can adopt features incrementally.

Step 1: Install¶

pip install behave-kit

Step 2: Wire automatic features (optional)¶

Add to environment.py:

from behave_kit import setup, teardown

def before_all(context):
    setup(context, env="staging")

def after_scenario(context, scenario):
    teardown(context)

This enables:

Soft assertion collector (reset per scenario)
Context dump on failure
Step suggestions for undefined steps
Fixture manager
Scoped attribute cleanup

Step 3: Replace raw asserts with soft asserts¶

Before:

@then("the response should be valid")
def step(context):
    assert context.response.status_code == 200
    assert context.response.body["count"] > 0

After:

from behave_kit import assert_soft

@then("the response should be valid")
def step(context):
    assert_soft(context.response.status_code == 200)
    assert_soft(context.response.body["count"] > 0)

Soft asserts collect all failures and report them together at teardown, instead of stopping at the first one.

Step 4: Add typed context (optional)¶

Before:

@given("I have a browser")
def step(context):
    context.driver = "chrome"
    context.base_url = "https://test.com"

@then('the driver should be "{driver}"')
def step(context, driver):
    assert context.driver == driver  # no IDE autocompletion

After:

from behave_kit import TypedContext

class MySchema:
    driver: str
    base_url: str

@given("I have a browser")
def step(context):
    ctx = TypedContext(context, MySchema)
    ctx.setup(driver="chrome", base_url="https://test.com")

@then('the driver should be "{driver}"')
def step(context, driver):
    ctx = TypedContext(context, MySchema)
    assert ctx.driver == driver  # IDE autocompletion + mypy validation

Step 5: Replace manual env reads¶

Before:

import os
api_key = os.environ.get("API_KEY")
if api_key is None:
    raise ValueError("API_KEY is not set")

After:

from behave_kit import env
api_key = env("API_KEY", required=True)

Step 6: Add tag-based fixtures (optional)¶

Before:

def before_scenario(context, scenario):
    if "browser" in scenario.tags:
        context.browser = start_browser()

def after_scenario(context, scenario):
    if hasattr(context, "browser"):
        context.browser.quit()

After:

from behave_kit import fixture

@fixture("browser")
def browser_fixture(context):
    def setup(ctx):
        ctx.browser = start_browser()
    def teardown(ctx):
        ctx.browser.quit()
    return (setup, teardown)

# In environment.py:
from behave_kit.fixtures import FixtureManager
fixtures = FixtureManager()

def before_scenario(context, scenario):
    fixtures.setup_for_scenario(context, scenario)

def after_scenario(context, scenario):
    fixtures.teardown_scenario(context)

Compatibility¶

behave-kit works with Behave >= 1.2.6
Python >= 3.11
No monkey-patching — all features are opt-in
Existing step definitions continue to work unchanged