Configuration model¶

Root structure¶

Key	Type	Purpose
`version`	`int`	Config format version. Defaults to `1`.
`variables`	mapping	Reusable literal values referenced with `$var`.
`objects`	mapping	Named object definitions managed by the toolkit.
`parsers`	mapping	Optional Behave parser/type helpers configured at import time.
`logging`	mapping	Optional named logger definitions configured from `before_all()`.

Most suites can start with just version, variables, and objects. parsers and logging are optional layers for the cases where Behave setup has started to become repetitive.

File or directory input¶

install(...) and configure_parsers(...) accept either:

one YAML file
or a dedicated config directory

When you pass a directory, behave-toolkit loads every .yaml / .yml file recursively in deterministic path order and merges the known root sections.

features/
  behave-toolkit/
    00-variables.yaml
    10-parsers.yaml
    20-objects.yaml
    30-logging.yaml

Duplicate names across files fail fast. For example, defining the same object or logger name twice is treated as a config error instead of “last file wins”.

Object fields¶

Each entry in objects supports the following fields:

Field	Required	Purpose
`factory`	yes	Import path for the callable used to create the object.
`scope`	no	One of `global`, `feature`, or `scenario`. Defaults to `scenario`.
`args`	no	Positional constructor arguments.
`kwargs`	no	Keyword constructor arguments.
`cleanup`	no	Method or attribute name called during cleanup.
`inject_as`	no	Context attribute name used instead of the object name.

factory can point to:

code from your own project
an installed dependency from the active environment
the Python standard library

Markers¶

The config stays explicit by using dedicated markers instead of hidden magic.

Marker	Purpose
`$ref`	Reuse another configured object.
`$ref` + `attr`	Reuse one attribute path from another object.
`$var`	Reuse a root-level variable from the config.

Example with references¶

version: 1
variables:
  report_name: report.json

objects:
  artifacts_path:
    factory: pathlib.Path
    scope: global
    args:
      - artifacts

  workspace:
    factory: tempfile.TemporaryDirectory
    scope: feature
    cleanup: cleanup

  workspace_path:
    factory: pathlib.Path
    scope: feature
    args:
      - $ref: workspace
        attr: name

  report_path:
    factory: pathlib.Path
    scope: scenario
    args:
      - $ref: workspace_path
      - $var: report_name

  latest_report_path:
    factory: pathlib.Path
    scope: global
    args:
      - $ref: artifacts_path
      - $var: report_name

Validation behavior¶

install() validates the whole config before any object is left attached to the Behave context. This catches problems early, including:

invalid scope values
non-importable factories
unknown $ref targets
unknown $var names
cycles between object references
invalid wider-to-narrower scope dependencies

Tip

If you want to inject an instance under a shorter or more domain-specific name, use inject_as. Otherwise the toolkit exposes it with the object name.

Parser configuration¶

The optional parsers section configures Behave custom types and the default step matcher.

Field	Purpose
`step_matcher`	Default Behave matcher to use while step modules are imported.
`types`	Mapping of custom type names to parser helper specs.

Each custom type can either reference an existing converter or generate one from an enum:

Field	Purpose
`converter`	Import path to a callable that converts raw text.
`enum`	Import path to an `Enum` class. The toolkit builds the converter for you.
`pattern`	Regex pattern attached to the converter if it does not already define one.
`regex_group_count`	Optional regex group count metadata for advanced parse patterns.
`matcher`	Per-type matcher override for registration (`parse` or `cfparse`).
`case_sensitive`	Enum helper option controlling case-sensitive lookup.
`lookup`	Enum helper mode: `value` or `name`.

See Parser helpers for end-to-end examples.

Logging configuration¶

If you only want one persistent test-run.log, you can skip logging: entirely and call configure_test_logging(...) yourself from before_all().

Use the optional logging section when you want multiple named loggers to be materialized by configure_loggers(context) from before_all().

logging:
  test_run:
    path:
      $ref: test_log_path
    logger_name: suite-tests
    inject_as: test_logger

  diagnostics:
    path:
      $ref: diagnostics_log_path
    logger_name: suite-diagnostics
    inject_as: diagnostics_logger
    console: false

Each logger supports:

Field	Purpose
`path`	File path or marker-based value used for the log file.
`logger_name`	Optional underlying Python logger name. Defaults to the logger key.
`inject_as`	Optional Behave context attribute name for the logger object.
`level`	Logging level passed to Python logging. Defaults to `INFO`.
`console`	Mirror output to console in addition to the file. Defaults to `true`.
`mode`	File open mode, for example `w` or `a`. Defaults to `w`.

path supports the same marker style as object arguments:

$ref to a configured object, such as a pathlib.Path
$ref + attr for one attribute path
$var to reuse a root variable

Logger references are intentionally global in this first version, so configure them after global objects are active.

With the default install(context, CONFIG_PATH), global objects are already active, so configure_loggers(context) can run immediately after install().
If you use install(..., activate_global=False), call activate_global_scope(context) first and then configure_loggers(context).