Testing toolkit

SimulatedChain

SimulatedChain(actor) from cowboy_sdk.testing runs one actor’s handlers in memory, from empty state.

Method	What it does
`call(handler, payload=b"")`	Calls a handler and returns what it returns. Encode the payload with `codec.encode` and decode the result with `codec.decode`.
`set_sender(address)`	Sets who sends the next calls, as 20 bytes.
`state(key)`, `assert_state(key, expected)`	Reads one key of the actor’s state as encoded bytes, or asserts its value.
`snapshot()`	All of the actor’s state, to compare before and after a call.
`events()`	Every `(name, payload)` event the actor sent, oldest first. The payload is encoded.
`advance_block(n=1)`	Moves time forward `n` blocks and runs every schedule that comes due. A block is the network’s unit of about one second.
`jobs()`	Every runner job the actor sent, oldest first. `payload["args"]` and `payload["kwargs"]` are what the handler passed.
`reply(result)`	Answers the last runner job with `result` and returns what the resumed handler returns. For a plain `runner.llm`, reply with a dict such as `{"text": "4"}`.
`fail(reason="retries_exhausted")`	Answers the last runner job with a failure, so the `await` raises `JobFailed`.
`set_budget_left(amount)`	Sets what `runtime.budget_left()` returns.
`check_determinism(scenario)`	Runs the scenario twice and compares the resulting state.

mock_host

cowboy_sdk.mock_host is the in-memory stand-in for Cowboy that SimulatedChain runs on.

Helper	What it does
`seed_actor_owner(owner)`	Makes `owner` the actor’s owner, as a deploy does.
`context()`	The current call’s context as a dict: `sender`, `actor_addr`, `timestamp_ms` and more.
`set_context(**fields)`	Changes fields of the context, such as `timestamp_ms`.
`set_call_handler(fn)`	Answers the actor’s calls to other actors.

Calls to other actors

When a handler calls another actor with call(...), answer it with a CallMock. This test needs no second actor:

from cowboy_sdk import Actor, call, codec, mock_host, public
from cowboy_sdk.testing import CallMock, SimulatedChain

PRICES = b"\x44" * 20


class Shop(Actor):
    @public
    def quote(self, item: object) -> object:
        return call(PRICES, "price", item)


def test_quote_asks_the_price_actor() -> None:
    shop = Shop()
    chain = SimulatedChain(shop)
    prices = CallMock(default=codec.encode(None))
    prices.when(method="price", args=codec.encode("coffee")).respond(codec.encode(3))
    mock_host.set_call_handler(prices)
    assert codec.decode(chain.call(shop.quote, codec.encode("coffee"))) == 3
    target, method, _args, _cycles, _access = prices.calls[-1]
    assert (target, method) == (PRICES, "price")

cowboy test

Output

tests/test_calls.py .                                                    [ 14%]
tests/test_helpdesk.py ......                                            [100%]
============================== 7 passed in 0.08s ===============================

when(...) chooses which calls to match, and respond(...) gives the encoded answer. calls records every call.

Stubs

Every runner call a handler makes needs an answer. Without one, the run ends with the handler still waiting for its job.

Flag	What it answers
`--stub-llm <JSON>`	The next `runner.llm` call, with this value. Repeatable.
`--stub-llm-failure <CODE>`	The next structured `runner.llm` call, with a failure such as `provider_refusal`.
`--stub-job-failure <REASON>`	The next runner job of any kind, with a failure, so `except JobFailed` runs.
`--stub <FUNCTION=JSON>`	An off-chain function’s result, such as `--stub 'count_primes=25'`. Repeatable.
`--stub-error <FUNCTION=TYPE:MESSAGE>`	Makes the function raise.
`--stub-exit <FUNCTION=CODE>`	Makes its container exit with this code.

State and callers

Flag	What it does
`--reset`	Starts from empty state, and saves the result as the new state.
`--sender <ADDRESS>`	Who the handler sees as the caller.
`--timestamp <MS>`	The time, in milliseconds, the handler sees.

cowboy run lists the rest.

Welcome

Hire Actors

Build Actors

Sell in the Store

Protocol and architecture

Reference

Testing toolkit

SimulatedChain

mock_host

Calls to other actors

Stubs

State and callers

​SimulatedChain

​mock_host

​Calls to other actors

​Stubs

​State and callers

SimulatedChain

mock_host

Calls to other actors

Stubs

State and callers