behave-data

Data management for Behave — typed tables, diffs, dynamic examples, fixtures, and secrets with zero boilerplate.

Built on top of behave-tables.

Full documentation: mathiaspaulenko.github.io/behave-data

Quick links

• Documentation
• Installation
• Quickstart
• Changelog
• Contributing
• Security
• License

Why?

Behave data tables are strings. Everything is "42", "true", "". You write boilerplate in environment.py to convert types, handle nulls, load examples, and manage test data.

behave-data fixes this:

Features

• Typed Tables — name:str, age:int, active:bool, price:float, created:date with automatic conversion
• Null Resolution — Empty cells become None, configurable markers ("", "null", "N/A"), per-column overrides
• Table Diff — Cucumber-style diff output with row/column mismatch detection
• Raw Tables — Access tables without header assumption, vertical tables, transposed data
• Dynamic Examples — @load_examples:csv:users.csv replaces static Examples blocks; named data_sources for URLs, SQL, nested paths
• Fixtures — Reusable data recipes with nesting (ref:other) and parametrization
• Builders — Construct test data with derived fields and overrides
• Secrets — env:, file:, secret: placeholders with Vault and AWS backends, automatic masking
• Declarative Tags — @needs_data, @with_fixture, @cleanup_after for zero-boilerplate setup/teardown

Install

Requires Python 3.11+ and behave 1.3.0+.

pip install behave-data

Optional extras:

pip install behave-data[yaml,excel]    # multiple extras
pip install behave-data[dev]           # contribute

Quickstart

# features/environment.py
from behave_data import (
    setup_data,
    before_feature_hook,
    before_scenario_hook,
    before_step_hook,
    after_scenario_hook,
)


def before_all(context):
    setup_data(context)


def before_feature(context, feature):
    before_feature_hook(context, feature)


def before_scenario(context, scenario):
    before_scenario_hook(context, scenario)


def before_step(context, step):
    before_step_hook(context, step)


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

# features/login.feature
@load_examples:csv:users.csv
Scenario Outline: User login
  Given a user with name "<name>" and email "<email>"
  When they log in
  Then they see the dashboard

  Examples:

# features/steps/login.py
from behave_data import typed_wrap, diff


@then("the users should match")
def step_match(context):
    table = typed_wrap(context.table)
    for row in table.typed_dicts():
        assert isinstance(row["age"], int)  # typed, not string
        assert row["city"] is None or row["city"]  # None for empty cells

That's it. Type annotations in headers, nulls resolved, examples from external files, tags for setup/teardown — all automatic.

Documentation

Migration from behave-tables

behave-data depends on behave-tables and extends it:

1. pip install behave-data — behave-tables comes as a dependency
2. Use typed_wrap() instead of wrap() for typed column conversion
3. Add setup_data(context) in before_all() to enable hooks, fixtures, builders, and secrets

All behave-tables APIs (as_dicts, as_models, transpose, to_csv, to_json, find_row, select, etc.) remain available via the re-exported TableWrapper and wrap().

See the Migration Guide for details.

Configuration

# behave_data.yml
null_markers: ["", "null", "None", "N/A"]
null_markers_by_column:
  age: ["", "unknown"]
secret_backend: env
secret_path: secrets/
load_base_dir: features/data/
data_sources:
  users_api: "http:https://api.example.com/users"   # @load_examples:users_api

See Configuration for all options.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for setup, development commands, and the release checklist.

For security issues, see SECURITY.md.

Acknowledgements

• Built on behave-tables for table manipulation.
• Inspired by the Behave community's need for first-class data handling in Gherkin scenarios.

License

MIT