uagent-testkit 0.1.0__py3-none-any.whl

uagent_testkit/__init__.py

@@ -0,0 +1,48 @@
+"""uagent-testkit — test Fetch.ai uAgents without a network, a wallet, or a sleep().
+
+    from uagent_testkit import harness
+
+    h = harness(my_agent)
+    result = await h.deliver(Ping(text="hi"))
+    assert result.reply(Pong).text == "pong:hi"
+"""
+
+from ._loop import ensure_event_loop
+from ._recording import Sent
+from ._storage import InMemoryStore
+from .harness import (
+    ANY,
+    DEFAULT_SENDER,
+    AgentHarness,
+    Delivery,
+    HandlerNotFound,
+    UnverifiedSender,
+    harness,
+    user_sender,
+)
+from .network import (
+    AgentNetwork,
+    ConversationTooLong,
+    Exchange,
+    Transcript,
+)
+
+__all__ = [
+    "ANY",
+    "AgentHarness",
+    "AgentNetwork",
+    "ConversationTooLong",
+    "DEFAULT_SENDER",
+    "Delivery",
+    "Exchange",
+    "HandlerNotFound",
+    "InMemoryStore",
+    "Sent",
+    "Transcript",
+    "UnverifiedSender",
+    "ensure_event_loop",
+    "harness",
+    "user_sender",
+]
+
+__version__ = "0.1.0"

uagent_testkit/_loop.py

@@ -0,0 +1,30 @@
+"""Keep an event loop available for Agent construction.
+
+`Agent.__init__` calls `get_event_loop()` and stores the result, so building an
+agent at import time or inside a synchronous pytest fixture raises
+`RuntimeError: There is no current event loop` on Python 3.12+. Since the canonical
+uAgents idiom is a module-level `agent = Agent(...)`, that would make most real
+agents untestable without restructuring them. We make sure a loop is set instead.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+
+def ensure_event_loop() -> asyncio.AbstractEventLoop:
+    """Return the current event loop, creating and installing one if needed."""
+    try:
+        return asyncio.get_running_loop()
+    except RuntimeError:
+        pass
+
+    try:
+        loop = asyncio.get_event_loop_policy().get_event_loop()
+    except RuntimeError:
+        loop = None
+
+    if loop is None or loop.is_closed():
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+    return loop

uagent_testkit/_recording.py

@@ -0,0 +1,130 @@
+"""Context subclasses that capture outbound messages instead of dispatching them."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from uagents import Model
+from uagents.context import ExternalContext, InternalContext
+from uagents_core.types import DeliveryStatus, MsgStatus
+
+if TYPE_CHECKING:
+    from uagents.types import JsonStr
+
+ModelT = TypeVar("ModelT", bound=Model)
+
+
+@dataclass
+class Sent:
+    """One message a handler passed to ctx.send()."""
+
+    destination: str
+    schema_digest: str
+    body: "JsonStr"
+
+    def matches(self, model: type[Model]) -> bool:
+        return self.schema_digest == Model.build_schema_digest(model)
+
+    def parse(self, model: type[ModelT]) -> ModelT:
+        """Decode the payload as `model`.
+
+        Raises if the wire schema digest doesn't match, so a renamed or retyped
+        field is caught here rather than surfacing as a confusing attribute error.
+        """
+        if not self.matches(model):
+            raise AssertionError(
+                f"message sent to {self.destination} is not a {model.__name__} "
+                f"(schema digest {self.schema_digest})"
+            )
+        return model.model_validate_json(self.body)
+
+    def __repr__(self) -> str:
+        return f"Sent(to={self.destination!r}, body={self.body})"
+
+
+class _RecordingMixin:
+    """Overrides send_raw so nothing touches the resolver, dispenser or network."""
+
+    def _init_recording(self) -> None:
+        self.sent: list[Sent] = []
+
+    async def send_raw(  # type: ignore[override]
+        self,
+        destination: str,
+        message_schema_digest: str,
+        message_body: "JsonStr",
+        sync: bool = False,
+        wait_for_response: bool = False,
+        timeout: int = 5,
+        protocol_digest: str | None = None,
+        queries: dict[str, Any] | None = None,
+        expected_response_digests: set[str] | None = None,
+    ) -> MsgStatus:
+        self.sent.append(
+            Sent(
+                destination=destination,
+                schema_digest=message_schema_digest,
+                body=message_body,
+            )
+        )
+        # Mirror the bookkeeping the real context does, so that the framework's own
+        # validate_replies() still sees the reply and behaves exactly as in prod.
+        self._outbound_messages.setdefault(destination, []).append(
+            (message_body, message_schema_digest)
+        )
+        return MsgStatus(
+            status=DeliveryStatus.DELIVERED,
+            detail="captured by uagent-testkit",
+            destination=destination,
+            endpoint="",
+            session=self._session,
+        )
+
+
+class RecordingExternalContext(_RecordingMixin, ExternalContext):
+    """The context handed to on_message handlers under test."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._init_recording()
+
+
+class RecordingInternalContext(_RecordingMixin, InternalContext):
+    """The context handed to on_interval and on_event handlers under test."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._init_recording()
+
+
+@dataclass
+class LogCapture:
+    """Collects records emitted through the agent's logger during one run."""
+
+    records: list[logging.LogRecord] = field(default_factory=list)
+
+    def messages(self, level: int | None = None) -> list[str]:
+        return [
+            r.getMessage()
+            for r in self.records
+            if level is None or r.levelno >= level
+        ]
+
+    @property
+    def warnings(self) -> list[str]:
+        return self.messages(logging.WARNING)
+
+    @property
+    def errors(self) -> list[str]:
+        return self.messages(logging.ERROR)
+
+
+class _ListHandler(logging.Handler):
+    def __init__(self, capture: LogCapture):
+        super().__init__()
+        self._capture = capture
+
+    def emit(self, record: logging.LogRecord) -> None:
+        self._capture.records.append(record)

uagent_testkit/_storage.py

@@ -0,0 +1,58 @@
+"""In-memory storage that stands in for the on-disk KeyValueStore during tests."""
+
+from typing import Any
+
+from uagents.storage import StorageAPI
+
+
+class InMemoryStore(StorageAPI):
+    """A StorageAPI backed by a plain dict.
+
+    The stock KeyValueStore writes a JSON file next to the test run and reloads it
+    on the next one, so agent state leaks between tests and between CI jobs. This
+    keeps the same interface but throws the state away when the harness does.
+    """
+
+    def __init__(self, initial: dict[str, Any] | None = None):
+        self._data: dict[str, Any] = dict(initial or {})
+
+    def get(self, key: str) -> Any | None:
+        return self._data.get(key)
+
+    def has(self, key: str) -> bool:
+        return key in self._data
+
+    def set(self, key: str, value: Any) -> None:
+        self._data[key] = value
+
+    def remove(self, key: str) -> None:
+        self._data.pop(key, None)
+
+    def clear(self) -> None:
+        self._data.clear()
+
+    # Mapping-ish sugar so tests can assert without reaching for .get()
+
+    def __getitem__(self, key: str) -> Any:
+        if key not in self._data:
+            raise KeyError(key)
+        return self._data[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self._data[key] = value
+
+    def __contains__(self, key: object) -> bool:
+        return key in self._data
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def __iter__(self):
+        return iter(self._data)
+
+    def as_dict(self) -> dict[str, Any]:
+        """A copy of the full contents, for snapshot-style assertions."""
+        return dict(self._data)
+
+    def __repr__(self) -> str:
+        return f"InMemoryStore({self._data!r})"

uagent_testkit/harness.py

@@ -0,0 +1,396 @@
+"""Drive a uAgent's handlers directly, with no network and no Almanac registration."""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from typing import Any, TypeVar
+
+from uagents import Agent, Model
+from uagents.agent import AgentRepresentation
+from uagents.types import MsgInfo
+from uagents_core.identity import Identity, generate_user_address, is_user_address
+
+from ._recording import (
+    LogCapture,
+    RecordingExternalContext,
+    RecordingInternalContext,
+    Sent,
+    _ListHandler,
+)
+from ._storage import InMemoryStore
+
+ModelT = TypeVar("ModelT", bound=Model)
+
+#: Stand-in peer used when a test doesn't care who sent the message.
+DEFAULT_SENDER = Identity.from_seed("uagent-testkit default sender", 0).address
+
+
+class _Any:
+    """Sentinel meaning 'any destination'. See Delivery.replies."""
+
+    def __repr__(self) -> str:
+        return "ANY"
+
+
+#: Pass as `to=` to match messages sent to any destination.
+ANY = _Any()
+
+
+class HandlerNotFound(AssertionError):
+    """Raised when the agent has no handler registered for a message type."""
+
+
+class UnverifiedSender(AssertionError):
+    """Raised when a user address targets a handler that requires a verified agent."""
+
+
+class Delivery:
+    """What happened when one message was handed to the agent.
+
+    Wraps the messages the handler sent, anything it logged, and any exception it
+    raised. The framework itself catches handler exceptions and writes them to a
+    log, which makes a broken handler look like a passing test; the harness keeps
+    the exception so it can be re-raised or asserted on.
+    """
+
+    def __init__(
+        self,
+        sent: list[Sent],
+        logs: LogCapture,
+        error: BaseException | None,
+        received: Model,
+        received_digest: str,
+        sender: str,
+        session: uuid.UUID,
+        replies: dict[str, dict[str, type[Model]]] | None,
+    ):
+        self.sent = sent
+        self.logs = logs
+        self.error = error
+        self.received = received
+        self.received_digest = received_digest
+        self.sender = sender
+        self.session = session
+        self._replies = replies or {}
+
+    # -- querying what was sent ------------------------------------------------
+
+    def to(self, destination: str) -> list[Sent]:
+        """Every message sent to one address."""
+        return [s for s in self.sent if s.destination == destination]
+
+    def replies(
+        self, model: type[ModelT], *, to: str | None = None
+    ) -> list[ModelT]:
+        """Messages of type `model` sent back to the original sender.
+
+        Pass `to` for messages sent to a third party instead, or `to=ANY` for
+        every message of that type regardless of destination.
+        """
+        target = self.sender if to is None else to
+        return [
+            s.parse(model)
+            for s in self.sent
+            if s.matches(model) and (target is ANY or s.destination == target)
+        ]
+
+    def reply(self, model: type[ModelT], *, to: str | None = None) -> ModelT:
+        """The single message of type `model`. Raises unless there is exactly one."""
+        found = self.replies(model, to=to)
+        target = self.sender if to is None else to
+        if not found:
+            raise AssertionError(
+                f"expected one {model.__name__} to {target}, got none. "
+                f"Sent: {self.sent or '(nothing)'}"
+            )
+        if len(found) > 1:
+            raise AssertionError(
+                f"expected one {model.__name__} to {target}, got {len(found)}"
+            )
+        return found[0]
+
+    # -- assertions ------------------------------------------------------------
+
+    def assert_replied_with(
+        self, model: type[Model], *, to: str | None = None
+    ) -> "Delivery":
+        self.reply(model, to=to)
+        return self
+
+    def assert_silent(self) -> "Delivery":
+        if self.sent:
+            raise AssertionError(f"expected no messages, got {self.sent}")
+        return self
+
+    def assert_no_errors(self) -> "Delivery":
+        if self.error is not None:
+            raise AssertionError(f"handler raised {self.error!r}") from self.error
+        if self.logs.errors:
+            raise AssertionError(f"handler logged errors: {self.logs.errors}")
+        return self
+
+    def assert_reply_contract(self) -> "Delivery":
+        """Assert the handler honoured the `replies=` set on its @on_message.
+
+        The framework only logs when a handler silently fails to answer, which is
+        easy to miss. Under test it should be a failure.
+        """
+        allowed = self._replies.get(self.received_digest)
+        if not allowed:
+            return self
+        sent_digests = {s.schema_digest for s in self.to(self.sender)}
+        if not sent_digests & set(allowed):
+            expected = sorted(m.__name__ for m in allowed.values())
+            raise AssertionError(
+                f"handler for {type(self.received).__name__} declares replies "
+                f"{expected} but sent none of them to {self.sender}"
+            )
+        return self
+
+    def raise_for_error(self) -> "Delivery":
+        if self.error is not None:
+            raise self.error
+        return self
+
+    def __repr__(self) -> str:
+        return (
+            f"<Delivery {type(self.received).__name__} from {self.sender[:16]}… "
+            f"sent={len(self.sent)} error={self.error!r}>"
+        )
+
+
+class AgentHarness:
+    """A uAgent wired for tests.
+
+    Swaps the agent's on-disk storage for an in-memory one, merges the internal
+    protocol so handlers are resolvable, and routes messages straight to the
+    registered handler with a context that records instead of transmitting.
+    """
+
+    def __init__(self, agent: Agent, *, persist_storage: bool = False):
+        self.agent = agent
+        if not persist_storage:
+            agent._storage = InMemoryStore()
+        self._ensure_protocol_included(agent)
+
+    @staticmethod
+    def _ensure_protocol_included(agent: Agent) -> None:
+        """Merge the agent's internal protocol into its handler tables.
+
+        Normally Agent.setup() does this, but setup() also starts the Almanac
+        registration loop and the network dispenser. include() on its own does
+        the routing half with no I/O.
+        """
+        if getattr(agent, "_testkit_included", False):
+            return
+        agent.include(agent._protocol)
+        agent._testkit_included = True  # type: ignore[attr-defined]
+
+    # -- properties ------------------------------------------------------------
+
+    @property
+    def address(self) -> str:
+        return self.agent.address
+
+    @property
+    def name(self) -> str:
+        return self.agent.name
+
+    @property
+    def storage(self) -> InMemoryStore:
+        return self.agent._storage  # type: ignore[return-value]
+
+    def handles(self, model: type[Model]) -> bool:
+        """Whether a handler is registered for this message type."""
+        return Model.build_schema_digest(model) in self.agent._models
+
+    # -- driving handlers ------------------------------------------------------
+
+    async def deliver(
+        self,
+        message: Model,
+        *,
+        sender: str = DEFAULT_SENDER,
+        session: uuid.UUID | None = None,
+        raise_errors: bool = True,
+    ) -> Delivery:
+        """Hand `message` to the agent as though `sender` had transmitted it."""
+        digest = Model.build_schema_digest(message)
+        model_class = self.agent._models.get(digest)
+        if model_class is None:
+            raise HandlerNotFound(
+                f"{type(message).__name__} has no registered handler on "
+                f"agent {self.agent.name!r}"
+            )
+
+        # Mirror the framework's own resolution order, including its refusal to
+        # hand a user-address message to a handler that requires a verified agent.
+        handler = self.agent._unsigned_message_handlers.get(digest)
+        if handler is None:
+            if is_user_address(sender):
+                if digest in self.agent._signed_message_handlers:
+                    raise UnverifiedSender(
+                        f"{type(message).__name__} is handled by a verified-only "
+                        f"handler, but {sender!r} is a user address. In production "
+                        f"this message is rejected with an ErrorMessage. Use an "
+                        f"agent address, or set allow_unverified=True on the handler."
+                    )
+            else:
+                handler = self.agent._signed_message_handlers.get(digest)
+        if handler is None:
+            raise HandlerNotFound(
+                f"no handler function for {type(message).__name__} on "
+                f"agent {self.agent.name!r}"
+            )
+
+        session = session or uuid.uuid4()
+        body = message.model_dump_json()
+        ctx = self._external_context(digest, body, sender, session)
+
+        with self._capture_logs() as logs:
+            error: BaseException | None = None
+            try:
+                await handler(ctx, sender, model_class.model_validate_json(body))
+            except BaseException as exc:  # noqa: BLE001 - surfaced to the caller
+                error = exc
+
+        delivery = Delivery(
+            sent=ctx.sent,
+            logs=logs,
+            error=error,
+            received=message,
+            received_digest=digest,
+            sender=sender,
+            session=session,
+            replies=self.agent._replies,
+        )
+        if raise_errors and error is not None:
+            raise error
+        return delivery
+
+    async def tick(self, *, only: str | None = None) -> Delivery:
+        """Run the agent's @on_interval handlers once.
+
+        Periods are ignored — the point is to exercise the body deterministically
+        rather than wait out a wall-clock schedule. `only` selects one handler by
+        function name.
+        """
+        handlers = [
+            (fn, period)
+            for fn, period in self.agent._interval_handlers
+            if only is None or fn.__name__ == only
+        ]
+        if only is not None and not handlers:
+            raise HandlerNotFound(f"no interval handler named {only!r}")
+        return await self._run_context_handlers(
+            [fn for fn, _ in handlers], label="interval"
+        )
+
+    async def startup(self) -> Delivery:
+        """Run the agent's @on_event("startup") handlers."""
+        return await self._run_context_handlers(self.agent._on_startup, label="startup")
+
+    async def shutdown(self) -> Delivery:
+        """Run the agent's @on_event("shutdown") handlers."""
+        return await self._run_context_handlers(
+            self.agent._on_shutdown, label="shutdown"
+        )
+
+    # -- internals -------------------------------------------------------------
+
+    async def _run_context_handlers(self, handlers, *, label: str) -> Delivery:
+        ctx = self._internal_context(uuid.uuid4())
+        error: BaseException | None = None
+        with self._capture_logs() as logs:
+            for fn in handlers:
+                try:
+                    await fn(ctx)
+                except BaseException as exc:  # noqa: BLE001
+                    error = exc
+                    break
+        delivery = Delivery(
+            sent=ctx.sent,
+            logs=logs,
+            error=error,
+            received=_Trigger(label=label),
+            received_digest="",
+            sender=self.address,
+            session=ctx.session,
+            replies=None,
+        )
+        if error is not None:
+            raise error
+        return delivery
+
+    def _representation(self) -> AgentRepresentation:
+        agent = self.agent
+        return AgentRepresentation(
+            address=agent.address,
+            name=agent._name,
+            identity=agent._identity,
+            prefix=agent._prefix,
+        )
+
+    def _common_context_kwargs(self, session: uuid.UUID) -> dict[str, Any]:
+        agent = self.agent
+        return {
+            "agent": self._representation(),
+            "storage": agent._storage,
+            "ledger": agent._ledger,
+            "resolver": agent._resolver,
+            "dispenser": agent._dispenser,
+            "logger": agent._logger,
+            "session": session,
+            "message_history": agent._message_history,
+        }
+
+    def _external_context(
+        self, digest: str, body: str, sender: str, session: uuid.UUID
+    ) -> RecordingExternalContext:
+        return RecordingExternalContext(
+            queries={},
+            replies=self.agent._replies,
+            message_received=MsgInfo(message=body, sender=sender, schema_digest=digest),
+            protocol=self.agent.get_message_protocol(digest),
+            **self._common_context_kwargs(session),
+        )
+
+    def _internal_context(self, session: uuid.UUID) -> RecordingInternalContext:
+        return RecordingInternalContext(
+            interval_messages=self.agent._interval_messages,
+            **self._common_context_kwargs(session),
+        )
+
+    def _capture_logs(self):
+        return _LogCaptureScope(self.agent._logger)
+
+
+class _Trigger(Model):
+    """Placeholder 'received message' for interval/startup runs."""
+
+    label: str
+
+
+class _LogCaptureScope:
+    def __init__(self, logger: logging.Logger):
+        self._logger = logger
+        self._capture = LogCapture()
+        self._handler = _ListHandler(self._capture)
+
+    def __enter__(self) -> LogCapture:
+        self._logger.addHandler(self._handler)
+        return self._capture
+
+    def __exit__(self, *exc_info) -> None:
+        self._logger.removeHandler(self._handler)
+
+
+def harness(agent: Agent, *, persist_storage: bool = False) -> AgentHarness:
+    """Wrap an agent for testing. See AgentHarness."""
+    return AgentHarness(agent, persist_storage=persist_storage)
+
+
+def user_sender() -> str:
+    """A user (non-agent) address, for exercising allow_unverified handlers."""
+    return generate_user_address()

uagent_testkit/network.py

@@ -0,0 +1,201 @@
+"""Run several agents against each other in-process, with no sockets involved."""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+from typing import Iterable, TypeVar
+
+from uagents import Agent, Model
+
+from ._recording import Sent
+from .harness import AgentHarness, Delivery, HandlerNotFound
+
+ModelT = TypeVar("ModelT", bound=Model)
+
+
+class ConversationTooLong(AssertionError):
+    """Raised when agents keep replying past the configured round limit."""
+
+
+@dataclass
+class Exchange:
+    """One message that actually reached an agent, and what that agent did."""
+
+    sender: str
+    recipient: str
+    schema_digest: str
+    body: str
+    delivery: Delivery
+
+    def matches(self, model: type[Model]) -> bool:
+        return self.schema_digest == Model.build_schema_digest(model)
+
+    def parse(self, model: type[ModelT]) -> ModelT:
+        return model.model_validate_json(self.body)
+
+
+class Transcript:
+    """Everything that happened after one message was injected into the network."""
+
+    def __init__(self, exchanges: list[Exchange], undelivered: list[Sent]):
+        self.exchanges = exchanges
+        #: Messages addressed to agents the network doesn't know about.
+        self.undelivered = undelivered
+
+    def __len__(self) -> int:
+        return len(self.exchanges)
+
+    def __iter__(self):
+        return iter(self.exchanges)
+
+    def of(self, model: type[ModelT]) -> list[ModelT]:
+        """Every message of this type that reached a handler."""
+        return [e.parse(model) for e in self.exchanges if e.matches(model)]
+
+    def to(self, recipient: str) -> list[Exchange]:
+        return [e for e in self.exchanges if e.recipient == recipient]
+
+    def assert_delivered(
+        self, model: type[Model], *, to: str | None = None
+    ) -> "Transcript":
+        candidates = self.exchanges if to is None else self.to(to)
+        if not any(e.matches(model) for e in candidates):
+            where = f" to {to}" if to else ""
+            raise AssertionError(
+                f"{model.__name__} was never delivered{where}. "
+                f"Transcript: {self.summary()}"
+            )
+        return self
+
+    def assert_all_delivered(self) -> "Transcript":
+        if self.undelivered:
+            raise AssertionError(
+                f"messages went to unknown addresses: {self.undelivered}"
+            )
+        return self
+
+    def summary(self) -> str:
+        if not self.exchanges:
+            return "(no messages)"
+        return " -> ".join(
+            f"{e.sender[:10]}…/{e.recipient[:10]}…" for e in self.exchanges
+        )
+
+    def __repr__(self) -> str:
+        return f"<Transcript {len(self.exchanges)} exchange(s): {self.summary()}>"
+
+
+class AgentNetwork:
+    """A set of agents that can address each other by their real addresses.
+
+    Delivery is synchronous and depth-first-by-round, so a conversation replays
+    the same way every time — no sleeps, no flakes.
+    """
+
+    def __init__(self, *agents: Agent | AgentHarness, persist_storage: bool = False):
+        self._harnesses: dict[str, AgentHarness] = {}
+        for agent in agents:
+            self.add(agent, persist_storage=persist_storage)
+
+    def add(
+        self, agent: Agent | AgentHarness, *, persist_storage: bool = False
+    ) -> AgentHarness:
+        h = (
+            agent
+            if isinstance(agent, AgentHarness)
+            else AgentHarness(agent, persist_storage=persist_storage)
+        )
+        self._harnesses[h.address] = h
+        return h
+
+    def __contains__(self, address: object) -> bool:
+        return address in self._harnesses
+
+    def __iter__(self) -> Iterable[AgentHarness]:
+        return iter(self._harnesses.values())
+
+    def harness(self, agent: Agent | AgentHarness | str) -> AgentHarness:
+        address = self._address_of(agent)
+        if address not in self._harnesses:
+            raise KeyError(f"{address} is not part of this network")
+        return self._harnesses[address]
+
+    @staticmethod
+    def _address_of(agent: Agent | AgentHarness | str) -> str:
+        if isinstance(agent, str):
+            return agent
+        return agent.address
+
+    async def send(
+        self,
+        message: Model,
+        *,
+        to: Agent | AgentHarness | str,
+        sender: Agent | AgentHarness | str | None = None,
+        max_rounds: int = 20,
+    ) -> Transcript:
+        """Inject `message` and let the resulting conversation play out.
+
+        Every reply addressed to another agent in the network is delivered in
+        turn, until nobody has anything left to say.
+        """
+        recipient = self._address_of(to)
+        from_address = (
+            self._address_of(sender) if sender is not None else _EXTERNAL_SENDER
+        )
+
+        queue: deque[tuple[str, str, Model | str, str]] = deque()
+        queue.append((from_address, recipient, message, Model.build_schema_digest(message)))
+
+        exchanges: list[Exchange] = []
+        undelivered: list[Sent] = []
+
+        while queue:
+            if len(exchanges) >= max_rounds:
+                raise ConversationTooLong(
+                    f"conversation exceeded {max_rounds} deliveries; "
+                    f"suspected reply loop. So far: {Transcript(exchanges, []).summary()}"
+                )
+
+            src, dst, payload, digest = queue.popleft()
+            harness = self._harnesses.get(dst)
+            if harness is None:
+                # Shouldn't happen for queued items, but keeps the loop total.
+                continue
+
+            model = payload if isinstance(payload, Model) else None
+            if model is None:
+                model_class = harness.agent._models.get(digest)
+                if model_class is None:
+                    undelivered.append(Sent(dst, digest, payload))  # type: ignore[arg-type]
+                    continue
+                model = model_class.model_validate_json(payload)  # type: ignore[arg-type]
+
+            try:
+                delivery = await harness.deliver(model, sender=src)
+            except HandlerNotFound:
+                undelivered.append(Sent(dst, digest, model.model_dump_json()))
+                continue
+
+            exchanges.append(
+                Exchange(
+                    sender=src,
+                    recipient=dst,
+                    schema_digest=digest,
+                    body=model.model_dump_json(),
+                    delivery=delivery,
+                )
+            )
+
+            for s in delivery.sent:
+                if s.destination in self._harnesses:
+                    queue.append((dst, s.destination, s.body, s.schema_digest))
+                else:
+                    undelivered.append(s)
+
+        return Transcript(exchanges, undelivered)
+
+
+#: Address used when a message is injected from outside the network.
+_EXTERNAL_SENDER = "agent1q0000000000000000000000000000000000000000000000000000000000"

uagent_testkit/plugin.py

@@ -0,0 +1,57 @@
+"""pytest fixtures. Enabled automatically once the package is installed."""
+
+from __future__ import annotations
+
+import pytest
+
+from ._loop import ensure_event_loop
+from .harness import AgentHarness, harness as _harness
+from .network import AgentNetwork
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    """Install an event loop before collection.
+
+    Test modules routinely define `agent = Agent(...)` at module scope, which needs
+    a current event loop at import time.
+    """
+    ensure_event_loop()
+
+
+@pytest.fixture(autouse=True)
+def _uagent_event_loop():
+    """Re-establish a loop for each test.
+
+    pytest-asyncio closes its loop after every test; without this, a synchronous
+    fixture that constructs an Agent fails from the second test onward.
+    """
+    ensure_event_loop()
+    yield
+
+
+@pytest.fixture
+def agent_harness():
+    """Factory fixture wrapping an Agent for testing.
+
+        def test_reply(agent_harness):
+            h = agent_harness(my_agent)
+    """
+
+    def _factory(agent, *, persist_storage: bool = False) -> AgentHarness:
+        return _harness(agent, persist_storage=persist_storage)
+
+    return _factory
+
+
+@pytest.fixture
+def agent_network():
+    """Factory fixture building an AgentNetwork from agents or harnesses.
+
+        def test_conversation(agent_network):
+            net = agent_network(alice, bob)
+    """
+
+    def _factory(*agents, persist_storage: bool = False) -> AgentNetwork:
+        return AgentNetwork(*agents, persist_storage=persist_storage)
+
+    return _factory

uagent_testkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: uagent-testkit
+Version: 0.1.0
+Summary: Test Fetch.ai uAgents without a network, a wallet, or a sleep().
+Project-URL: Homepage, https://github.com/pgalyen1987/fetchai_harness
+Project-URL: Repository, https://github.com/pgalyen1987/fetchai_harness
+Project-URL: Issues, https://github.com/pgalyen1987/fetchai_harness/issues
+Author-email: pgalyen1987 <pgalyen87@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agentverse,asi,fetchai,pytest,testing,uagents
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: uagents>=0.22
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# uagent-testkit
+
+Test [Fetch.ai uAgents](https://github.com/fetchai/uAgents) without a network, a wallet, or a `sleep()`.
+
+```python
+from uagent_testkit import harness
+
+async def test_echo():
+    h = harness(my_agent)
+    result = await h.deliver(Ping(text="hi"))
+
+    assert result.reply(Pong).text == "pong:hi"
+    assert h.storage["seen"] == 1
+```
+
+## Why
+
+The uAgents framework has no testing story. To exercise a handler today you generally
+have to stand the agent up for real — which means Almanac registration, endpoint
+resolution, a funded wallet on some paths, and `asyncio.sleep()` calls sprinkled through
+the test to wait for messages that may never arrive. That is slow, flaky, and awkward to
+run in CI.
+
+Worse, `Agent._handle_message` catches every exception a handler raises and writes it to
+a log. A handler that crashes on every message still looks like a green test. The most
+common agent bug is invisible to the most common agent test.
+
+`uagent-testkit` routes messages straight to the registered handler with a context that
+records instead of transmitting. No sockets, no registration, no waiting.
+
+- **Handler exceptions are raised**, not swallowed into a log.
+- **Storage is in-memory**, so state doesn't leak between tests via the JSON file the
+  stock `KeyValueStore` writes to your working directory.
+- **Reply contracts are enforced** — if `@on_message(replies=Pong)` doesn't send a
+  `Pong`, that's an assertion failure instead of a log line nobody reads.
+- **Interval and lifecycle handlers run on demand**, so an `@on_interval(period=3600)`
+  is testable without waiting an hour.
+- **Multi-agent conversations replay deterministically**, with a loop guard instead of
+  a hung test.
+
+## Install
+
+```bash
+pip install uagent-testkit
+```
+
+Requires Python 3.10+ and `uagents>=0.22`. The pytest fixtures register automatically.
+
+## Testing one agent
+
+```python
+from uagents import Agent, Context, Model
+from uagent_testkit import harness
+
+class Ping(Model):
+    text: str
+
+class Pong(Model):
+    text: str
+
+agent = Agent(name="echo", seed="echo seed")
+
+@agent.on_message(model=Ping, replies=Pong)
+async def on_ping(ctx: Context, sender: str, msg: Ping):
+    ctx.storage.set("seen", (ctx.storage.get("seen") or 0) + 1)
+    await ctx.send(sender, Pong(text=f"pong:{msg.text}"))
+```
+
+```python
+async def test_ping():
+    h = harness(agent)
+    result = await h.deliver(Ping(text="hi"), sender="agent1qexample")
+
+    result.assert_replied_with(Pong)
+    result.assert_reply_contract()          # honoured its replies= declaration
+    assert result.reply(Pong).text == "pong:hi"
+    assert result.sent[0].destination == "agent1qexample"
+    assert h.storage["seen"] == 1
+```
+
+### Asserting on failure
+
+```python
+async def test_bad_input_is_handled():
+    result = await h.deliver(Ping(text=""), raise_errors=False)
+    assert isinstance(result.error, ValueError)
+    assert "empty" in result.logs.errors[0]
+```
+
+By default `deliver()` re-raises whatever the handler raised, so a broken handler fails
+the test loudly. Pass `raise_errors=False` when the failure is the thing under test.
+
+### Sender verification
+
+Handlers without `allow_unverified=True` are only reachable from a verified agent
+address. The harness enforces that, so a test can't pass for a flow production
+rejects:
+
+```python
+from uagent_testkit import UnverifiedSender, user_sender
+
+async def test_strict_handler_refuses_users():
+    with pytest.raises(UnverifiedSender):
+        await h.deliver(Ping(text="hi"), sender=user_sender())
+```
+
+### Intervals and lifecycle
+
+```python
+await h.startup()                  # runs @on_event("startup") handlers
+result = await h.tick()            # runs @on_interval handlers once, ignoring period
+result = await h.tick(only="heartbeat")   # just one, by function name
+await h.shutdown()
+```
+
+## Testing agents against each other
+
+```python
+from uagent_testkit import AgentNetwork
+
+async def test_conversation():
+    net = AgentNetwork(alice, bob)
+    transcript = await net.send(Ping(text="hello"), to=bob, sender=alice)
+
+    transcript.assert_delivered(Pong, to=alice.address)
+    assert transcript.of(Pong)[0].text == "pong:hello"
+    assert net.harness(alice).storage["last_pong"] == "pong:hello"
+```
+
+Every reply addressed to another agent in the network is delivered in turn until the
+conversation goes quiet. Messages sent to addresses outside the network are collected on
+`transcript.undelivered` rather than silently dropped:
+
+```python
+transcript.assert_all_delivered()   # fails if anything went to an unknown address
+```
+
+Agents that answer each other forever raise `ConversationTooLong` after `max_rounds`
+deliveries instead of hanging the suite. This catches echo loops, which are easy to
+write and expensive to discover in production:
+
+```python
+# a keyword responder whose answer contains its own trigger word
+if "menu" in msg.text().lower():
+    await ctx.send(sender, chat("here is the menu"))   # -> contains "menu"
+```
+
+Two agents like that will talk to each other indefinitely. On a live network that is
+two agents spamming each other; here it fails in milliseconds with the transcript
+so far attached.
+
+## Protocols and the chat protocol
+
+Agents assembled from `Protocol` objects work the same way, including the shared chat
+protocol from `uagents_core` that Agentverse and Agent Launch agents use:
+
+```python
+chat = Protocol(spec=chat_protocol_spec)
+
+@chat.on_message(ChatMessage)
+async def on_chat(ctx: Context, sender: str, msg: ChatMessage):
+    ...
+
+agent.include(chat)
+```
+
+```python
+async def test_chat():
+    h = harness(agent)
+    result = await h.deliver(
+        ChatMessage(
+            timestamp=datetime.now(timezone.utc),
+            msg_id=uuid4(),
+            content=[TextContent(type="text", text="show me the menu")],
+        )
+    )
+    assert result.replies(ChatAcknowledgement)
+    assert result.replies(ChatMessage)[0].text() == "here is what we have"
+```
+
+## pytest fixtures
+
+Installing the package registers two factory fixtures:
+
+```python
+def test_with_fixture(agent_harness, agent_network):
+    h = agent_harness(my_agent)
+    net = agent_network(alice, bob)
+```
+
+## API
+
+| | |
+|---|---|
+| `harness(agent)` | Wrap an agent. Swaps in in-memory storage and merges the internal protocol. |
+| `h.deliver(msg, sender=…, raise_errors=True)` | Route a message to its handler. Returns `Delivery`. |
+| `h.tick(only=None)` | Run `@on_interval` handlers once. |
+| `h.startup()` / `h.shutdown()` | Run `@on_event` handlers. |
+| `h.storage` | In-memory store, subscriptable. |
+| `h.handles(Model)` | Whether a handler is registered for a type. |
+| `Delivery.sent` | List of `Sent(destination, schema_digest, body)`. |
+| `Delivery.reply(Model)` | The single reply of that type; raises otherwise. |
+| `Delivery.replies(Model, to=…)` | Replies of that type to the sender; `to=ANY` for any destination. |
+| `user_sender()` | A user (non-agent) address, for `allow_unverified` paths. |
+| `Delivery.error` / `.logs` | Handler exception and captured log records. |
+| `Delivery.assert_replied_with` / `assert_silent` / `assert_no_errors` / `assert_reply_contract` | Chainable assertions. |
+| `AgentNetwork(*agents)` | Multi-agent network. |
+| `net.send(msg, to=…, sender=…, max_rounds=20)` | Play out a conversation. Returns `Transcript`. |
+| `Transcript.of(Model)` / `.to(addr)` / `.undelivered` | Inspect what was exchanged. |
+
+## Scope
+
+This exercises your handler logic: routing, replies, storage, protocol contracts, and
+inter-agent flow. It deliberately does not simulate Almanac resolution, envelope
+signing, or on-chain settlement — those are integration concerns and mocking them would
+give you false confidence. Keep a thin integration test on a real testnet for those, and
+use this for everything else.
+
+## Running the tests
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[test]"
+.venv/bin/python -m pytest
+```
+
+## License
+
+Apache-2.0

uagent_testkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+uagent_testkit/__init__.py,sha256=GJXgexig-4xEQlWrgILYYXI8jJbk7Eb33OjOy1JGELw,939
+uagent_testkit/_loop.py,sha256=kvJbue_i_VLJE96TjHsjXFwjmWmA6rYGWqVP8uLxSXI,985
+uagent_testkit/_recording.py,sha256=lNTUp2heOF4PXenzlQ4xXYwufgvDyYwsidMrnzRCsEg,4027
+uagent_testkit/_storage.py,sha256=CyZa2FECI2wcEsrIzYdvCwRJJESEimg65r8ScZqP_n4,1698
+uagent_testkit/harness.py,sha256=XR49G0tlXM9QlTr74eahTFSAGm33SgCxvLhP7CONtUI,13897
+uagent_testkit/network.py,sha256=CkoW9FG6QbJ3r1gLoZMKHEu6OTVfUSbYcdujRrouZ-Y,6893
+uagent_testkit/plugin.py,sha256=bXYm116O8ksjyY4Y8eplqduT4RbDMLVrHX7wYY4xoA0,1531
+uagent_testkit-0.1.0.dist-info/METADATA,sha256=NLl_kLG1y9uJyyskPmf4XFH8kyBN9zB21AoqjwKRa2w,9084
+uagent_testkit-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+uagent_testkit-0.1.0.dist-info/entry_points.txt,sha256=MQ7SakC1W1ToZa2RXCNsx3Z9UH0vCjGKrNXz6nDTc7A,50
+uagent_testkit-0.1.0.dist-info/licenses/LICENSE,sha256=fs2M4dMLiqJiMvXHyHjMpTvCc1R85S8WePlVFUdG5k8,709
+uagent_testkit-0.1.0.dist-info/RECORD,,

uagent_testkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

uagent_testkit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+uagent_testkit = uagent_testkit.plugin

uagent_testkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,15 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.