behave-hive 0.1.0__tar.gz

behave_hive-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alberto Zapata
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

behave_hive-0.1.0/PKG-INFO

@@ -0,0 +1,408 @@
+Metadata-Version: 2.4
+Name: behave-hive
+Version: 0.1.0
+Summary: Run behave scenarios in parallel with Examples read from CSV files, and get Allure, Cucumber JSON and HTML reports
+Author: Alberto Zapata
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/albertor03/behave-hive
+Project-URL: Issues, https://github.com/albertor03/behave-hive/issues
+Keywords: behave,bdd,csv,parallel,allure,cucumber
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Testing :: BDD
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: behave<1.4,>=1.3
+Provides-Extra: allure
+Requires-Dist: allure-behave==2.16.2; extra == "allure"
+Provides-Extra: playwright
+Requires-Dist: playwright>=1.40; extra == "playwright"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: jsonschema>=4; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: pytest-cov>=7; extra == "dev"
+Requires-Dist: coverage>=7.10; extra == "dev"
+Requires-Dist: pip-audit; extra == "dev"
+Dynamic: license-file
+
+# behave-hive
+
+Run [behave](https://github.com/behave/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](https://github.com/hrcorval/behavex) is another option.
+
+**Contents:** [Installation](#installation) · [Quick start](#quick-start) · [Examples from CSV](#examples-from-csv) · [Running](#running) · [Configuration](#configuration) · [Reports](#reports) · [Examples](#examples) · [Limitations](#limitations) · [Roadmap](#roadmap) · [Contributing](#contributing) · [Releasing](#releasing)
+
+## Installation
+
+Install behave-hive in the same environment as your behave project, with [uv](https://docs.astral.sh/uv/):
+
+```bash
+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](#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`:
+
+```gherkin
+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`:
+
+```csv
+user,password,message
+admin,1234,Welcome
+admin,wrong,Invalid credentials
+```
+
+```bash
+uv run behave-hive run --parallel -w 2
+```
+
+```text
+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
+```
+
+![HTML report overview: status, run context, durations and the feature table](docs/images/report-overview.png)
+
+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/`](example/), which runs as is.
+
+## Examples from CSV
+
+```gherkin
+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`:
+
+```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:
+
+```gherkin
+    Examples:
+      | data/login.csv |
+```
+
+`read('path.csv')` and `read("path.csv")` mean exactly the same; use them if you prefer the explicit spelling:
+
+```gherkin
+    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:
+
+```gherkin
+    @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. `uri`s in the reports are the original ones; the HTML report shows `path.csv:row` next to each scenario. To see the result:
+
+```bash
+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
+
+```bash
+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.
+
+| Option | Meaning |
+|---|---|
+| `--parallel` / `--no-parallel` | Override `parallel`. |
+| `-w`, `--workers N` | Number of processes. |
+| `--scheme scenario\|feature` | Distribute scenarios (and outline rows) or whole features. |
+| `--chunk N` | Units per process; `0` splits the units of a root evenly among the workers. |
+| `--results-dir DIR` | Where JSON, Allure results and logs go; HTML uses `report_path`. |
+| `--formats LIST` | Any of `allure`, `cucumber`, `html`. |
+| `--config FILE` | Read `[behave_hive]` from this file only. |
+| `--keep-tmp` | Keep `results_dir/tmp/` (partial results, locations files). |
+
+### 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:
+
+| `scheme` | A unit is | Use it when |
+|---|---|---|
+| `scenario` (default) | One scenario, or one row of a Scenario Outline (from CSV or written by hand). | Scenarios are independent. A file with 4 data rows runs as 4 units, in parallel. |
+| `feature` | One whole `.feature` file; its scenarios run in order in the same process. | Scenarios of a feature depend on each other, share an expensive `before_feature`, or use `@setup`/`@teardown`. The same 4-row file is 1 unit. |
+
+```bash
+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/`](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`](#worker-identification) 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.
+
+```ini
+[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
+```
+
+| Key | Default | Notes |
+|---|---|---|
+| `parallel` | `false` | `true/false`, `yes/no`, `on/off`, `1/0`. Sequential mode ignores `workers`, `scheme` and `chunk`. |
+| `workers` | number of CPUs | At least 1. |
+| `scheme` | `scenario` | `scenario` or `feature`. |
+| `chunk` | `0` | At least 0. |
+| `results_dir` | `reports` | |
+| `report_name` | project name | HTML title and heading only; blank also uses the fallback. |
+| `report_path` | `<project-root>/report.html` | Full HTML filename; relative to the project root, or absolute. Parents are created. |
+| `formats` | `cucumber, html` | Comma or space separated; TOML arrays work too. |
+| `work_dir` | `.behave-hive` | Each run uses its own subdirectory. |
+| `behave_args` | empty | Shell-style string (`--tags="@a and not @b" -D env=qa`) or a TOML array. `%` is literal. |
+| `paths` | `features` | What to run when no path is given. |
+
+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 `@file`s (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:
+
+```python
+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`):
+
+| Path | Format |
+|---|---|
+| `cucumber.json` | Standard Cucumber JSON, scenarios in line order, each preceded by its background. |
+| `allure-results/` | One Allure result per scenario that behave selected, including scenarios inside a `Rule`, with `context.attach(...)` data as attachments of their step and an `environment.properties` file. Open it with the Allure CLI: `npx allure@3 generate reports/allure-results`. |
+| `report_path` | Self-contained HTML with inline filters, no external requests, light and dark mode; project name in title and heading. |
+| `logs/batch-<n>.log` | Output of each behave process. |
+
+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):
+
+![A failed scenario with its steps and the screenshot attached to the failed step](docs/images/report-failure.png)
+
+Filters live in the address, so a filtered view can be shared; `#status=passed&tag=@smoke` shows this:
+
+![The toolbar with the status and tag filters applied and one matching scenario](docs/images/report-filters.png)
+
+### 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](#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:
+
+```bash
+behave features -f behave_hive.formatters.cucumber:CucumberJSONFormatter -o out.json
+```
+
+## Examples
+
+[`example/`](example/) is a runnable project (Playwright and a local login page) with one example for each feature. Its [README](example/README.md) lists them with the command to run each one.
+
+| Example | Shows |
+|---|---|
+| [`features/login.feature`](example/features/login.feature) | CSV table, hand-written table and a table that fails on purpose (screenshot as evidence). |
+| [`features/csv/forms.feature`](example/features/csv/forms.feature) | The plain path (the default form), `read('...')` with single and double quotes, and a shared file through `..`. |
+| [`features/csv/mixed_and_tagged.feature`](example/features/csv/mixed_and_tagged.feature) | CSV (plain path and `read()`) and hand-written tables in one outline, each with its own tags. |
+| [`features/csv/special_characters.feature`](example/features/csv/special_characters.feature) | Pipes, commas and percent signs inside cells. |
+| [`features/structure/background_and_rule.feature`](example/features/structure/background_and_rule.feature) | `Background` and `Rule` with CSV `Examples:`. |
+| [`features/structure/step_data.feature`](example/features/structure/step_data.feature) | Step tables and docstrings, never read as `Examples:`. |
+| [`configs/`](example/configs/) | Sequential, `scheme = feature` and TOML configurations. |
+
+```bash
+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/`](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](#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](#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](CONTRIBUTING.md) explains how to set up the project, the checks that must pass and how CI works. [AGENTS.md](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](docs/RELEASING.md).
+
+## License
+
+MIT, see [LICENSE](LICENSE).