Testing overview

​

Quick navigation

• What is TON Sandbox — understanding the testing environment
• Writing tests — creating test suites for your contracts
• Running tests — executing and configuring tests
• Common pitfalls — troubleshooting and best practices

​

What is TON Sandbox

​

Key features

• Emulates all transaction phases
• Accurate fee calculation and gas consumption
• Full message routing and processing
• Account state management

• Pre-funded treasury wallets for testing
• Transaction matchers for Jest/Chai/
• Coverage analysis and reporting
• Step-by-step execution debugging

​

Sandbox vs real network

​

Sandbox limitations

• Time-dependent contracts: Sandbox time is controlled, not real-time
• External dependencies: Cannot interact with real external contracts, but can get their state and emulate them
• Blockchain imitation: Because there is no concept of blocks in Sandbox, things like sharding do not work.

​

Writing tests

​

Basic test setup

import { Blockchain, SandboxContract, TreasuryContract } from '@ton/sandbox';
import { Cell, toNano } from '@ton/core';
import { MyContract } from '../wrappers/MyContract';
import '@ton/test-utils';
import { compile } from '@ton/blueprint';

describe('MyContract', () => {
    let code: Cell;

    beforeAll(async () => {
        code = await compile('MyContract');
    });

    let blockchain: Blockchain;
    let deployer: SandboxContract<TreasuryContract>;
    let myContract: SandboxContract<MyContract>;

    beforeEach(async () => {
        blockchain = await Blockchain.create();
        
        myContract = blockchain.openContract(
            MyContract.createFromConfig({}, code)
        );
        
        deployer = await blockchain.treasury('deployer');
        
        const deployResult = await myContract.sendDeploy(
            deployer.getSender(), 
            toNano('0.05')
        );

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

    it('should deploy', async () => {
        // Contract is already deployed in beforeEach
        // Add additional deployment checks here
    });
});

​

Test isolation

• No state leakage between tests
• Predictable initial conditions
• Independent contract deployments

• Fresh treasury wallets
• Reset logical time and configuration
• Clear transaction history

beforeEach(async () => {
    // Fresh blockchain for each test
    blockchain = await Blockchain.create();
    
    // Each test gets clean treasuries
    deployer = await blockchain.treasury('deployer');
    user = await blockchain.treasury('user');
});

​

Understanding transaction results

const result = await contract.sendIncrement(user.getSender(), toNano('0.1'));

// result.transactions - Array of all transactions in the chain
// result.events - Blockchain events emitted
// result.externals - External messages generated

​

Transaction matchers

expect(result.transactions).toHaveTransaction({
    from: user.address,
    to: contract.address,
    value: toNano('1'),
    op: 0x12345678, // Operation code
    success: true,
    outMessagesCount: 2, // Number of outbound messages
    deploy: false,
    body: beginCell()
        .storeUint(0, 32) // Comment op
        .storeStringTail("Hello, user!")
        .endCell()
});

​

Running tests

# Run all tests
npx blueprint test

# Run specific test file
npx blueprint test MyContract

# Run with coverage
npx blueprint test --coverage

# Run with gas reporting  
npx blueprint test --gas-report

​

Common pitfalls

​

Debugging checklist

• ✅ Contract is properly deployed before testing
• ✅ Treasury has sufficient balance for operations
• ✅ Transaction matchers use correct field names
• ✅ Exit codes match expected error conditions
• ✅ Message bodies are correctly formatted
• ✅ Time-sensitive operations account for blockchain time

​

Next steps

• Testing Reference — Complete API documentation
• Testing Guidelines — Best practices and patterns
• Testing Coverage — Testing coverage

• Blueprint Benchmarks — Performance testing and optimization

• Debug Guide — Advanced debugging techniques
• TON Dev Wallet — Visual debugging tools