uagent-testkit 0.1.0__tar.gz → 0.1.1__tar.gz

{uagent_testkit-0.1.0 → uagent_testkit-0.1.1}/.gitignore

@@ -10,3 +10,5 @@ agent_storage.json
 grant-application.md
 .env
 .env.*
+.mcp.json
+PASTE-SHEET.md

uagent_testkit-0.1.0/README.md → uagent_testkit-0.1.1/PKG-INFO

@@ -1,5 +1,37 @@
+Metadata-Version: 2.4
+Name: uagent-testkit
+Version: 0.1.1
+Summary: Test Fetch.ai uAgents offline — handlers, agent-to-agent flows, and BNB Chain reads.
+Project-URL: Homepage, https://github.com/pgalyen1987/uagent-testkit
+Project-URL: Repository, https://github.com/pgalyen1987/uagent-testkit
+Project-URL: Issues, https://github.com/pgalyen1987/uagent-testkit/issues
+Author-email: Patrick Galyen <pgalyen87@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agent-launch,agentverse,asi,bnb-chain,bsc,fetchai,pytest,testing,uagents,web3
+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: aiohttp>=3.9; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Requires-Dist: requests>=2.31; extra == 'test'
+Description-Content-Type: text/markdown
+
 # uagent-testkit
 
+[![PyPI](https://img.shields.io/pypi/v/uagent-testkit.svg)](https://pypi.org/project/uagent-testkit/)
+[![CI](https://github.com/pgalyen1987/uagent-testkit/actions/workflows/ci.yml/badge.svg)](https://github.com/pgalyen1987/uagent-testkit/actions/workflows/ci.yml)
+
 Test [Fetch.ai uAgents](https://github.com/fetchai/uAgents) without a network, a wallet, or a `sleep()`.
 
 ```python
@@ -21,14 +53,17 @@ resolution, a funded wallet on some paths, and `asyncio.sleep()` calls sprinkled
 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.
+There is also a subtler problem. `Agent._handle_message` catches every exception a
+handler raises and writes it to a log. That is the right call at runtime — an agent
+processes messages from peers it does not control, and one malformed message must not
+take the process down. But the same containment applies under pytest, and there is no
+strict mode to turn it off, so a handler that crashes on every message still looks
+like a green 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.
+- **Handler exceptions are raised** rather than contained 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
@@ -37,6 +72,8 @@ records instead of transmitting. No sockets, no registration, no waiting.
   is testable without waiting an hour.
 - **Multi-agent conversations replay deterministically**, with a loop guard instead of
   a hung test.
+- **Agents that read BNB Chain are testable offline** — `ChainDouble` answers BEP-20
+  and balance queries from state your test sets, and blocks any other outbound HTTP.
 
 ## Install
 
@@ -178,6 +215,49 @@ async def test_chat():
     assert result.replies(ChatMessage)[0].text() == "here is what we have"
 ```
 
+## Agents that read BNB Chain
+
+The harness intercepts `ctx.send`, which covers agent-to-agent messaging. It does not
+cover a handler that reaches out to an RPC endpoint — an agent reading a BEP-20 balance
+still talks to the network during a test. `ChainDouble` closes that gap:
+
+```python
+from uagent_testkit import ChainDouble, FET_BSC, harness
+
+async def test_treasury_agent():
+    chain = ChainDouble()
+    chain.add_token(FET_BSC, symbol="FET", decimals=18,
+                    balances={wallet: 5_500_000_000_000_000_000})
+
+    h = harness(treasury_agent)
+    with chain.install():
+        result = await h.deliver(CheckBalance(wallet=wallet))
+
+    assert result.reply(BalanceReport).amount == 5.5
+    chain.assert_called("eth_call")
+```
+
+It patches whichever of `requests`, `httpx` and `aiohttp` are importable, so it works
+whether the agent uses web3.py or raw async HTTP, and it understands web3.py's
+JSON-encoded `data=` body as well as `json=`.
+
+Supported: `eth_call` (BEP-20 `balanceOf`, `symbol`, `name`, `decimals`, `totalSupply`),
+`eth_getBalance`, `eth_getCode`, `eth_blockNumber`, `eth_chainId`, batched requests.
+
+Two deliberate refusals, both of which turn a silent pass into a loud failure:
+
+```python
+# reading state the test never set up
+with pytest.raises(UnstubbedCall):
+    ...                       # rather than quietly returning zero
+
+# any non-JSON-RPC HTTP from inside a handler
+with pytest.raises(NetworkCallBlocked):
+    ...                       # rather than hitting a real API in CI
+```
+
+There's also a `bsc` fixture that gives you an installed double directly.
+
 ## pytest fixtures
 
 Installing the package registers two factory fixtures:

uagent_testkit-0.1.0/PKG-INFO → uagent_testkit-0.1.1/README.md

@@ -1,32 +1,8 @@
-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
 
+[![PyPI](https://img.shields.io/pypi/v/uagent-testkit.svg)](https://pypi.org/project/uagent-testkit/)
+[![CI](https://github.com/pgalyen1987/uagent-testkit/actions/workflows/ci.yml/badge.svg)](https://github.com/pgalyen1987/uagent-testkit/actions/workflows/ci.yml)
+
 Test [Fetch.ai uAgents](https://github.com/fetchai/uAgents) without a network, a wallet, or a `sleep()`.
 
 ```python
@@ -48,14 +24,17 @@ resolution, a funded wallet on some paths, and `asyncio.sleep()` calls sprinkled
 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.
+There is also a subtler problem. `Agent._handle_message` catches every exception a
+handler raises and writes it to a log. That is the right call at runtime — an agent
+processes messages from peers it does not control, and one malformed message must not
+take the process down. But the same containment applies under pytest, and there is no
+strict mode to turn it off, so a handler that crashes on every message still looks
+like a green 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.
+- **Handler exceptions are raised** rather than contained 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
@@ -64,6 +43,8 @@ records instead of transmitting. No sockets, no registration, no waiting.
   is testable without waiting an hour.
 - **Multi-agent conversations replay deterministically**, with a loop guard instead of
   a hung test.
+- **Agents that read BNB Chain are testable offline** — `ChainDouble` answers BEP-20
+  and balance queries from state your test sets, and blocks any other outbound HTTP.
 
 ## Install
 
@@ -205,6 +186,49 @@ async def test_chat():
     assert result.replies(ChatMessage)[0].text() == "here is what we have"
 ```
 
+## Agents that read BNB Chain
+
+The harness intercepts `ctx.send`, which covers agent-to-agent messaging. It does not
+cover a handler that reaches out to an RPC endpoint — an agent reading a BEP-20 balance
+still talks to the network during a test. `ChainDouble` closes that gap:
+
+```python
+from uagent_testkit import ChainDouble, FET_BSC, harness
+
+async def test_treasury_agent():
+    chain = ChainDouble()
+    chain.add_token(FET_BSC, symbol="FET", decimals=18,
+                    balances={wallet: 5_500_000_000_000_000_000})
+
+    h = harness(treasury_agent)
+    with chain.install():
+        result = await h.deliver(CheckBalance(wallet=wallet))
+
+    assert result.reply(BalanceReport).amount == 5.5
+    chain.assert_called("eth_call")
+```
+
+It patches whichever of `requests`, `httpx` and `aiohttp` are importable, so it works
+whether the agent uses web3.py or raw async HTTP, and it understands web3.py's
+JSON-encoded `data=` body as well as `json=`.
+
+Supported: `eth_call` (BEP-20 `balanceOf`, `symbol`, `name`, `decimals`, `totalSupply`),
+`eth_getBalance`, `eth_getCode`, `eth_blockNumber`, `eth_chainId`, batched requests.
+
+Two deliberate refusals, both of which turn a silent pass into a loud failure:
+
+```python
+# reading state the test never set up
+with pytest.raises(UnstubbedCall):
+    ...                       # rather than quietly returning zero
+
+# any non-JSON-RPC HTTP from inside a handler
+with pytest.raises(NetworkCallBlocked):
+    ...                       # rather than hitting a real API in CI
+```
+
+There's also a `bsc` fixture that gives you an installed double directly.
+
 ## pytest fixtures
 
 Installing the package registers two factory fixtures:

{uagent_testkit-0.1.0 → uagent_testkit-0.1.1}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "uagent-testkit"
-version = "0.1.0"
-description = "Test Fetch.ai uAgents without a network, a wallet, or a sleep()."
+version = "0.1.1"
+description = "Test Fetch.ai uAgents offline — handlers, agent-to-agent flows, and BNB Chain reads."
 readme = "README.md"
 license = "Apache-2.0"
 requires-python = ">=3.10"
-keywords = ["fetchai", "uagents", "agentverse", "testing", "pytest", "asi"]
-authors = [{ name = "pgalyen1987", email = "pgalyen87@gmail.com" }]
+keywords = ["fetchai", "uagents", "agentverse", "asi", "agent-launch", "bnb-chain", "bsc", "web3", "testing", "pytest"]
+authors = [{ name = "Patrick Galyen", email = "pgalyen87@gmail.com" }]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Framework :: Pytest",
@@ -31,12 +31,15 @@ dependencies = [
 test = [
     "pytest>=8.0",
     "pytest-asyncio>=0.24",
+    # exercised by the ChainDouble tests, which drive real HTTP clients
+    "requests>=2.31",
+    "aiohttp>=3.9",
 ]
 
 [project.urls]
-Homepage = "https://github.com/pgalyen1987/fetchai_harness"
-Repository = "https://github.com/pgalyen1987/fetchai_harness"
-Issues = "https://github.com/pgalyen1987/fetchai_harness/issues"
+Homepage = "https://github.com/pgalyen1987/uagent-testkit"
+Repository = "https://github.com/pgalyen1987/uagent-testkit"
+Issues = "https://github.com/pgalyen1987/uagent-testkit/issues"
 
 [project.entry-points.pytest11]
 uagent_testkit = "uagent_testkit.plugin"

uagent_testkit-0.1.1/tests/test_chain.py

@@ -0,0 +1,227 @@
+"""Agents that read BNB Chain, tested offline.
+
+These drive real HTTP clients (requests / aiohttp) so the patching is exercised the
+way an actual agent would exercise it, not through a hand-rolled shim.
+"""
+
+import pytest
+from uagents import Agent, Context, Model
+
+from uagent_testkit import (
+    FET_BSC,
+    ChainDouble,
+    NetworkCallBlocked,
+    UnstubbedCall,
+    harness,
+)
+
+RPC = "https://bsc-dataseed.binance.org/"
+WALLET = "0x8E57BFDE053dBb6862991759c19affC5F383d5D0"
+
+
+def _rpc(method, params):
+    import requests
+
+    return requests.Session().request(
+        "POST", RPC, json={"jsonrpc": "2.0", "id": 1, "method": method, "params": params}
+    ).json()
+
+
+class CheckBalance(Model):
+    wallet: str
+
+
+class BalanceReport(Model):
+    symbol: str
+    amount: float
+
+
+def build_treasury_agent(seed: str) -> Agent:
+    """An agent whose whole job is reading a BEP-20 balance off BNB Chain."""
+    agent = Agent(name="treasury", seed=seed)
+
+    @agent.on_message(model=CheckBalance, replies=BalanceReport)
+    async def on_check(ctx: Context, sender: str, msg: CheckBalance):
+        import requests
+
+        session = requests.Session()
+
+        def call(data):
+            return session.request(
+                "POST",
+                RPC,
+                json={
+                    "jsonrpc": "2.0",
+                    "id": 1,
+                    "method": "eth_call",
+                    "params": [{"to": FET_BSC, "data": data}, "latest"],
+                },
+            ).json()["result"]
+
+        raw = int(call("0x70a08231" + "0" * 24 + msg.wallet[2:].lower()), 16)
+        decimals = int(call("0x313ce567"), 16)
+        symbol_hex = call("0x95d89b41")
+        length = int(symbol_hex[2 + 64 : 2 + 128], 16)
+        symbol = bytes.fromhex(symbol_hex[2 + 128 : 2 + 128 + length * 2]).decode()
+
+        ctx.storage.set("last_wallet", msg.wallet)
+        await ctx.send(
+            sender, BalanceReport(symbol=symbol, amount=raw / 10**decimals)
+        )
+
+    return agent
+
+
+async def test_agent_reads_a_bep20_balance_offline():
+    chain = ChainDouble()
+    chain.add_token(
+        FET_BSC, symbol="FET", decimals=18, balances={WALLET: 5_500_000_000_000_000_000}
+    )
+    h = harness(build_treasury_agent("treasury seed one"))
+
+    with chain.install():
+        result = await h.deliver(CheckBalance(wallet=WALLET))
+
+    report = result.reply(BalanceReport)
+    assert report.symbol == "FET"
+    assert report.amount == 5.5
+    chain.assert_called("eth_call")
+
+
+async def test_native_bnb_balance():
+    chain = ChainDouble().set_balance(WALLET, 2 * 10**18)
+
+    with chain.install():
+        got = _rpc("eth_getBalance", [WALLET, "latest"])
+
+    assert int(got["result"], 16) == 2 * 10**18
+
+
+async def test_chain_metadata():
+    chain = ChainDouble().set_block_number(41_234_567)
+
+    with chain.install():
+        assert int(_rpc("eth_chainId", [])["result"], 16) == 56
+        assert int(_rpc("eth_blockNumber", [])["result"], 16) == 41_234_567
+
+
+async def test_unstubbed_balance_raises_rather_than_returning_zero():
+    """A silent zero would let a test pass on data nobody set up."""
+    chain = ChainDouble()
+
+    with chain.install():
+        with pytest.raises(UnstubbedCall, match="never set"):
+            _rpc("eth_getBalance", [WALLET, "latest"])
+
+
+async def test_unregistered_contract_raises():
+    chain = ChainDouble()
+
+    with chain.install():
+        with pytest.raises(UnstubbedCall, match="never registered"):
+            _rpc("eth_call", [{"to": FET_BSC, "data": "0x313ce567"}, "latest"])
+
+
+async def test_unstubbed_holder_balance_raises():
+    chain = ChainDouble()
+    chain.add_token(FET_BSC, symbol="FET", balances={})
+
+    with chain.install():
+        with pytest.raises(UnstubbedCall, match="balance of"):
+            _rpc(
+                "eth_call",
+                [
+                    {"to": FET_BSC, "data": "0x70a08231" + "0" * 24 + WALLET[2:].lower()},
+                    "latest",
+                ],
+            )
+
+
+async def test_non_rpc_http_is_blocked():
+    """An agent calling some other API mid-handler should fail the test, not the CI run."""
+    import requests
+
+    chain = ChainDouble()
+
+    with chain.install():
+        with pytest.raises(NetworkCallBlocked, match="non-JSON-RPC"):
+            requests.Session().request("GET", "https://example.com/prices")
+
+
+async def test_web3_style_data_body_is_understood():
+    """web3.py posts a JSON-encoded body via data=, not json=."""
+    import json
+
+    import requests
+
+    chain = ChainDouble().set_balance(WALLET, 7)
+
+    with chain.install():
+        resp = requests.Session().request(
+            "POST",
+            RPC,
+            data=json.dumps(
+                {"jsonrpc": "2.0", "id": 1, "method": "eth_getBalance",
+                 "params": [WALLET, "latest"]}
+            ),
+        )
+
+    assert int(resp.json()["result"], 16) == 7
+
+
+async def test_batch_requests():
+    chain = ChainDouble().set_balance(WALLET, 3)
+
+    with chain.install():
+        import requests
+
+        resp = requests.Session().request(
+            "POST",
+            RPC,
+            json=[
+                {"jsonrpc": "2.0", "id": 1, "method": "eth_chainId", "params": []},
+                {"jsonrpc": "2.0", "id": 2, "method": "eth_getBalance",
+                 "params": [WALLET, "latest"]},
+            ],
+        )
+
+    body = resp.json()
+    assert len(body) == 2
+    assert int(body[1]["result"], 16) == 3
+
+
+async def test_aiohttp_client_is_patched():
+    import aiohttp
+
+    chain = ChainDouble().set_balance(WALLET, 11)
+
+    with chain.install():
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                RPC,
+                json={"jsonrpc": "2.0", "id": 1, "method": "eth_getBalance",
+                      "params": [WALLET, "latest"]},
+            ) as resp:
+                body = await resp.json()
+
+    assert int(body["result"], 16) == 11
+
+
+async def test_patches_are_removed_on_exit():
+    """Leaving the context must restore the real client, or later tests get poisoned."""
+    import requests
+
+    original = requests.Session.request
+    with ChainDouble().install():
+        assert requests.Session.request is not original
+    assert requests.Session.request is original
+
+
+async def test_assert_no_calls():
+    chain = ChainDouble()
+    with chain.install():
+        pass
+    chain.assert_no_calls()
+
+    with pytest.raises(AssertionError, match="expected a eth_call call"):
+        chain.assert_called("eth_call")

{uagent_testkit-0.1.0 → uagent_testkit-0.1.1}/uagent_testkit/__init__.py

@@ -10,6 +10,12 @@
 from ._loop import ensure_event_loop
 from ._recording import Sent
 from ._storage import InMemoryStore
+from .chain import (
+    FET_BSC,
+    ChainDouble,
+    NetworkCallBlocked,
+    UnstubbedCall,
+)
 from .harness import (
     ANY,
     DEFAULT_SENDER,
@@ -31,18 +37,22 @@ __all__ = [
     "ANY",
     "AgentHarness",
     "AgentNetwork",
+    "ChainDouble",
     "ConversationTooLong",
     "DEFAULT_SENDER",
     "Delivery",
     "Exchange",
+    "FET_BSC",
     "HandlerNotFound",
     "InMemoryStore",
+    "NetworkCallBlocked",
     "Sent",
     "Transcript",
+    "UnstubbedCall",
     "UnverifiedSender",
     "ensure_event_loop",
     "harness",
     "user_sender",
 ]
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"

uagent_testkit-0.1.1/uagent_testkit/chain.py

@@ -0,0 +1,383 @@
+"""An offline stand-in for BNB Chain, for agents that read on-chain state.
+
+The rest of this package intercepts `ctx.send`, which covers agent-to-agent messaging.
+It does not cover a handler that reaches out to an RPC endpoint — an agent that reads a
+BEP-20 balance, a token's symbol, or a wallet's BNB balance still talks to the network
+during a test. That makes those tests slow, rate-limited, dependent on mainnet state
+that changes underneath them, and impossible to run in CI offline.
+
+`ChainDouble` blocks outbound HTTP from handlers and answers JSON-RPC from state the
+test sets up, so an agent that reads BNB Chain becomes as testable as one that doesn't:
+
+    chain = ChainDouble()
+    chain.add_token(FET, symbol="FET", decimals=18, balances={wallet: 5 * 10**18})
+
+    with chain.install():
+        result = await h.deliver(CheckBalance(wallet=wallet))
+
+    assert result.reply(BalanceReport).amount == 5.0
+    chain.assert_called("eth_call")
+
+Anything the double has not been told about raises rather than silently returning zero,
+so a test cannot pass on data that was never stubbed.
+"""
+
+from __future__ import annotations
+
+from contextlib import ExitStack, contextmanager
+from typing import Any, Iterator
+
+#: BEP-20 / ERC-20 selectors. Stable across every token that implements the standard.
+SELECTOR_BALANCE_OF = "70a08231"
+SELECTOR_SYMBOL = "95d89b41"
+SELECTOR_DECIMALS = "313ce567"
+SELECTOR_TOTAL_SUPPLY = "18160ddd"
+SELECTOR_NAME = "06fdde03"
+
+#: FET on BNB Chain — the asset Agent Launch grants are paid in.
+FET_BSC = "0x031b41e504677879370e9dbcf937283a8691fa7f"
+
+BSC_CHAIN_ID = 56
+
+
+class NetworkCallBlocked(AssertionError):
+    """Raised when a handler tries to reach the network during a test."""
+
+
+class UnstubbedCall(AssertionError):
+    """Raised when a handler asks the chain for something the test never set up."""
+
+
+def _norm(address: str) -> str:
+    return address.lower()
+
+
+def _enc_uint(value: int) -> str:
+    return f"{value:064x}"
+
+
+def _enc_string(value: str) -> str:
+    raw = value.encode()
+    padded = raw + b"\x00" * ((32 - len(raw) % 32) % 32)
+    return _enc_uint(32) + _enc_uint(len(raw)) + padded.hex()
+
+
+class _Token:
+    def __init__(
+        self,
+        symbol: str,
+        decimals: int,
+        total_supply: int,
+        balances: dict[str, int],
+        name: str | None,
+    ):
+        self.symbol = symbol
+        self.decimals = decimals
+        self.total_supply = total_supply
+        self.balances = {_norm(k): v for k, v in balances.items()}
+        self.name = name if name is not None else symbol
+
+
+class ChainDouble:
+    """A stubbable JSON-RPC endpoint standing in for BNB Chain."""
+
+    def __init__(self, *, chain_id: int = BSC_CHAIN_ID, block_number: int = 40_000_000):
+        self.chain_id = chain_id
+        self.block_number = block_number
+        self._balances: dict[str, int] = {}
+        self._tokens: dict[str, _Token] = {}
+        self._code: dict[str, str] = {}
+        #: Every JSON-RPC method the agent asked for, in order.
+        self.calls: list[tuple[str, Any]] = []
+
+    # -- setting up state ------------------------------------------------------
+
+    def set_balance(self, address: str, wei: int) -> "ChainDouble":
+        """Set a wallet's native BNB balance, in wei."""
+        self._balances[_norm(address)] = wei
+        return self
+
+    def add_token(
+        self,
+        address: str,
+        *,
+        symbol: str,
+        decimals: int = 18,
+        total_supply: int = 0,
+        balances: dict[str, int] | None = None,
+        name: str | None = None,
+    ) -> "ChainDouble":
+        """Register a BEP-20 token and the balances it should report."""
+        self._tokens[_norm(address)] = _Token(
+            symbol, decimals, total_supply, balances or {}, name
+        )
+        self._code.setdefault(_norm(address), "0x60806040")
+        return self
+
+    def set_block_number(self, n: int) -> "ChainDouble":
+        self.block_number = n
+        return self
+
+    # -- assertions ------------------------------------------------------------
+
+    def assert_called(self, method: str) -> "ChainDouble":
+        if not any(m == method for m, _ in self.calls):
+            raise AssertionError(
+                f"expected a {method} call; got {[m for m, _ in self.calls] or 'none'}"
+            )
+        return self
+
+    def assert_no_calls(self) -> "ChainDouble":
+        if self.calls:
+            raise AssertionError(f"expected no chain access, got {self.calls}")
+        return self
+
+    # -- JSON-RPC --------------------------------------------------------------
+
+    def rpc(self, payload: Any) -> Any:
+        """Answer a single JSON-RPC request or a batch of them."""
+        if isinstance(payload, list):
+            return [self._one(p) for p in payload]
+        return self._one(payload)
+
+    def _one(self, payload: dict) -> dict:
+        method = payload.get("method")
+        params = payload.get("params") or []
+        self.calls.append((method, params))
+        return {
+            "jsonrpc": "2.0",
+            "id": payload.get("id", 1),
+            "result": self._dispatch(method, params),
+        }
+
+    def _dispatch(self, method: str, params: list) -> Any:
+        if method == "eth_chainId":
+            return hex(self.chain_id)
+        if method == "eth_blockNumber":
+            return hex(self.block_number)
+        if method == "net_version":
+            return str(self.chain_id)
+        if method == "eth_getBalance":
+            address = _norm(params[0])
+            if address not in self._balances:
+                raise UnstubbedCall(
+                    f"handler read the BNB balance of {params[0]}, which the test never "
+                    f"set. Call chain.set_balance({params[0]!r}, wei) first."
+                )
+            return hex(self._balances[address])
+        if method == "eth_getCode":
+            return self._code.get(_norm(params[0]), "0x")
+        if method == "eth_getTransactionCount":
+            return "0x0"
+        if method == "eth_call":
+            return self._eth_call(params[0])
+        raise UnstubbedCall(
+            f"handler called {method}, which ChainDouble does not implement. "
+            f"Supported: eth_call, eth_getBalance, eth_getCode, eth_blockNumber, "
+            f"eth_chainId, eth_getTransactionCount, net_version."
+        )
+
+    def _eth_call(self, call: dict) -> str:
+        to = _norm(call.get("to", ""))
+        data = (call.get("data") or call.get("input") or "").removeprefix("0x")
+        selector, args = data[:8], data[8:]
+
+        token = self._tokens.get(to)
+        if token is None:
+            raise UnstubbedCall(
+                f"handler called contract {call.get('to')}, which the test never "
+                f"registered. Call chain.add_token({call.get('to')!r}, symbol=...) first."
+            )
+
+        if selector == SELECTOR_BALANCE_OF:
+            holder = "0x" + args[24:64]
+            if holder not in token.balances:
+                raise UnstubbedCall(
+                    f"handler read the {token.symbol} balance of {holder}, which the "
+                    f"test never set. Add it to the balances= of add_token()."
+                )
+            return "0x" + _enc_uint(token.balances[holder])
+        if selector == SELECTOR_DECIMALS:
+            return "0x" + _enc_uint(token.decimals)
+        if selector == SELECTOR_TOTAL_SUPPLY:
+            return "0x" + _enc_uint(token.total_supply)
+        if selector == SELECTOR_SYMBOL:
+            return "0x" + _enc_string(token.symbol)
+        if selector == SELECTOR_NAME:
+            return "0x" + _enc_string(token.name)
+        raise UnstubbedCall(
+            f"handler called selector 0x{selector} on {call.get('to')}; ChainDouble "
+            f"implements balanceOf, symbol, name, decimals and totalSupply."
+        )
+
+    # -- installing over the HTTP clients --------------------------------------
+
+    @contextmanager
+    def install(self) -> Iterator["ChainDouble"]:
+        """Route HTTP from handlers here, and block anything that isn't JSON-RPC.
+
+        Patches whichever of requests / httpx / aiohttp are importable, so this works
+        whether the agent uses web3.py (requests) or raw async HTTP.
+        """
+        with ExitStack() as stack:
+            for patch in (self._patch_requests, self._patch_httpx, self._patch_aiohttp):
+                ctx = patch()
+                if ctx is not None:
+                    stack.enter_context(ctx)
+            yield self
+
+    def _payload_or_block(self, url: str, json_body: Any, data: Any = None) -> Any:
+        """Resolve a request body to a JSON-RPC payload, or refuse it.
+
+        web3.py's HTTPProvider posts a JSON-encoded body via `data=` rather than
+        `json=`, so both have to be understood.
+        """
+        payload = json_body
+        if payload is None and data is not None:
+            import json as _json
+
+            if isinstance(data, (bytes, bytearray)):
+                data = data.decode()
+            if isinstance(data, str):
+                try:
+                    payload = _json.loads(data)
+                except ValueError:
+                    payload = None
+        if payload is None:
+            raise NetworkCallBlocked(
+                f"handler made a non-JSON-RPC HTTP request to {url} during a test. "
+                f"Stub it, or assert the handler does not call out."
+            )
+        return self.rpc(payload)
+
+    def _patch_requests(self):
+        try:
+            import requests
+        except ImportError:
+            return None
+
+        double = self
+
+        class _Response:
+            def __init__(self, payload):
+                self._payload = payload
+                self.status_code = 200
+                self.reason = "OK"
+                self.headers = {"Content-Type": "application/json"}
+
+            def json(self):
+                return self._payload
+
+            @property
+            def content(self):
+                import json
+
+                return json.dumps(self._payload).encode()
+
+            @property
+            def text(self):
+                return self.content.decode()
+
+            def raise_for_status(self):
+                return None
+
+        @contextmanager
+        def _ctx():
+            original = requests.Session.request
+
+            def patched(self, method, url, *args, json=None, data=None, **kwargs):
+                return _Response(double._payload_or_block(url, json, data))
+
+            requests.Session.request = patched
+            try:
+                yield
+            finally:
+                requests.Session.request = original
+
+        return _ctx()
+
+    def _patch_httpx(self):
+        try:
+            import httpx
+        except ImportError:
+            return None
+
+        double = self
+
+        @contextmanager
+        def _ctx():
+            original = httpx.Client.request
+            original_async = httpx.AsyncClient.request
+
+            def _resp(url, json_body, data):
+                return httpx.Response(
+                    200, json=double._payload_or_block(str(url), json_body, data)
+                )
+
+            def patched(self, method, url, *args, json=None, content=None, **kwargs):
+                return _resp(url, json, content)
+
+            async def patched_async(
+                self, method, url, *args, json=None, content=None, **kwargs
+            ):
+                return _resp(url, json, content)
+
+            httpx.Client.request = patched
+            httpx.AsyncClient.request = patched_async
+            try:
+                yield
+            finally:
+                httpx.Client.request = original
+                httpx.AsyncClient.request = original_async
+
+        return _ctx()
+
+    def _patch_aiohttp(self):
+        try:
+            import aiohttp
+        except ImportError:
+            return None
+
+        double = self
+
+        class _Response:
+            def __init__(self, payload):
+                self._payload = payload
+                self.status = 200
+
+            async def json(self, **_kwargs):
+                return self._payload
+
+            async def text(self):
+                import json
+
+                return json.dumps(self._payload)
+
+            def raise_for_status(self):
+                return None
+
+            async def __aenter__(self):
+                return self
+
+            async def __aexit__(self, *exc):
+                return False
+
+            async def release(self):
+                return None
+
+        @contextmanager
+        def _ctx():
+            original = aiohttp.ClientSession._request
+
+            # _request is a coroutine function, and session.post() wraps its result
+            # in _RequestContextManager, which awaits it. It must stay awaitable.
+            async def patched(self, method, url, *args, json=None, data=None, **kwargs):
+                return _Response(double._payload_or_block(str(url), json, data))
+
+            aiohttp.ClientSession._request = patched
+            try:
+                yield
+            finally:
+                aiohttp.ClientSession._request = original
+
+        return _ctx()

{uagent_testkit-0.1.0 → uagent_testkit-0.1.1}/uagent_testkit/plugin.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import pytest
 
 from ._loop import ensure_event_loop
+from .chain import ChainDouble
 from .harness import AgentHarness, harness as _harness
 from .network import AgentNetwork
 
@@ -43,6 +44,19 @@ def agent_harness():
     return _factory
 
 
+@pytest.fixture
+def bsc():
+    """An installed ChainDouble standing in for BNB Chain.
+
+        def test_reads_balance(bsc):
+            bsc.add_token(FET_BSC, symbol="FET", balances={wallet: 10**18})
+            ...
+    """
+    double = ChainDouble()
+    with double.install():
+        yield double
+
+
 @pytest.fixture
 def agent_network():
     """Factory fixture building an AgentNetwork from agents or harnesses.