Skip to main content
Integration tests deploy your contract to a local NEAR Sandbox and create test accounts to interact with it. This lets you test contract behavior in a realistic blockchain environment. Moreover, when using the local sandbox you gain complete control of the network:
  1. Create test Accounts and manipulate their State and Balance.
  2. Simulate errors on callbacks.
  3. Control the time flow and fast-forward into the future.
Use Rust 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.
It implements the production host surface (~140 functions: storage, registers, promise batch actions, validators, epochs), protocol-accurate gas metering (V155 fee table), and the real crypto precompiles (ecrecover, p256_verify, alt_bn128, keccak512, BLS12-381) using the same crates as nearcore. Two patterns where it complements sandbox testing:
Pin randomness, time, and epoch height via environment variables, so every CI run replays identically:
For workflows that need the full node stack — wallets, indexers, network behavior — keep using near-sandbox. Use near-mock when you want chain semantics without the chain.

Create Accounts

Account

basics.rs

Using Secret Key

basics.rs

Using Credentials From File

basics.rs

WASM Files

Compile Contract Code

basics.rs
You don’t need to assert compiling process everytime. You can use ? operator to get the result as Vec<u8> without dealing with Result<Vec<u8>>, Error> type. That way you can directly use this vector to deploy the wasm file into account. Your test will still fail if compiling process fails.

Loading From File

basics.rs
The same as in the case of compilation wasm from code, you don’t need to assert reading file process everytime. You can use expect method to get the reading file result as Vec<u8> and provide error message as a parameter. Your test will still fail if compiling process fails.

Deploy Contracts

Deploy To Account

basics.rs

Logs

Show contract’s logs. You can use println or dbg! when you want to see information from your code.
basics.rs
In Rust, the output from your code is captured by default and not displayed in the terminal. In order to see the output, you have to use the --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 with patchState. 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
See the full Sandbox timeout test.

Using Testnet

For checks against deployed testnet contracts, use near-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
If you can create a new account on each iteration as well.

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 from testnet 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 to donate money to a beneficiary. Lets see its integration tests
test_basics.rs

Additional Resources

Advanced Examples