ton-devtools-rpc-mock

Deterministic Toncenter API v2 emulator for ICP integration testing.

Part of the ton-devtools monorepo.

What it does

Replaces the live Toncenter API v2 node in tests with an in-process server that:

• Returns deterministic responses for pre-configured wallet addresses
• Supports getWalletInformation and runGetMethod (get_public_key)
• Provides runtime state mutation and fault injection via /_mock/* endpoints
• Eliminates flaky tests caused by mainnet/testnet availability

Installation

pip install ton-devtools-rpc-mock

Quick Start

As a pytest ASGI fixture (recommended)

import os
import pytest_asyncio
import httpx
from asgi_lifespan import LifespanManager
from ton_devtools_rpc_mock import app, DEPLOYED_WALLET

@pytest_asyncio.fixture
async def trms():
    os.environ["MOCK_CONTROL"] = "1"
    async with LifespanManager(app):
        async with httpx.AsyncClient(
            transport=httpx.ASGITransport(app=app),
            base_url="http://test",
        ) as client:
            await client.post("/_mock/reset")
            yield client

async def test_deployed_wallet(trms):
    resp = await trms.post("/jsonRPC", json={
        "method": "runGetMethod",
        "params": {"address": DEPLOYED_WALLET, "method": "get_public_key", "stack": []},
    })
    assert resp.json()["result"]["exit_code"] == 0

As a standalone server

# Start with control endpoints enabled
ton-devtools-rpc-mock --port 8080 --control

# Point your ICP core service at it
export TON_API_BASE_URL=http://localhost:8080

As a Docker container

docker run -p 8080:8080 -e MOCK_CONTROL=1 ghcr.io/ismaildalgatov/ton-devtools-rpc-mock:latest

Pre-configured fixtures

Control endpoints

Enabled when MOCK_CONTROL=1:

Fault injection

# Inject HTTP 503 on a specific address
await client.post("/_mock/inject_fault", json={
    "address": DEPLOYED_WALLET,
    "fault": {"type": "http_error", "status_code": 503},
})

# Global outage
await client.post("/_mock/inject_fault", json={
    "address": None,
    "fault": {"type": "http_error", "status_code": 502},
})

# Corrupt JSON response
await client.post("/_mock/inject_fault", json={
    "address": DEPLOYED_WALLET,
    "fault": {"type": "corrupt_json"},
})

License

MIT