> ## Documentation Index
> Fetch the complete documentation index at: https://neardocs-docs-2123-js-error-prone-collections.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Integration Tests
> Learn how to write and run integration tests for NEAR smart contracts using Sandbox testing and realistic blockchain environments.
export const Github = ({url, start, end, fname, withSourceLink = true}) => {
const [code, setCode] = useState(null);
function toRaw(ref) {
const fullUrl = ref.slice(ref.indexOf('https'));
const [url] = fullUrl.split('#');
const [org, repo, , branch, ...pathSeg] = new URL(url).pathname.split('/').slice(1);
return `https://raw.githubusercontent.com/${org}/${repo}/${branch}/${pathSeg.join('/')}`;
}
async function fetchCode(url, fromLine, toLine) {
let res;
if (typeof window !== 'undefined') {
const validUntil = localStorage.getItem(`${url}-until`);
if (validUntil && Number(validUntil) > Date.now()) {
res = localStorage.getItem(url);
}
}
if (!res) {
try {
res = await (await fetch(url)).text();
if (typeof window !== 'undefined') {
localStorage.setItem(url, res);
localStorage.setItem(`${url}-until`, String(Date.now() + 60000));
}
} catch {
return 'Error fetching code, please try reloading';
}
}
let body = res.split('\n');
const from = fromLine ? Number(fromLine) - 1 : 0;
const to = toLine ? Number(toLine) : body.length;
body = body.slice(from, to);
const precedingSpace = body.reduce((prev, line) => {
if (line.length === 0) return prev;
const spaces = line.match(/^\s+/);
if (spaces) return Math.min(prev, spaces[0].length);
return 0;
}, Infinity);
return body.map(line => line.slice(precedingSpace === Infinity ? 0 : precedingSpace)).join('\n');
}
function buildSourceUrl(url, start, end) {
const base = url.split('#')[0];
if (start && end) return `${base}#L${start}-L${end}`;
if (start) return `${base}#L${start}`;
return base;
}
useEffect(() => {
const rawUrl = toRaw(url);
fetchCode(rawUrl, start, end).then(res => setCode(res));
}, [url, start, end]);
const sourceUrl = buildSourceUrl(url, start, end);
const startLine = start ? Number(start) : 1;
const fileName = fname ?? sourceUrl.split('/').pop();
return
{}
{start && end &&
Lines {start}β{end}
}
{}
{code === null ?
Loading...
:
{code.split('\n').map((line, i) =>
|
{startLine + i}
|
{line || ' '}
|
)}
}
{}
{withSourceLink &&
}
### Dev Account
### Subaccount
### Using Secret Key
### Using Credentials From File
***
## WASM Files
### Compile Contract Code
You don't need to assert compiling process everytime. You can use `?` operator to get the result as `Vec` without dealing with `Result>, 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.
```rust theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
"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:
```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const pathToWasm = process.argv[2];
await contract.deploy(pathToWasm);
```
### Loading From File
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` and provide error message as a parameter. Your test will still fail if compiling process fails.
```rust theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
"scripts": {
"build": "near-sdk-js build src/contract.ts build/hello_near.wasm",
"test": "ava -- ./build/hello_near.wasm"
},
```
`main.ava.js` file:
```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const pathToWasm = process.argv[2];
await contract.deploy(pathToWasm);
```
***
## Deploy Contracts
### Dev Deploy
### Deploy To Account
***
## Logs
Show contract's logs.
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` flag
eg. `cargo test -- --nocapture`
If you want to access the contracts logs, you can find them in the `tx_outcome.logs()` Vec.
```rust theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.
```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const balance = await account.balance();
console.log('balance: ', balance);
// balance: {
// total: ,
// stateStaked: ,
// staked: ,
// available:
// }
```
***
## Account Balance
***
## Transactions
### Call
### View
***
## 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](https://nomicon.io/RuntimeSpec/Actions#addkeyaction). But this limits you to altering your own account or sub-account. `patchState` allows you to perform these operations on any account.
To see a complete example of how to do this, see the [patch-state test](https://github.com/near/workspaces-js/blob/main/__tests__/02.patch-state.ava.ts).
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:
*[See the full example on Github](https://github.com/near/workspaces-rs/blob/main/examples/src/fast_forward.rs).*
***
## 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](../../protocol/network/networks). 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
If you can create a new account on each iteration as well.
You can switch to testnet mode in three ways:
When creating Worker set network to `testnet` and pass your master account (an account for which you have the private key):
```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
const worker = await Worker.init({
network: 'testnet',
testnetMasterAccountId: '',
initialBalance: NEAR.parse(" N").toString(),
})
```
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:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
NEAR_WORKSPACES_NETWORK=testnet TESTNET_MASTER_ACCOUNT_ID= node test.js
```
If you set this environment variables and pass `{network: 'testnet', testnetMasterAccountId: }` to `Worker.init`, the config object takes precedence.
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:
```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
module.exports = {
...require('near-workspaces/ava.testnet.config.cjs'),
...require('./ava.config.cjs'),
};
module.exports.environmentVariables = {
TESTNET_MASTER_ACCOUNT_ID: '',
};
```
Where the master account is an account for which you have the private key.
The [near-workspaces/ava.testnet.config.cjs](https://github.com/near/workspaces-js/blob/main/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:
```diff theme={"theme":{"light":"github-light","dark":"github-dark"}}
"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:
```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
// .near-credentials/workspaces/testnet/.testnet.json
{"account_id":".testnet","public_key":"ed25519:...","private_key":"ed25519:..."}
```
Example:
***
## Spooning Contracts
[Spooning a blockchain](https://coinmarketcap.com/alexandria/glossary/spoon-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)
```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://nearblocks.io/address/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](#patch-state-on-the-fly) 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](/api/rpc/contracts#view-contract-state).
See a [TypeScript example of spooning](https://github.com/near/workspaces-js/blob/main/__tests__/05.spoon-contract-to-sandbox.ava.ts) contracts.
***
## Snippets
### Snippet I: Testing Hello NEAR
Lets take a look at the test of our [Quickstart Project](../quickstart) [π Hello NEAR](https://github.com/near-examples/hello-near-examples), where we deploy the contract on an account and test it correctly retrieves and sets the greeting.
### 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](https://github.com/near-examples/donation-examples), which enables users to `donate` money to a beneficiary. Lets see its integration tests
***
## Go Integration Testing
Go contracts use the Rust `workspaces-rs` framework for integration tests. The workflow is:
1. Build your contract to WASM with `near-go build`
2. Write integration tests in a separate Rust project using `workspaces-rs`
3. Run with `cargo test`
**Unit tests vs Integration tests**
`near-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
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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 values**
`near-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.
```rust theme={"theme":{"light":"github-light","dark":"github-dark"}}
// β
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()?;
```
```rust theme={"theme":{"light":"github-light","dark":"github-dark"}}
// 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(())
}
```
```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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](https://github.com/Emir-Asanov/near-go-examples/blob/example-release-1/greeting/integration-tests/tests/test_greeting.rs)
***
## Additional Resources
### Advanced Examples
* [Rust](https://github.com/near/near-sandbox-rs/tree/main/examples)
* [JavaScript](https://github.com/near/near-workspaces-js/tree/main/__tests__)
### Test Driven Design Using Workspaces and AVA
The video below walks through how to apply TDD with Workspaces and AVA for a simple contract: