behave-hive

Run behave 1.3.x scenarios in parallel, read Examples: from CSV files and get Allure, Cucumber JSON and HTML reports in one run.

• Examples from CSV: point an Examples: table at a file with its path, | data/users.csv |, or the equivalent | read('data/users.csv') |. CSV and hand-written tables can live in the same outline.
• Sequential or parallel runs: set in the [behave_hive] section of behave.ini, or with --parallel/--no-parallel.
• Consolidated reports: Allure results, standard Cucumber JSON and a self-contained HTML report with filters, metrics and screenshots.

Your steps, your environment.py and the way you write features stay the same. A .feature without CSV cells runs exactly as it does with behave. behave-hive complements behave; if you only need a parallel runner with its own report, BehaveX is another option.

Contents: Installation · Quick start · Examples from CSV · Running · Configuration · Reports · Examples · Limitations · Roadmap · Contributing · Releasing

Installation

Install behave-hive in the same environment as your behave project, with uv:

uv add behave-hive                      # in a uv project; or: uv pip install behave-hive
uv add "behave-hive[allure]"            # adds allure-behave 2.16.2 for the Allure format
uv add "behave-hive[playwright]"        # only needed to run the example

pip works too: pip install behave-hive, pip install "behave-hive[allure]".

Requires Python 3.11 or newer. macOS and Linux are supported; Windows is not (see Limitations). Run the commands in this guide with uv run (for example uv run behave-hive run), or activate the environment first.

Quick start

features/login.feature:

Feature: Login

  Scenario Outline: Login as <user>
    Given I open the login page
    When I sign in with user "<user>" and password "<password>"
    Then I see the message "<message>"

    Examples:
      | data/login.csv |

features/data/login.csv:

user,password,message
admin,1234,Welcome
admin,wrong,Invalid credentials

uv run behave-hive run --parallel -w 2

Examples: 0 inline, 1 from CSV
  - features/data/login.csv
Mode: parallel (2 workers, scheme scenario)
batch 1 · worker 1 · 1 scenario · passed · 1.6s
batch 2 · worker 2 · 1 scenario · passed · 1.6s
1 feature · 2 scenarios (2 passed) · 6 steps (6 passed) · 1.7s

Open report.html (project root by default) for the result; the Cucumber JSON, Allure results and logs are in reports/. The steps used here are in example/, which runs as is.

Examples from CSV

Feature: Login

  Scenario Outline: Login as <user>
    Given I open the login page
    When I sign in with user "<user>" and password "<password>"
    Then I see the message "<message>"

    Examples: valid credentials
      | data/login.csv |

data/login.csv:

user,password,message
admin,1234,Welcome
admin,wrong,Invalid credentials

A table is read from CSV when its first row has one cell that is a path ending in .csv. That plain path is the default form:

    Examples:
      | data/login.csv |

read('path.csv') and read("path.csv") mean exactly the same; use them if you prefer the explicit spelling:

    Examples:
      | read('data/login.csv') |

Any other table is a regular, hand-written one. Both kinds can live in the same outline, each under its own Examples:, and each keeps its own tags:

    @smoke
    Examples: from a file
      | data/login.csv |

    Examples: written by hand
      | user  | password | message             |
      | guest | guest    | Invalid credentials |

