Integration Tests

Integration tests enable you to deploy a contract in the NEAR testnet or a local sandbox and create test users to interact with it. This way, you can thoroughly test your contract in a realistic environment. Moreover, when using the local sandbox you gain complete control of the network:

Create test Accounts and manipulate their State and Balance.
Simulate errors on callbacks.
Control the time-flow and fast-forward into the future (Rust ready, TS coming soon).

In NEAR, integration tests are implemented using a framework called Sandbox. Sandbox comes in two flavors: 🦀 Rust and 🌐 Typescript. For Go contracts, unit tests are run with the near-go CLI:

near-go test project

This runs unit tests using the MockSystem environment to simulate the NEAR blockchain locally — no sandbox required. For full integration tests that deploy to a sandbox, Go contracts use the Rust workspaces-rs framework. See the Go Integration Testing section below.

Sandbox TestingNEAR Sandbox allows you to write tests once, and run them either on testnet or a local Sandbox. By default, Sandbox will start a sandbox and run your tests locally. Lets dive into the features of our framework and see how they can help you.

Create Accounts

Account

🦀 Rust

Dev Account

🌐 JavaScript

Subaccount

🌐 JavaScript

Using Secret Key

🦀 Rust
🌐 JavaScript

Using Credentials From File

🦀 Rust
🌐 JavaScript

WASM Files

Compile Contract Code

🦀 Rust
🌐 JavaScript

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.

let contract_wasm_path = cargo_near_build::build_with_cli(Default::default())?;

If you want to compile a contract each time running tests, you can put following scripts into package.json file. In the code you can access path to compiled file using process.argv[2].package.json file:

"scripts": {
  "build": "near-sdk-js build src/contract.ts build/hello_near.wasm",
  "test": "$npm_execpath run build && ava -- ./build/hello_near.wasm"
},

main.ava.js file:

const pathToWasm = process.argv[2];
await contract.deploy(pathToWasm);

Loading From File

🦀 Rust
🌐 JavaScript

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.

let contract_wasm = std::fs::read(artifact_path)
    .expect(format!("Could not read WASM file from {}", artifact_path).as_str());

If you want to use pre-compiled a contract, you can put following scripts into package.json file. In the code you can access path to pre-compiled file using process.argv[2].package.json file:

"scripts": {
  "build": "near-sdk-js build src/contract.ts build/hello_near.wasm",
  "test": "ava -- ./build/hello_near.wasm"
},

main.ava.js file:

const pathToWasm = process.argv[2];
await contract.deploy(pathToWasm);

Deploy Contracts

Dev Deploy

🌐 JavaScript

Deploy To Account

🦀 Rust
🌐 JavaScript

Logs

Show contract’s logs.

🦀 Rust
🌐 JavaScript

You can use println or dbg! when you want to see information from your code.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 flageg. cargo test -- --nocaptureIf you want to access the contracts logs, you can find them in the tx_outcome.logs() Vec.

let tx_outcome = contract
        .call_function("set_greeting", json!({"greeting": "Hello World!"}))
        .transaction()
        .gas(Gas::from_tgas(100))
        .with_signer(contract.account_id().clone(), signer.clone())
        .send_to(&sandbox_network)
        .await?;
    assert!(tx_outcome.is_success());

    dbg!(tx_outcome.logs());
    // [tests/test_basics.rs:29:5] tx_outcome.logs() = [
    //     "Saving greeting: Hello World!",
    // ]

Use console.log method when you want to see debug information from your code.

const balance = await account.balance();

console.log('balance: ', balance);
// balance:  {
//   total: <BN: 52b7d2dcc80cd2e4000000>,
//   stateStaked: <BN: 62a992e53a0af00000>,
//   staked: <BN: 0>,
//   available: <BN: 52b77033352798d9100000>
// }

Account Balance

🦀 Rust
🌐 JavaScript

Transactions

Call

🦀 Rust
🌐 JavaScript

View

🦀 Rust
🌐 JavaScript

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.

🦀 Rust
🌐 JavaScript

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:

🦀 Rust
🌐 JavaScript

See the full example on Github.

Using Testnet

NEAR Sandbox is set up so that you can write tests once and run them against a local Sandbox node (the default behavior) or against NEAR TestNet. Some reasons this might be helpful:

Gives higher confidence that your contracts work as expected
You can test against deployed testnet contracts
If something seems off in Sandbox mode, you can compare it to testnet

