testing

Module for public API to be used in tests (which do NOT interact with real blockchain).

You cover contracts with tests to simulate their behavior in a real blockchain. Use methods testing.xxx in combination with net.xxx in some-file.test.tolk.

Writing tests differs from writing scripts that operate testnet/mainnet. In tests, you don't connect your wallet, you use testing.treasury (unlimited source of money). In tests, you may set blockchain config, set any account at any address, etc. In tests, you don't wait for network responses: all transactions are emulated.

Definitions

testing

struct testing

Root module for public API to be used in tests along with net.xxx methods.

testing.getC7OutsideContract

fun testing.getC7OutsideContract(): tuple

Read the TVM control register C7.

testing.setC7OutsideContract

fun testing.setC7OutsideContract(c7: tuple): void

Write a new value to the TVM control register C7.

TxCursor

struct TxCursor {
    id: int
}

Opaque cursor for step-by-step transaction execution.

Use testing.createTraceIterationCursor to create it, then drain it in parts with TxCursor.executeN, TxCursor.executeTill, or TxCursor.executeAllRemaining.

TxCursor.isDone

fun TxCursor.isDone(self): bool

Returns true when the cursor has no pending transactions to execute.

TxCursor.close

fun TxCursor.close(self): void

Discards any remaining pending transactions for this cursor.

TxCursor.executeN

fun TxCursor.executeN(self, n: int): SendResultList

Executes up to n transactions from the cursor and returns only this executed segment.

This is useful when you need to inspect the first few hops of a long chain without draining the whole queue.

TxCursor.executeTill

fun TxCursor.executeTill<Msg = unknown>(self, params: SearchParams = {}): SendResultList

Executes transactions until one of them matches params, then returns the executed segment.

The matching transaction is included in the returned list. If no matching transaction is found before the queue is exhausted, this function fails the test.

TxCursor.executeAllRemaining

fun TxCursor.executeAllRemaining(self): SendResultList

Executes all remaining pending transactions and returns only this executed segment.

testing.createTraceIterationCursor

fun testing.createTraceIterationCursor(from: address, message: OutMessage): TxCursor

Start step-by-step execution for a message sent from from.

In contrast to net.send, this method does not execute the whole transaction chain eagerly. Instead it returns a cursor that can be advanced in batches.

This API is emulation-only and is intended for programmable partial execution workflows such as large cascades and interleaving multiple message chains.

testing.processSingleTraceStep

fun testing.processSingleTraceStep(from: address, message: OutMessage): SendResult

Send a single message from a specified address.

In contrast to net.send, this method executes exactly one transaction and does not recursively process that transaction's out messages. The returned SendResult still contains those out messages for inspection, but they are left undelivered.

This method is useful to simulate a bounced message.

Example:

val bouncedMsg = createMessage({
    bounce: false,
    value: ton("0.95"),
    dest: deployer.address,
    body: beginCell().storeUint(0xFFFFFFFF, 32).storeSlice(body.toCell().beginParse()).endCell(),
}).bounced();

testing.processSingleTraceStep(notDeployer.address, bouncedMsg);

See net.send or net.sendExternal if you need full recursive trace processing.

testing.runTickTock

fun testing.runTickTock(onAccount: address, isTock: bool): SendResultList

Runs a tick or tock transaction on the specified account.

Tick-tock transactions have no incoming message and are triggered by the blockchain on special accounts (e.g., elector, config).

Example:

val results = testing.runTickTock(electorAddress, false); // run tick
val results = testing.runTickTock(electorAddress, true);  // run tock

Treasury

struct Treasury {
    address: address
}

Treasury is a special contract that is used to deploy other contracts.

To create a treasury, use the testing.treasury method.

testing.treasury

fun testing.treasury(name: string): Treasury

Create a treasury with a specified name.

Calling this method with same name will return the same treasury (the same address).

Example:

get fun `test mint`() {
    val treasury = testing.treasury("treasury");
    // ...
}

Note: in scripts always use scripts.wallet instead.

testing.getAccountState

fun testing.getAccountState(addr: address): TlbAccountInfo?

Returns current account state for address or null if no information available or contract is not deployed.

The account state includes balance, storage information, and other account data. See TlbAccountInfo type for more information.

Example:

val state = testing.getAccountState(contract.address);
if (state != null) {
    println("Balance: {:ton}", state.storage.balance.grams);
} else {
    println("Account not found");
}

testing.getAccountStorageFee

fun testing.getAccountStorageFee(addr: address, seconds: int): coins?

Returns storage fee for address for specified amount of seconds.

Returns null if the contract with given address is not deployed.

Example:

val storageFee = testing.getAccountStorageFee(contract.address, 86400); // 1 day
if (storageFee != null) {
    println("Daily storage fee: {:ton}", storageFee);
}

testing.setNow

fun testing.setNow(now: uint32): void

Set the current Unix timestamp for time forwarding emulation.

This is useful for testing time-dependent contracts.

testing.setNow() synchronizes time in two places:

• the emulated world state used for future transactions and snapshots
• the current VM context's C7 unixtime slot, so blockchain.now() in the current test/get-method context immediately sees the same mocked value

This is why testing.setNow() affects both future emulated execution and time-dependent helpers that read the current VM context right away.

Example:

val futureTime = testing.getNow() + 1000; // 1000 seconds from now
testing.setNow(futureTime);

testing.getNow

fun testing.getNow(): uint32

Get the current Unix timestamp used in emulation.

Returns the current time in the emulated blockchain.

