sandbox you gain complete control of the network:
- Create test
Accountsand manipulate theirStateandBalance. - Simulate errors on callbacks.
- Control the time flow and fast-forward into the future.
near-sandbox to start and control a local NEAR node, and near-api to create accounts, deploy contracts, send transactions, and read their outcomes. The examples below use these libraries directly.
Sandbox TestingRun automated integration tests locally with
near-sandbox. Each test can create its own accounts, deploy contracts built from source, and inspect transaction and receipt outcomes. Use near-api to interact with the node through its local RPC endpoint.In-process alternative: near-mock
When a full sandbox node is more than you need — fast local iteration, hermetic CI, or replaying a specific mainnet account — near-mock executes unmodified contract wasm in-process via wasmtime: no node, Docker, RPC, or fees. Contracts only see host calls, state, and gas, so existing binaries (vaults, DEXes, oracles) run as-is and complete in milliseconds.
ecrecover, p256_verify, alt_bn128, keccak512, BLS12-381) using the same crates as nearcore.
Two patterns where it complements sandbox testing:
- Deterministic CI
- Mainnet forensics
Pin randomness, time, and epoch height via environment variables, so every CI run replays identically:
Create Accounts
Account
basics.rs
Using Secret Key
basics.rs
Using Credentials From File
basics.rs
WASM Files
Compile Contract Code
basics.rs
Loading From File
basics.rs
Deploy Contracts
Deploy To Account
basics.rs
Logs
Show contract’s logs. You can useprintln or dbg! when you want to see information from your code.
basics.rs
--nocapture flag
eg. cargo test -- --nocapture
If you want to access the contracts logs, you can find them in the tx_outcome.logs() Vec.
Account Balance
basics.rs
Transactions
Call
basics.rs
View
basics.rs
Patch State on the Fly
In Sandbox-mode, you can add or modify any contract state, contract code, account or access key withpatchState.
You can alter contract code, accounts, and access keys using normal transactions via the DeployContract, CreateAccount, and AddKey actions. But this limits you to altering your own account or sub-account. patchState allows you to perform these operations on any account.
basics.rs
As an alternative to
patchState, you can stop the node, dump state at genesis, edit the genesis, and restart the node.
This approach is more complex to do and also cannot be performed without restarting the node.Time Traveling
sandbox offers support for forwarding the state of the blockchain to the future. This means contracts which require time sensitive data do not need to sit and wait the same amount of time for blocks on the sandbox to be produced. We can simply just call sandbox.fast_forward to get us further in time:
basics.rs
Using Testnet
For checks against deployed testnet contracts, usenear-api with NetworkConfig::testnet() and funded testnet accounts. Sandbox runs a separate local node; its account creation, state patching, and fast-forward controls apply to that local node. Testnet checks can help you:
- Check your contract against a public network
- Exercise interactions with existing testnet contracts
- Compare results with your local Sandbox tests
basics.rs
Spooning Contracts
Spooning a blockchain is copying the data from one network into a different network. NEAR Sandbox makes it easy to copy data from Mainnet or Testnet contracts into your local Sandbox environment: Specify the contract name fromtestnet you want to be pulling, and a specific block ID referencing back to a specific time. (Just in case the contract you’re referencing has been changed or updated)
Create a function called pull_contract which will pull the contract’s .wasm file from the chain and deploy it onto your local sandbox. You’ll have to re-initialize it with all the data to run tests. This is because the contract’s data is too big for the RPC service to pull down. (limits are set to 50Mb)
basics.rs
Snippets
Snippet I: Testing Hello NEAR
Lets take a look at the test of our Quickstart Project 👋 Hello NEAR, where we deploy the contract on an account and test it correctly retrieves and sets the greeting.test_basics.rs
Snippet II: Testing Donations
In most cases we will want to test complex methods involving multiple users and money transfers. A perfect example for this is our Donation Example, which enables users todonate money to a beneficiary. Lets see its integration tests
test_basics.rs