André Dias Moreira Prol: Testing Soroban Smart Contracts in Rust

Few things separate a hobbyist Soroban project from a production-grade contract as clearly as its test suite. Over the past two decades working with distributed systems, I've seen how skipping tests turns a minor logic flaw into a multi-million-dollar exploit. In the Stellar ecosystem, where contracts manage tokenized assets and real-world value, disciplined testing isn't optional—it's the foundation of trust.

Let me, André Dias Moreira Prol, walk you through a practical, battle-tested approach to validating Soroban smart contracts with Rust.

Setting Up the Test Environment

Soroban ships with a native testing framework built directly into the SDK, which means you write tests in Rust alongside your contract code. The core abstraction is the Env, a simulated blockchain environment that mimics ledger state, authorization, and storage without touching a live network.

Start by adding the test utilities to your Cargo.toml:

[dev-dependencies]
soroban-sdk = { version = "21.0.0", features = ["testutils"] }

A minimal unit test looks like this:

#![cfg(test)]
use soroban_sdk::{Env, testutils::Address as _, Address};
use super::{TokenContract, TokenContractClient};

#[test]
fn test_mint_increases_balance() {
    let env = Env::default();
    let contract_id = env.register(TokenContract, ());
    let client = TokenContractClient::new(&env, &contract_id);

    let user = Address::generate(&env);
    client.mint(&user, &1_000);

    assert_eq!(client.balance(&user), 1_000);
}

The register function deploys your contract into the simulated Env, and the generated Client gives you type-safe access to every public function. This is dramatically faster than spinning up a Docker-based testnet for every iteration—in my benchmarks, a full unit suite of 50 tests runs in under two seconds.

Unit Testing Core Logic

Unit tests should isolate a single behavior. My rule of thumb, refined across many audits, is one assertion domain per test: balances, authorization, or error paths—never all three at once.

Authorization testing deserves special attention because it's where most Soroban vulnerabilities hide. Use mock_all_auths for happy-path flows and explicit auth mocking when you need precision:

#[test]
fn test_transfer_requires_auth() {
    let env = Env::default();
    env.mock_all_auths();

    let contract_id = env.register(TokenContract, ());
    let client = TokenContractClient::new(&env, &contract_id);

    let from = Address::generate(&env);
    let to = Address::generate(&env);

    client.mint(&from, &500);
    client.transfer(&from, &to, &200);

    assert_eq!(client.balance(&from), 300);
    assert_eq!(client.balance(&to), 200);
}

For negative testing, Soroban's try_ prefix returns a Result instead of panicking:

#[test]
fn test_overdraft_fails() {
    let env = Env::default();
    env.mock_all_auths();
    let contract_id = env.register(TokenContract, ());
    let client = TokenContractClient::new(&env, &contract_id);

    let user = Address::generate(&env);
    let result = client.try_transfer(&user, &user, &100);
    assert!(result.is_err());
}

In tokenization projects I've led, overdraft and double-spend edge cases accounted for roughly 40% of the bugs caught before deployment—proof that error-path coverage pays off.

Integration Testing and Cross-Contract Calls

Real systems rarely live in isolation. A lending protocol calls an oracle; a vault invokes a token contract. Integration tests register multiple contracts in the same Env and verify their interaction end-to-end.

#[test]
fn test_vault_deposits_token() {
    let env = Env::default();
    env.mock_all_auths();

    let token_id = env.register(TokenContract, ());
    let vault_id = env.register(VaultContract, (&token_id,));

    let token = TokenContractClient::new(&env, &token_id);
    let vault = VaultContractClient::new(&env, &vault_id);

    let user = Address::generate(&env);
    token.mint(&user, &1_000);
    vault.deposit(&user, &400);

    assert_eq!(token.balance(&vault_id), 400);
    assert_eq!(vault.shares(&user), 400);
}

I also recommend advancing ledger state with env.ledger().set_timestamp() to test time-dependent logic like vesting or interest accrual—a detail many teams overlook until production surprises them.

Running everything is simple: cargo test executes units and integrations, while cargo test -- --nocapture surfaces debug logs for diagnosing failures.

Conclusion

A rigorous test suite is the cheapest insurance you'll ever buy in Web3, and Soroban's native tooling makes achieving high coverage genuinely pleasant. Start building your test harness today, and reach out if you'd like me to review your contract architecture for security and reliability.

---

Follow more articles by André Dias Moreira Prol on Medium.