Metadata-Version: 2.4
Name: anna-executa-test
Version: 0.1.1
Summary: Pytest plugin + helpers for testing Anna Executa stdio JSON-RPC plugins.
Author: Talent AI
License: MIT
Keywords: anna,executa,jsonrpc,plugin,pytest
Requires-Python: >=3.10
Requires-Dist: pytest>=7.0
Description-Content-Type: text/markdown

# anna-executa-test

Pytest plugin and helpers for testing Anna **Executa** stdio JSON-RPC tool
plugins.

Companion to `@anna/cli` and `@anna/app-test` — covers the *plugin* side of
an Anna App while `@anna/app-test` covers the *bundle* side.

## Install

```bash
uv pip install anna-executa-test
# or
pip install anna-executa-test
```

## Usage

Drop a `tests/test_smoke.py` next to your plugin:

```python
from pathlib import Path
import pytest
from anna_executa_test import describe_plugin, executa, assert_jsonrpc_ok

PLUGIN_DIR = Path(__file__).parent.parent

@pytest.fixture(scope="module")
def plugin():
    with executa.spawn(PLUGIN_DIR) as p:
        yield p

def test_describe(plugin):
    info = plugin.call("describe")
    assert info["name"].startswith("tool-")
    assert info["tools"], "plugin should declare at least one tool"

def test_invoke_get_state(plugin):
    resp = plugin.call("invoke", {"tool": "session", "arguments": {"action": "get_state"}})
    assert resp["success"] is True
```

## Public API (Phase 5 MVP)

- `executa.spawn(project_dir, *, command=None, env=None)` — context manager
  spawning the plugin under `uv run`. Returns `ExecutaClient`.
- `ExecutaClient.call(method, params=None, *, timeout=10.0)` — one
  JSON-RPC request/response round-trip.
- `ExecutaClient.invoke(tool, arguments)` — sugar for the common case.
- `ExecutaClient.describe()` / `.health()` — sugar for the standard
  control methods.
- `assert_jsonrpc_ok(resp)` / `assert_jsonrpc_error(resp, code=...)`
- `wire_format.validate_response(env)` — strict envelope shape check
  matching `nexus.executa_wire`.
- `contract.contract_for(project_dir)` — read `pyproject.toml` + spawn
  briefly to capture `MANIFEST`; exposes `.parametrize_invoke(...)`.
- `mock_state_dir(tmp_path)` — pytest fixture overriding `XDG_STATE_HOME`
  and friends.
