> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cowboy.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing toolkit

> What SimulatedChain, mock_host and the local stubs can do

[Test your actor](https://docs.cowboy.inc/developers/testing-actors.md) walks through these.

## 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:

```python theme={"system"}
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")
```

```bash theme={"system"}
cowboy test
```

```text Output theme={"system"}
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](https://docs.cowboy.inc/build/where-your-code-runs.md#off-chain-functions)'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`](https://docs.cowboy.inc/cli-specs/cowboy-run) lists the rest.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.