Metadata-Version: 2.4
Name: bpp-anubis
Version: 2026.4.28
Summary: Run behave tests in parallel
Home-page: https://gitlab.com/blueprintprep/bpp-qa/utilities/anubis
Author: matthew bahloul
Author-email: matthew.bahloul@blueprintprep.com
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
License-File: LICENSE
Requires-Dist: behave>=1.2.6
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

anubis
======

.. image:: https://img.shields.io/pypi/v/bpp-anubis.svg
    :target: https://pypi.python.org/pypi/bpp-anubis
    :alt: Latest PyPI version

A Python CLI tool for running Gherkin/Behave BDD tests in parallel with comprehensive in-memory result aggregation and reporting.

**Anubis** orchestrates parallel execution of Behave test suites, distributing scenarios across multiple worker processes for faster feedback. It handles test parsing, distribution, aggregation, and generates console output (with Behave formatter pass-through available for additional formats).

Features
--------

- **Parallel Test Execution**: Distribute tests across N worker processes for faster execution
- **Flexible Granularity**: Run tests at feature, scenario, or example (scenario outline rows) level
- **Smart Tag Filtering**: Leverage Behave's full tag expression syntax for test selection
- **Result Aggregation**: Automatically merge results from all workers into unified reports
- **Formatted Console Summary**: Aggregated pass/fail summary and per-feature scenario details
- **Dry-run Mode**: Parse and validate tests without execution
- **Configurable Pass Thresholds**: Set minimum pass rates for CI/CD integration
- **Full Behave Compatibility**: Pass any Behave argument through to the runner

Installation
------------

From PyPI:

.. code-block:: bash

    pip install bpp-anubis

From source:

.. code-block:: bash

    git clone <repository>
    cd anubis
    pip install -e .

For development (includes build and documentation tools):

.. code-block:: bash

    pip install -r requirements-dev.txt

Quick Start
-----------

Run all tests in the ``features`` directory (default):

.. code-block:: bash

    anubis

Run tests from a specific path with 4 parallel workers:

.. code-block:: bash

    anubis --features tests/features --processes 4

Run only tests tagged with ``@automated``, excluding ``@flaky``:

.. code-block:: bash

    anubis --features tests/features --tags @automated --tags ~@flaky

Dry-run to validate feature files:

.. code-block:: bash

    anubis --features tests/features --dry-run

Run scenarios with custom Behave definitions:

.. code-block:: bash

    anubis --features tests/features -D env=staging -D browser=chrome

For detailed usage and all available options, see `README.md <README.md>`_.

Requirements
------------

**Runtime:**

- Python 3.10+
- behave >= 1.2.6 (dynamically supports all compatible versions)

**Development:**

See ``requirements-dev.txt`` for build, packaging, and documentation tools.

Usage
-----

Anubis is designed to be intuitive for users familiar with Behave. Core concepts:

**Granularity** (``--unit``):
    - ``feature``: Each feature file is one test unit
    - ``scenario``: Each scenario (including outlines) is one test unit
    - ``example``: Each row in a scenario outline is a separate test (default, most parallelizable)

**Tags** (``--tags``):
    Standard Behave tag filtering with support for complex expressions:
    ``--tags @automated --tags ~@flaky`` runs automated tests excluding flaky ones

**Processes** (``--processes``):
    Number of parallel workers. Default is 1 (sequential). Increase for faster execution on multi-core systems.

**User Definitions** (``-D``):
    Pass variables to Behave step implementations. Format: ``-D key=value``

Exit Codes
^^^^^^^^^^

- **0**: Tests passed (pass rate >= threshold) or no tests found with ``--pass-with-no-tests``
- **1**: Tests failed or pass rate below threshold

Output
^^^^^^

By default, worker result files are written to the ``.output`` directory:

- ``json_results/`` - Individual worker results (temporary)

CLI notes:

- ``--junit`` is deprecated and explicitly rejected by the parser
- ``--delete-output`` has been removed
- ``--log-file``, ``--log-std-out``, and ``--log-level`` have been removed
- For JUnit/other result files, use Behave pass-through formatter flags

Migration note:

- Heavy post-run worker log synthesis was removed to reduce post-run lag. Console output and Behave formatter pass-through remain available.

Configuration
^^^^^^^^^^^^^

All behavior is controlled via command-line arguments. See README.md for comprehensive documentation of all options.

Examples
--------

Run tests with custom output directory:

.. code-block:: bash

    anubis --features tests/features --output ./results

Run tests at scenario level with 80% pass threshold:

.. code-block:: bash

    anubis --features tests/features --unit scenario --pass-threshold 0.8 --processes 8

Run regression tests, excluding known flaky and slow tests:

.. code-block:: bash

    anubis --features tests/features --tags @regression --tags ~@flaky --tags ~@slow

Contributing
------------

Contributions are welcome. Please ensure code follows project conventions and includes appropriate documentation.

Architecture
------------

See `agents.md <agents.md>`_ for detailed architecture documentation, including:
- Component descriptions and relationships
- Execution flow and data pipelines
- Design patterns and extension points
- Known limitations

License
-------

MIT

Authors
-------

`anubis` was written by `matthew bahloul <matthew.bahloul@blueprintprep.com>`_.

Support
-------

For issues, questions, or suggestions, please contact the development team or file an issue in the repository.
