[Ecosystem > Testing > Overview]

[verytactical]

https://github.com/ton-org/sandbox?tab=readme-ov-file#writing-tests

• writing jest tests
  • what is sandbox, what are its downsides
  • what is mylocalton
  • why we create instance of Blockchain
  • how we use built-in wallet (treasury, sender) to send messages to contracts
  • how to see the result: exploring transactions object, writing expects
• debugging tests
  • link to [Ecosystem > Wallet apps > TonDevWallet] #139
  • link to [Contract dev > Debugging smart contracts] #86

[olopez6951-tech]

Here is the PR-ready package for TON Docs issue #164.
Commit
docs: add smart contract testing overview
New file
content/docs/smart-contracts/testing/overview.mdx

title: Testing Smart Contracts
description: Learn how to test TON smart contracts using a local blockchain environment.

Testing Smart Contracts

Testing is an essential part of smart contract development. TON smart contracts
are message-driven programs, so tests should verify how contracts process
messages, update persistent data, and interact with other contracts.

This guide introduces the basic workflow for testing TON smart contracts locally.

Testing environment

A local blockchain environment allows developers to test contracts without
deploying to a live network.

With a local environment, developers can:

• Deploy contracts
• Create test wallets
• Send messages
• Inspect transactions
• Verify state changes
• Debug failed executions

Common tools include:

• Jest for running tests
• TON Sandbox for simulating blockchain execution
• Contract wrappers for interacting with contracts from tests

Creating a blockchain instance

Tests usually start by creating a new isolated blockchain instance:

import { Blockchain } from "@ton/sandbox";

const blockchain = await Blockchain.create();
The Blockchain instance represents a local TON network created specifically for the test. It allows contracts and wallets to interact in a controlled environment.
Test wallets
The sandbox provides built-in wallets that can act as message senders.
Example:
const sender = await blockchain.treasury("sender");
These wallets behave like regular TON wallets but exist only inside the test environment.
They can be used to:
Deploy contracts
Send internal messages
Test permissions
Simulate user actions
Deploying a contract
Before testing contract behavior, deploy the contract inside the sandbox.
Example:
const contract = blockchain.openContract(
    await MyContract.fromInit()
);

await contract.sendDeploy(
    sender.getSender()
);
After deployment, the contract can receive messages and execute methods.
Sending messages
TON contracts communicate through messages.
A test should verify that messages produce the expected result.
Example:
await contract.sendAction(
    sender.getSender(),
    1
);

const value = await contract.getValue();

expect(value).toBe(1);
This confirms that the contract processed the message correctly.
Inspecting transactions
Every action produces one or more transactions.
Transactions can be checked to verify:
Sender and receiver
Successful execution
Deployment
Outgoing messages
Exit codes
Example:
expect(result.transactions).toHaveTransaction({
    to: contract.address,
    success: true,
});
Transaction assertions help detect incorrect contract behavior.
Debugging tests
When a test fails, inspect:
Transaction traces
Exit codes
Contract state
Message parameters
Generated actions
Common causes of failures include:
Incorrect message format
Invalid contract state
Missing permissions
Unexpected gas usage
Sandbox limitations
A local sandbox is designed for development and testing. It does not perfectly replicate every condition of the TON network.
Differences may include:
Network timing
External contract interactions
Validator behavior
Important applications should also be tested on a TON test network before production deployment.
Testing best practices
Keep tests isolated
Create a clean blockchain state for every test.
Test failure cases
Verify that invalid messages and unauthorized actions are rejected.
Check transactions
Do not only check final state. Transaction behavior often reveals issues earlier.
Use descriptive test names
Good:
it("increments counter after receiving a valid message");
Avoid:
it("works");
Summary
A good TON smart contract test suite should verify:
Contracts deploy correctly
Messages are processed correctly
State changes are expected
Errors are handled safely
Testing locally helps developers find issues before deploying contracts to a public network.

---

## Navigation update

Add the new page to the existing smart contract documentation navigation:

```json
{
  "pages": [
    "...",
    "testing"
  ]
}
(Keep the existing formatting/order used by the repository.)
Pull Request
Title
docs: add smart contract testing overview
Description
Closes #164

## Summary

Adds an overview page explaining how to test TON smart contracts.

## Changes

- Added smart contract testing documentation
- Explained:
  - local blockchain testing workflow
  - Blockchain instances
  - test wallets
  - deployment testing
  - message handling
  - transaction assertions
  - debugging
  - sandbox limitations

## Motivation

Developers need a clear introduction to testing TON smart contracts before
deploying applications to testnet or mainnet.

The documentation provides a vendor-neutral overview of the testing workflow
and focuses on concepts that apply across TON development tools