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 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 results in multiple formats (JSON, JUnit XML, console output).

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
- **Multiple Output Formats**: JSON, JUnit XML, and formatted console output
- **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, results are written to the ``.output`` directory:

- ``results.json`` - Aggregated test results in JSON format
- ``results.xml`` - JUnit XML format for CI/CD integration
- ``logs/anubis.log`` - Execution log with detailed information
- ``json_results/`` - Individual worker results (temporary)

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

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

Examples
--------

Run tests with verbose logging and custom output directory:

.. code-block:: bash

    anubis --features tests/features --output ./results --log-std-out

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

Run with cleanup (delete output directory after completion):

.. code-block:: bash

    anubis --features tests/features --delete-output --processes 4

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.
