gramdocs.tech
Документация

TON Sandbox: локальное тестирование без сети

Поднимешь локальный Blockchain из @ton/sandbox, задеплоишь контракт в тесте и проверишь транзакции без testnet.

Что такое Sandbox

@ton/sandbox — эмулятор TON внутри Node.js: локальный Blockchain, кошельки-казначейства (treasury) и исполнение TVM без RPC. Тесты быстрые, бесплатные и детерминированные.

На момент публикации: @ton/sandbox@0.44.0 (в шаблоне Blueprint ставится вместе с проектом).

Минимальный тест

В Blueprint-проекте с Tact-контрактом (SimpleCounter из tact-counter):

typescript
// @ton/sandbox 0.44.0, @ton/core 0.63.x, @ton/test-utils
import { Blockchain, SandboxContract, TreasuryContract } from "@ton/sandbox";
import { toNano } from "@ton/core";
import { SimpleCounter } from "../build/SimpleCounter/tact_SimpleCounter";
import "@ton/test-utils";

describe("SimpleCounter", () => {
  let blockchain: Blockchain;
  let deployer: SandboxContract<TreasuryContract>;
  let counter: SandboxContract<SimpleCounter>;

  beforeEach(async () => {
    blockchain = await Blockchain.create();
    deployer = await blockchain.treasury("deployer");

    counter = blockchain.openContract(await SimpleCounter.fromInit(0n, 0n));

    const deployResult = await counter.send(
      deployer.getSender(),
      { value: toNano("0.05") },
      null, // пустой receive() — деплой
    );

    expect(deployResult.transactions).toHaveTransaction({
      from: deployer.address,
      to: counter.address,
      deploy: true,
      success: true,
    });
  });

  it("increments counter", async () => {
    await counter.send(
      deployer.getSender(),
      { value: toNano("0.05") },
      { $$type: "Add", queryId: 0n, amount: 3n },
    );

    expect(await counter.getCounter()).toBe(3n);
  });
});

Запуск:

bash
npm test

Все сценарии проходят локально — RPC-ключ и faucet не нужны.

Как это работает

  • Blockchain.create() — изолированная «сеть» в процессе Node.
  • blockchain.treasury(name) — тестовый кошелёк с балансом; одно и то же имя → один и тот же адрес между прогонами.
  • openContract — связывает TS-wrapper с эмулятором.
  • toHaveTransaction из @ton/test-utils — матчер по полям транзакции (success, deploy, адреса).

Частые ошибки

Забываешь await на getCounter() / send → флакующие или ложные падения. Все вызовы к sandbox асинхронные.

Деплоишь без value → не хватает газа, success: false. Для деплоя обычно toNano("0.05") и больше.

Ждёшь, что sandbox = testnet → состояние эмулятора не видно в Tonviewer. Для проверки в сети — testnet и faucet.

Что дальше

Материалы gramdocs.tech носят образовательный характер и не являются финансовой, юридической или инвестиционной рекомендацией. Работа с блокчейном TON и токеном Gram связана с рисками потери средств. Правовая информация