🦀 Rust
🌐 JavaScript

If you can create a new account on each iteration as well.

You can switch to testnet mode in three ways:

1. Setting the `Worker` network to `testnet`

When creating Worker set network to testnet and pass your master account (an account for which you have the private key):

const worker = await Worker.init({
  network: 'testnet',
  testnetMasterAccountId: '<yourAccountName>',
  initialBalance: NEAR.parse("<X> N").toString(),
})

2. Setting environment variables

Set the NEAR_WORKSPACES_NETWORK and TESTNET_MASTER_ACCOUNT_ID (an account for which you have the private key) environment variables when running your tests:

NEAR_WORKSPACES_NETWORK=testnet TESTNET_MASTER_ACCOUNT_ID=<your master account Id> node test.js

If you set this environment variables and pass {network: 'testnet', testnetMasterAccountId: <masterAccountId>} to Worker.init, the config object takes precedence.

3. Config file

If you are using AVA, you can use a custom config file. Other test runners allow similar config files; adjust the following instructions for your situation.Create a file in the same directory as your package.json called ava.testnet.config.cjs with the following contents:

module.exports = {
...require('near-workspaces/ava.testnet.config.cjs'),
...require('./ava.config.cjs'),
};
module.exports.environmentVariables = {
    TESTNET_MASTER_ACCOUNT_ID: '<masterAccountId>',
};

Where the master account is an account for which you have the private key.The near-workspaces/ava.testnet.config.cjs import sets the NEAR_WORKSPACES_NETWORK environment variable for you. A benefit of this approach is that you can then easily ignore files that should only run in Sandbox mode.Now you’ll also want to add a test:testnet script to your package.json’s scripts section:

"scripts": {
  "test": "ava",
+  "test:testnet": "ava --config ./ava.testnet.config.cjs"
}

To use the accounts, you will need to create the .near-credentials/workspaces/testnet directory and add files for your master account, for example:

// .near-credentials/workspaces/testnet/<your-account>.testnet.json
{"account_id":"<your-account>.testnet","public_key":"ed25519:...","private_key":"ed25519:..."}

Example:

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:

🦀 Rust
🌐 JavaScript

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)

const refFinance = await root.importContract({
  mainnetContract: 'v2.ref-finance.near',
  blockId: 50_000_000,
  withData: true,
});

This would copy the Wasm bytes and contract state from v2.ref-finance.near to your local blockchain as it existed at block 50_000_000. This makes use of Sandbox’s special patch state feature to keep the contract name the same, even though the top level account might not exist locally (note that this means it only works in Sandbox testing mode). You can then interact with the contract in a deterministic way the same way you interact with all other accounts created with near-workspaces.

withData will only work out-of-the-box if the contract’s data is 50kB or less. This is due to the default configuration of RPC servers; see the “Heads Up” note here.

See a TypeScript example of spooning contracts.

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.

🦀 Rust
🌐 JavaScript
🐹 GO

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

🦀 Rust
🌐 JavaScript
🐹 GO

Go Integration Testing

Go contracts use the Rust workspaces-rs framework for integration tests. The workflow is:

Build your contract to WASM with near-go build
Write integration tests in a separate Rust project using workspaces-rs
Run with cargo test

Unit tests vs Integration testsnear-go test project runs unit tests using the MockSystem environment locally. For full integration tests that deploy to a sandbox, use the workspaces-rs Rust crate as described below.

Project Structure

my-contract/
├── main.go              # your Go contract
├── go.mod
├── go.sum
└── integration-tests/   # Standalone Rust integration test project
    ├── Cargo.toml
    └── tests/
        └── test_my_contract.rs

Running Tests

# Step 1: Build the Go contract to WASM (from the contract root)
near-go build

# Step 2: Run integration tests
cargo test --manifest-path integration-tests/Cargo.toml

Writing Integration Tests

Integration tests follow the workspaces-rs pattern. The compiled main.wasm sits one directory above integration-tests/, so tests load it with std::fs::read("../main.wasm").

Double-encoded return valuesnear-sdk-go wraps every return value in an extra JSON string encoding. When reading a view result, always deserialize in two steps: first parse the outer String, then parse the inner type.

// ✅ Correct two-step deserialization
let raw: String = contract.view("get_greeting").args_json(json!({})).await?.json()?;
let greeting: String = serde_json::from_str(&raw)?;

