Metadata-Version: 2.4
Name: pytest-arrakis
Version: 0.3.0
Summary: Pytest plugin providing Arrakis fixtures for testing
Project-URL: Homepage, https://git.ligo.org/ngdd/pytest-arrakis
Author-email: Olivia Godwin <olivia.godwin@ligo.org>
License-Expression: LGPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: arrakis-server>=0.9
Requires-Dist: mockafka-py
Requires-Dist: pytest
Provides-Extra: publish
Requires-Dist: arrakis-backend-kafka>=0.6; extra == 'publish'
Requires-Dist: pytest-kafka-broker; extra == 'publish'
Description-Content-Type: text/markdown

<h1 align="center">pytest-arrakis</h1>

<p align="center">Pytest plugin providing <a href="https://git.ligo.org/ngdd/arrakis-python">Arrakis</a> fixtures for testing</p>

<p align="center">
  <a href="https://pypi.org/project/pytest-arrakis/">
    <img alt="pypi version" src="https://img.shields.io/pypi/v/pytest-arrakis.svg" />
  </a>
</p>

---

## Resources

* [Source Code](https://git.ligo.org/ngdd/pytest-arrakis)
* [Issue Tracker](https://git.ligo.org/ngdd/pytest-arrakis/-/issues)

## Installation

```
pip install pytest-arrakis
```

To enable publish fixtures (including a real Kafka-backed server), install the `publish` extra:

```
pip install pytest-arrakis[publish]
```

## Fixtures

### Core fixtures

These are available out of the box:

| Fixture | Scope | Description |
| --- | --- | --- |
| `arrakis_channel_configs` | session | List of paths to the bundled per-publisher config files |
| `arrakis_backend` | session | A `MockBackend` configured with the bundled test channels |
| `arrakis_server` | session | A running mock `ArrakisFlightServer` (sets `ARRAKIS_SERVER` env var) |
| `arrakis_channels` | session | Dict of channel metadata loaded from the bundled TOML |
| `arrakis_mock_publisher` | function | A mocked `Publisher` with `FakeProducer` for sink testing (no server/broker needed) |

### Publish fixtures (requires `publish` extra)

These are conditionally registered when `arrakis-backend-kafka` and `pytest-kafka-broker` are installed:

| Fixture | Scope | Description |
| --- | --- | --- |
| `arrakis_publish_backend` | function | A real `KafkaBackend` pointed at an embedded Kafka broker |
| `arrakis_publish_server` | function | A publish-capable `ArrakisFlightServer` backed by Kafka |
| `arrakis_publisher` | function | A real `Publisher` registered against the embedded broker |

## Usage

### Fetching data from a mock server

``` python
def test_fetch(arrakis_server):
    import arrakis

    block = arrakis.fetch(["H1:TEST-CHANNEL_SIN"], 0, 1)
    for channel, series in block.items():
        assert len(series) > 0
```

### Testing a publisher without a real broker

``` python
def test_publish(arrakis_mock_publisher):
    publisher, fake_producer, published_blocks = arrakis_mock_publisher

    # publish a block through your code under test ...
    assert len(published_blocks) == 1
```

### End-to-end publish testing (requires `publish` extra)

``` python
def test_roundtrip(arrakis_publisher):
    # arrakis_publisher is a real Publisher connected to an embedded Kafka broker
    ...
```

## Bundled test channels

The plugin ships with a set of test channel definitions:

| Channel | Publisher | Sample Rate | Data Type |
| --- | --- | --- | --- |
| `H1:TEST-CHANNEL_SIN` | `FAKE_H1` | 512 | float32 |
| `H1:TEST-CHANNEL_COS` | `FAKE_H1` | 16384 | float64 |
| `H1:TEST-STATE_ONES` | `FAKE_H1` | 16 | int32 |
| `L1:TEST-NOISE` | `FAKE_L1` | 4096 | float32 |

## CI setup

### GitLab CI

The core fixtures work without any extra system dependencies. However, the
`publish` extra uses `pytest-kafka-broker`, which starts an embedded Kafka
broker that **requires a JVM** at runtime. In Debian/Ubuntu-based CI images
(including the standard `python:` Docker images), install it in a
`before_script`:

```yaml
test:
  image: python:3.13
  before_script:
    - apt-get update && apt-get install -y --no-install-recommends default-jre-headless
```

If you only use the core fixtures (no `publish` extra), the JVM is not needed.