Get-method execution prefers this mocked time once you have called testing.setNow. If the emulated time is still 0 (the default before any override), Acton falls back to the real wall clock for get-method runs.

Example:

val currentTime = testing.getNow();
println("Current emulation time: {}", currentTime);

testing.topUp

fun testing.topUp(to: address, amount: coins): void

Topup an address with a specified amount of TON.

Example:

testing.topUp(address, ton("10"));

Note: This function for tests only! For testnet TON airdrop onto your wallet, use acton wallet airdrop command.

testing.getAccountBalance

fun testing.getAccountBalance(of: address): coins

Get the balance of an address.

Returns 0 if the address is not deployed.

Example:

val balance = testing.getAccountBalance(address);
println("{:ton}", balance);

testing.getShardAccount

fun testing.getShardAccount(addr: address): TlbShardAccount?

Returns the shard account state for an address.

The returned shard account can represent an uninitialized account.

Example:

val shard = testing.getShardAccount(addr);
if (shard != null) {
    println("Last LT: {}", shard.lastTransLt);
}

testing.setShardAccount

fun testing.setShardAccount(addr: address, account: TlbShardAccount?): void

Sets the shard account state for an address in emulation.

Pass null to reset the account to an empty state.

Example:

val shard = testing.getShardAccount(addr);
if (shard != null) {
    testing.setShardAccount(addr, shard);
}

testing.loadAndRegisterLibrary

fun testing.loadAndRegisterLibrary(hash: string): bool

Load library by hash from emulated blockchain or real network and register it in the current emulated blockchain.

Returns false if library is not found.

testing.registerLibrary

fun testing.registerLibrary(libCell: cell): void

Register a library in the emulated blockchain.

testing.saveSnapshot

fun testing.saveSnapshot(pathToJsonFile: string): bool

Save the current emulation world state to a JSON snapshot file.

Returns true on successful write and false on serialization or host I/O failure.

Example:

testing.topUp(addr, ton("3"));
val saved = testing.saveSnapshot("world-state.json");
expect(saved).toBeTrue();

testing.loadSnapshot

fun testing.loadSnapshot(pathToJsonFile: string): bool

Load an emulation world state from a JSON snapshot file.

On success, replaces the current local emulation state with the snapshot contents. Returns false when the file is missing, malformed, or cannot be applied.

Example:

val loaded = testing.loadSnapshot("world-state.json");
expect(loaded).toBeTrue();

testing.setConfig

fun testing.setConfig(config: BlockchainConfigMap): bool

Sets the blockchain configuration.

This function updates the entire blockchain configuration with a new configuration dict. The configuration is validated before being applied. If validation fails, the function returns false and the configuration is not updated.

BlockchainConfigMap.set* methods only mutate the local map value returned by testing.getConfig. testing.setConfig() is the commit point that pushes those changes into the emulator.

On success, Acton synchronizes the configuration in two places:

• the emulator's world-state config used by future transactions and queries
• the current VM context's C7 config mirrors (both packed root config and the unpacked hot fields used by TVM helpers)

That extra C7 synchronization keeps the current test context, follow-up config getters, and emulated execution paths aligned on the same config data without requiring a fresh VM bootstrap.

For detailed information about blockchain configuration parameters, see the TON Blockchain Configuration Reference.

Parameters:

• config: The new BlockchainConfigMap map containing configuration parameters (indices 0-90)

Returns: true if the configuration was successfully updated, false if validation failed. On failure, neither the emulator world state nor the C7 mirrors are updated.

Example:

var config = testing.getConfig();
val storagePrices = config.getStoragePrices();
var pricesDict = storagePrices;
pricesDict.setInitial(StoragePrices {
    initialUnixTime: 0,
    bitPrice: 1,
    cellPrice: 1000,
    masterchainBitPrice: 1,
    masterchainCellPrice: 1000
});
config.setStoragePrices(pricesDict);
val success = testing.setConfig(config);
if (success) {
    println("Configuration updated successfully");
}

testing.getConfig

fun testing.getConfig(): BlockchainConfigMap

Retrieves the current blockchain configuration.

Returns a map of all blockchain configuration parameters indexed from 0-90. The configuration includes gas prices, storage costs, validator settings, and other network parameters. Use specialized getter functions like BlockchainConfigMap.getGasPrices, BlockchainConfigMap.getStoragePrices, or BlockchainConfigMap.getGlobalVersion to access specific parameters.

For detailed information about blockchain configuration parameters, see the TON Blockchain Configuration Reference.

Returns: A BlockchainConfigMap containing all current blockchain configuration parameters.

Example:

val config = testing.getConfig();

// Access specific configuration
val gasPrice = config.getGasPrices(BASECHAIN);
val storagePrices = config.getStoragePrices();
val globalVersion = config.getGlobalVersion();

println("Network version: {}", globalVersion.version);

testing.isDeployed

fun testing.isDeployed(addr: address): bool

Check if a contract with a specified address is deployed.

Returns true if the contract is deployed, false otherwise.

Example:

fun JettonWallet.getJettonBalance(self): coins {
    if (!testing.isDeployed(self.address)) {
        return 0; // return 0 if contract is not deployed
    }

    // and if deployed, actually run get method
    val result = net.runGetMethod<JettonWalletDataReply>(self.address, "get_wallet_data");
    return result.jettonBalance;
}

testing.outActions

fun testing.outActions(): OutActionList

Returns out actions from the control register C5 at that moment.

Example:

val outActions = testing.outActions();
println(outActions.size());