// ❌ Will fail – skips the outer wrapper
let greeting: String = contract.view("get_greeting").args_json(json!({})).await?.json()?;

// integration-tests/tests/test_greeting.rs
use serde_json::json;

#[tokio::test]
async fn test_greeting_init() -> anyhow::Result<()> {
    let sandbox = near_workspaces::sandbox().await?;
    let wasm = std::fs::read("../main.wasm")?;
    let contract = sandbox.dev_deploy(&wasm).await?;

    contract
        .call("init")
        .args_json(json!({}))
        .transact()
        .await?
        .into_result()?;

    // Two-step deserialization: outer String wrapper → inner type
    let raw: String = contract.view("get_greeting").args_json(json!({})).await?.json()?;
    let greeting: String = serde_json::from_str(&raw)?;
    assert_eq!(greeting, "Hello");
    Ok(())
}

#[tokio::test]
async fn test_set_greeting() -> anyhow::Result<()> {
    let sandbox = near_workspaces::sandbox().await?;
    let wasm = std::fs::read("../main.wasm")?;
    let contract = sandbox.dev_deploy(&wasm).await?;

    contract.call("init").args_json(json!({})).transact().await?.into_result()?;

    let caller = sandbox.dev_create_account().await?;
    caller
        .call(contract.id(), "set_greeting")
        .args_json(json!({ "greeting": "Howdy" }))
        .transact()
        .await?
        .into_result()?;

    let raw: String = contract.view("get_greeting").args_json(json!({})).await?.json()?;
    let greeting: String = serde_json::from_str(&raw)?;
    assert_eq!(greeting, "Howdy");
    Ok(())
}

# integration-tests/Cargo.toml
[package]
name = "greeting-integration-tests"
version = "0.1.0"
edition = "2021"

[dev-dependencies]
near-workspaces = "0.22.0"
tokio = { version = "1.41.1", features = ["full"] }
anyhow = "1.0.93"
serde_json = "1.0.133"
serde = { version = "1.0.215", features = ["derive"] }

You can also test your Go contract on NEAR testnet by deploying it first with near deploy and calling methods via the near CLI.See full example on GitHub

Additional Resources

Advanced Examples

Test Driven Design Using Workspaces and AVA

The video below walks through how to apply TDD with Workspaces and AVA for a simple contract:

Concepts

DevKit

Tutorials

Create Accounts

Account

Dev Account

Subaccount

Using Secret Key

Using Credentials From File

WASM Files

Compile Contract Code

Loading From File

Deploy Contracts

Dev Deploy

Deploy To Account

Logs

Account Balance

Transactions

Call

View

Patch State on the Fly

Time Traveling

Using Testnet

Spooning Contracts

Snippets

Snippet I: Testing Hello NEAR

Snippet II: Testing Donations

Go Integration Testing

Project Structure

Running Tests

Writing Integration Tests

Additional Resources

Advanced Examples

Test Driven Design Using Workspaces and AVA

Concepts

DevKit

Tutorials

Documentation Index

​Create Accounts

​Account

​Dev Account

​Subaccount

​Using Secret Key

​Using Credentials From File

​WASM Files

​Compile Contract Code

​Loading From File

​Deploy Contracts

​Dev Deploy

​Deploy To Account

​Logs

​Account Balance

​Transactions

​Call

​View

​Patch State on the Fly

​Time Traveling

​Using Testnet

​Spooning Contracts

​Snippets

​Snippet I: Testing Hello NEAR

​Snippet II: Testing Donations

​Go Integration Testing

​Project Structure

​Running Tests

​Writing Integration Tests

​Additional Resources

​Advanced Examples

​Test Driven Design Using Workspaces and AVA

Create Accounts

Account

Dev Account

Subaccount

Using Secret Key

Using Credentials From File

WASM Files

Compile Contract Code

Loading From File

Deploy Contracts

Dev Deploy

Deploy To Account

Logs

Account Balance

Transactions

Call

View

Patch State on the Fly

Time Traveling

Using Testnet

Spooning Contracts

Snippets

Snippet I: Testing Hello NEAR

Snippet II: Testing Donations

Go Integration Testing

Project Structure

Running Tests

Writing Integration Tests

Additional Resources

Advanced Examples

Test Driven Design Using Workspaces and AVA