The CSV path is relative to the directory of the .feature file (subdirectories and .. are fine). The Examples: keyword follows the language of the feature (# language: directive or lang in [behave]).

CSV contract

• UTF-8, with or without a BOM. The first row is the header; its names are the <placeholders>.
• Physically empty lines are ignored. Empty cells are kept.
• Spaces around a cell are lost, as in any Gherkin table. A | inside a cell is written as \| for you, and the step receives it intact.
• Rejected, with exit code 2 and a message naming the .feature, the line, the CSV and the CSV row: no data rows, empty or duplicated headers (after stripping spaces), rows whose width differs from the header, cells with a line break, a missing file and invalid UTF-8.
• Text inside """ or ''' docstrings is never interpreted as Examples:.

What behave-hive writes

When a CSV table is present, the whole features root is copied to a working directory: .feature files are written expanded and every other file is a symlink to the original. uris in the reports are the original ones; the HTML report shows path.csv:row next to each scenario. To see the result:

behave-hive expand features /tmp/expanded

expand refuses, without deleting anything, a destination that is the source or one of its ancestors, a symlink, or a non-empty directory not created by a previous expansion.

Running

behave-hive run                         # uses [behave_hive] from behave.ini
behave-hive run --parallel -w 4         # 4 processes
behave-hive run --no-parallel           # one process per features root
behave-hive run features/login.feature   # a directory or a single .feature file
behave-hive run -- --tags=@smoke -D env=qa   # everything after -- goes to behave

Every path belongs to a features root: the closest directory, walking up, that contains steps/. Inputs with the same root share one expansion, and a scenario reachable through two inputs runs once.

Parallel by scenario or by feature

With parallel = true, behave-hive splits the suite into units and gives them to up to workers processes. scheme decides what a unit is:

behave-hive run --parallel --scheme scenario -w 4    # rows and scenarios spread over 4 processes
behave-hive run --parallel --scheme feature -w 2     # one process per feature, 2 at a time

The same keys work in the configuration file (parallel, workers, scheme, chunk); example/configs/ has a ready-made file for each case. A scenario's own steps never run in parallel. chunk sets how many units each process receives (0 shares them evenly). before_all and after_all in environment.py run once per process, so use BEHAVE_HIVE_WORKER to keep ports or users apart.

Exit codes: 0 all good, 1 a failed, undefined or pending scenario or a batch error, 2 usage, configuration or CSV error, 130 interrupted with Ctrl+C. When nothing matches, No scenarios found is printed and the exit code is 0.

Configuration

Put a [behave_hive] section next to [behave] in behave.ini, .behaverc, setup.cfg or tox.ini, or a [tool.behave_hive] table in pyproject.toml. Files are looked up in the working directory in that order and the first one with the section wins. behave ignores the section.

[behave]
default_tags = not @expected_fail

[behave_hive]
parallel = true
workers = 3
scheme = scenario
formats = allure, cucumber, html
report_name = My QA project
report_path = reports/report.html

Precedence, lowest to highest: default, file, command line. Arguments after -- are appended after behave_args. An unknown key is an error. behave's own settings (default_tags, tags, lang, ...) keep their meaning; --tags on the command line overrides default_tags, as in behave.

The project root is the selected configuration file's directory, or the working directory when no configuration section is selected. An omitted/blank HTML name uses [project].name from that root's pyproject.toml, then the folder name. HTML is now written at the project root by default. Set report_path = reports/report.html to retain the earlier destination. These settings do not change the generated Allure report's name.

Arguments behave-hive controls

These are rejected, in behave_args and after --, with exit code 2:

• positional arguments and @files (paths go before --);
• -f/--format, -o/--outfile, -r/--runner, --junit, --junit-directory;
• -d/--dry-run, --stop, -i/--include, -e/--exclude, -n/--name, -w/--wip.

The same applies to the effective behave configuration: stop, dry_run, steps_catalog, junit, wip, name filters, include/exclude, stage and a custom runner in [behave] are rejected, and so are --version, --tags-help, --lang-list and --lang-help. format and outfiles from [behave] are ignored.

Worker identification

Each behave process receives BEHAVE_HIVE_WORKER (the slot, 1..workers; always 1 in sequential mode) and BEHAVE_HIVE_BATCH (the 1-based batch index). Two active processes never share a slot, so they can pick ports, users or databases:

import os
port = 9000 + int(os.environ.get("BEHAVE_HIVE_WORKER", "1"))

@setup and @teardown

behave runs scenarios tagged @setup or @teardown even when they are not selected. With parallel = true and scheme = scenario, a feature containing them is rejected; use scheme = feature or sequential mode.

Reports

JSON, Allure and logs are written to results_dir (default reports/). The HTML file uses report_path independently (default <project-root>/report.html):

Every generated HTML carries a behave-hive-report-4f9c2e7a generator marker in its head. At the start of a run behave-hive deletes the previous file at report_path only when it is a regular file with that marker, so an aborted run never leaves an old report that looks current, and any other file at report_path is never touched.

At the start of a run behave-hive deletes only what it manages (cucumber.json, report.html, allure-results/, logs/, tmp/); anything else in results_dir is kept. A second run on the same results_dir exits with code 2.

Scenario and feature ids are stable: they do not depend on workers, chunk or input order. Hook failures and failed context.add_cleanup functions count as failed (broken in Allure). A pending step counts as pending, except inside a @wip scenario.

Allure attachments and environment

Data attached with context.attach(mime_type, data) (for example a screenshot in after_step) is stored in allure-results/ and attached to the step that made it; data attached after the last step goes to the last step, and data attached before any step is ignored. environment.properties lists behave-hive, behave and python versions, mode (parallel or sequential), workers and scheme.

The HTML report

• Failures first: inside each feature, failed, undefined and pending scenarios come first and are open; each shows the first line of its error (the last line when the first one is only a prefix such as ASSERT FAILED:) and a Copy error button.
• Run context: start time, mode, workers, scheme, versions, the command without your home or project path, the wall-clock time, the sum of scenario times and, in parallel mode, the speedup between them.
• Worker and batch: each scenario names its worker, its batch and logs/batch-<n>.log.
• Outline groups: the rows of a Scenario Outline are grouped under the outline, with the row count and the number of rows that did not pass.
• Shareable filters: the search text, status and tag filters are kept in the address as #search=...&status=...&tag=..., for example report.html#status=failed&tag=@smoke. Unknown values are ignored.

A failed scenario opens with its error headline, a Copy error button, the worker and batch that ran it, and the screenshot taken by your after_step hook (the traceback below the steps is hidden in this picture):

Filters live in the address, so a filtered view can be shared; #status=passed&tag=@smoke shows this:

Privacy and security of the HTML

The HTML carries a default-deny Content-Security-Policy with the hash of its exact inline script, inline styles and data: images. Paths in error messages and in the command are rewritten as described under Limitations: the run directory becomes the original path, the project directory becomes relative and your home becomes ~. Screenshots and error texts are reported as they are.

CucumberJSONFormatter also works without behave-hive:

behave features -f behave_hive.formatters.cucumber:CucumberJSONFormatter -o out.json

Examples

example/ is a runnable project (Playwright and a local login page) with one example for each feature. Its README lists them with the command to run each one.

git clone https://github.com/albertor03/behave-hive && cd behave-hive/example
uv venv && uv pip install "behave-hive[allure,playwright]"
uv run python -m playwright install chromium
uv run behave-hive run                               # as configured in behave.ini
uv run behave-hive run --config configs/sequential.ini
uv run behave-hive run -- --tags=@smoke              # only the @smoke Examples table

Gherkin in other languages works too: the Examples: keyword follows the feature's language, as shown in tests/fixtures/i18n/.

Limitations

• Lines in expanded features: rows generated from a CSV, and everything after them in the file, report the lines of the expanded file. The uri is the original one and the HTML shows csv:row; files without CSV keep their lines.
• Path(__file__) in steps: steps run through symlinks in the expanded tree. Use Path(__file__).resolve() to reach files next to the original step.
• Unbalanced batches: units are split into consecutive chunks. Use chunk = 1 for dynamic balancing, at the cost of one process per unit.
• allure-behave is pinned to 2.16.2, because the Allure formatter relies on its internals.
• POSIX only (macOS and Linux): the run lock uses fcntl.flock, interruption signals whole process groups (os.killpg) so browsers started by a step do not survive Ctrl+C, and the expanded copy of your features links every non-feature file with symlinks. None of these exist, or work without special privileges, on Windows. CI covers Linux and macOS only. WSL runs Linux and should work, but it is not tested.
• Not supported: --stop, --dry-run, --include, --exclude, --name, --wip, retries, and data sources other than CSV (JSON files are planned, see the Roadmap).
• CSV access is not sandboxed: a feature may reference any CSV readable by the current user, including paths with ..; its rows can appear in reports.
• Retained run configuration: --keep-tmp preserves private plans and locations, including -D key=value arguments. These files are owner-only (0600, inside a 0700 temporary directory); remove retained runs when no longer needed. The results lock is also owner-only.
• Report privacy: behave-hive rewrites expanded roots, the working directory and the home prefix in error messages to original relative paths or ~. The directly used Cucumber formatter (behave -f) has no run path map and does not perform this rewriting. Screenshots and attached data are not scrubbed and may contain sensitive application data; scenario inputs can also appear.
• Expansion race window: destination checks are repeated before deletion and marker creation. This narrows, but does not eliminate, filesystem races.

Roadmap

Next on the list:

• Windows support: replace the POSIX-only pieces described under Limitations (file lock, process groups and symlinks) and add Windows to CI.
• JSON data files: read Examples: from a .json file, next to CSV, with the same plain-path form.

Contributing

Pull requests are welcome. CONTRIBUTING.md explains how to set up the project, the checks that must pass and how CI works. AGENTS.md describes the layout and the conventions.

Releasing

Releases are tagged and published to PyPI by a workflow; the maintainer's checklist is in docs/RELEASING.md.

License

MIT, see LICENSE.