Metadata-Version: 2.4
Name: hivescope
Version: 0.1.0
Summary: Hivescope: E2E testing library for HiveMind protocol
Author-email: JarbasAi <jarbasai@mailfence.com>
License: AGPL-3.0
Keywords: hivemind,protocol,testing,e2e,pytest
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: hivemind-bus-client>=0.7.0a2
Requires-Dist: hivemind-core>=4.0
Requires-Dist: ovos-utils>=0.0.40
Requires-Dist: pytest>=7.4
Requires-Dist: websockets>=11
Provides-Extra: ovos
Requires-Dist: ovoscope>=0.13; extra == "ovos"
Requires-Dist: ovos-core>=0.0.30; extra == "ovos"

# Hivescope

A self-contained pytest-based E2E testing library for HiveMind protocol implementations.

## Install

```bash
pip install "hivescope @ git+https://github.com/JarbasHiveMind/hivescope@dev"
```

With OVOS skill-level testing support:

```bash
pip install "hivescope[ovos] @ git+https://github.com/JarbasHiveMind/hivescope@dev"
```

## Quick Start

```python
from hivescope.scenarios import single_satellite
from hivescope.assertions import assert_handshake_complete, assert_encryption_match

def test_handshake():
    builder = single_satellite()
    builder.start_all()
    try:
        master = builder.get_master("M0")
        satellite = builder.get_satellite("S0")
        assert_handshake_complete(master, satellite)
        assert_encryption_match(master, satellite)
    finally:
        builder.stop_all()
```

Using pytest fixtures (add to `tests/conftest.py`):

```python
pytest_plugins = ['hivescope.pytest_fixtures']
```

```python
def test_message_forwarded(master_node, satellite_node):
    from ovos_bus_client.message import Message
    satellite_node.send(Message("test:ping", {}))
    master_node.recorder.assert_received("BUS", count=1)
```

## Templates

Copy-paste test templates from `templates/` into your repo's `tests/e2e/`:

| Template | Covers |
|---|---|
| `test_template_handshake.py` | Cipher/encoding agreement, handshake completion |
| `test_template_routing.py` | Message routing through master |
| `test_template_acl.py` | ACL enforcement for restricted satellites |
| `test_template_binary.py` | Binary protocol message handling |

## Configuration

| Key | Default | Purpose |
|---|---|---|
| `use_loopback` | `False` | Pass `True` to `add_master()` to use loopback network protocol instead of in-process |
| `[ovos]` extra | not installed | Enables `OvoscopeAgentProtocol` backed by a live MiniCroft |

## API Reference

See [docs/index.md](docs/index.md) for the full public API.

## License

AGPL-3.0
