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

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

Usage

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

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.