Quick Start

Write a complete Soroban test in about a minute: build a context, register the contract, invoke it, then assert on events and resource cost in the same test.

Imports

#![allow(unused)]
fn main() {
use soroban_sdk::{Env, Address};
use soroban_testkit_fixtures::builder::TestContextBuilder;
use soroban_testkit_assert::events::EventMatcher;
use soroban_testkit_core::budget::BudgetSnapshot;
}

Write a test

1. Build the context

   TestContextBuilder hands you a mocked Env plus ready-made addresses.

2. Register the contract

   Bind your contract to the context environment and create its client.

3. Invoke the contract

   Call the function under test, then read the metering that call left behind.

4. Assert on events and cost

   Match the events the call emitted and check its instruction count against a ceiling.

#![allow(unused)]
fn main() {
#[test]
fn test_token_transfer() {
    // 1. Create a test context with pre-generated users
    let ctx = TestContextBuilder::new()
        .with_users(2)
        .build();

    let sender = &ctx.users[0];
    let receiver = &ctx.users[1];

    // 2. Register your contract
    let contract_id = ctx.env.register(MyContract, ());
    let client = MyContractClient::new(&ctx.env, &contract_id);

    // 3. Invoke the function under test
    client.transfer(sender, receiver, &1000);

    // 4. Read the metering that invocation left behind
    let cost = BudgetSnapshot::last_invocation(&ctx.env);

    // 5. Assert events were emitted, and what they carried
    EventMatcher::new(&ctx.env)
        .from_contract(&contract_id)
        .with_topic("Transfer")
        .assert_emitted();
    EventMatcher::new(&ctx.env)
        .with_topic("Transfer")
        .assert_data_matches(|data| data.deserialize::<i128>() == Some(1_000));

    // 6. Check resource consumption
    assert!(cost.cpu_insns < 500_000);
}
}

What’s happening

Next steps