Invalid type passed!
Received:
{type}
Expected one of:
{asideVariants.join(", ")}
: <>
{title &&
{title}
}
{children}
}
;
};
TON Sandbox ([`@ton/sandbox`](https://github.com/ton-org/sandbox)) is a local blockchain emulator that allows you to test smart contracts from TypeScript, without deploying them to a real network, and without running a blockchain node. It provides a complete testing environment that closely mimics the behavior of the actual TON blockchain. [Blueprint](/contract-dev/blueprint/overview) project template already includes the `@ton/sandbox` dependency.
The companion `@ton/test-utils` helper library provides [matchers](https://jestjs.io/docs/using-matchers) for writing tests with Jest.
This guide covers everything you need to know about writing, running, and debugging tests for your smart contracts. For other programming languages consult documentation of corresponding [SDKs](/ecosystem/sdks).
### Sandbox vs real network
| Feature | Sandbox | Real Network |
| ------------- | ------------------ | ---------------------------------- |
| Speed | Instant execution | \~5-15 second finality |
| Cost | Free | Requires real TON |
| Deterministic | Yes | No (depends on network conditions) |
| Debugging | Full introspection | Limited visibility |
| State Control | Complete control | Immutable history |
### Sandbox limitations
While Sandbox closely emulates the real network, there are some differences to be aware of:
* **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
Blueprint uses Jest as the default testing framework, providing powerful assertion capabilities and excellent TypeScript support.
### Basic test setup
Every Blueprint project includes a test template. Here's the standard structure:
```typescript title="tests/MyContract.spec.ts" expandable theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
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;
let myContract: SandboxContract;
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
Each test should include a fresh `Blockchain` instance to ensure:
**Test isolation**
* No state leakage between tests
* Predictable initial conditions
* Independent contract deployments
**Clean environment**
* Fresh treasury wallets
* Reset logical time and configuration
* Clear transaction history
```typescript theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
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
When you send a message to a contract, you receive a `SendMessageResult` containing:
```typescript theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
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
Blueprint provides powerful matchers for validating transactions:
```typescript theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
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
```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
# 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
When tests fail, check these common issues:
* ✅ 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
## Other resources
* [Debug Guide](/contract-dev/debug) — Advanced debugging techniques
* [TON Dev Wallet](https://github.com/TonDevWallet/TonDevWallet) — Visual debugging tool