Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Stellar · Soroban · Test tooling

Soroban Testkit

Soroban Testkit is an open-source testing and debugging framework for Soroban smart contracts. It layers ergonomic fixtures, assertions, budget introspection and property-testing strategies on top of the official SDK, so contract tests are shorter, faster to write, and far closer to how they behave on-chain.

Quick start View on GitHub Contribute & earn
Soroban SDK v28 Rust 1.91+ 4 workspace crates Stellar Wave funded

Why Testkit

The Soroban SDK ships solid primitives — Env::default(), testutils, event inspection — but day-to-day contract testing still has rough edges that every team re-solves on its own.

Verbose setup Every test manually creates an environment, registers contracts, generates addresses and seeds state. Solved by soroban-testkit-fixtures — a Foundry-style `setUp` context builder.
Raw assertions Matching events and authorizations means destructuring tuples by hand with no domain helpers. Solved by soroban-testkit-assert — chainable event and auth matchers.
Hidden resource costs Tests pass locally yet fail on-chain once the CPU or memory budget is exhausted. Solved by soroban-testkit-core — budget snapshots and diffs around any call.
Heavyweight mocking Stubbing a single dependency forces you to write and register an entire mock contract. Solved by soroban-testkit-core — error decoding and storage inspection helpers.
No property-testing support Soroban-aware generators have to be rebuilt from scratch in every project. Solved by soroban-testkit-generators — `proptest` and `arbitrary` strategies for SDK types.

The Crates

Each crate is independent — adopt one, or combine all four for a complete testing stack.

soroban-testkit-core

Inspect & measure

Budget snapshots with call-level diffs, on-chain error decoding, and storage inspection across instance, persistent and temporary tiers.

BudgetSnapshotDecodedError
soroban-testkit-assert

Assert fluently

Readable matchers for contract events and authorizations, filterable by contract id and topic.

EventMatcherAuthMatcher
soroban-testkit-fixtures

Set up once

A reusable test context plus a builder for environments, admin accounts and generated users.

TestContextTestContextBuilder
soroban-testkit-generators

Generate wildly

Property-testing strategies for token amounts, ledger sequences and timestamps that respect Soroban limits.

proptestarbitrary

Architecture

soroban-testkit/                    Cargo workspace, resolver 2
├── crates/soroban-testkit-core             budget snapshots · error decoding · storage
├── crates/soroban-testkit-assert           event matchers · authorization matchers
├── crates/soroban-testkit-fixtures         test context · context builder
└── crates/soroban-testkit-generators       proptest strategies · arbitrary impls

A First Look

Six lines to a real test

Build a context, register the contract, invoke a call, then assert on events and budget in the same breath.

#![allow(unused)]
fn main() {
use soroban_testkit_assert::events::EventMatcher;
use soroban_testkit_fixtures::TestContext;

#[test]
fn transfer_emits_event() {
    let ctx = TestContext::new();
    // arrange: register your contract against ctx.env
    // act: invoke the contract client

    EventMatcher::new(&ctx.env).assert_emitted();
}
}

Full walkthroughs live in Quick Start, Testing Patterns and Budget-Aware Testing.

Stellar Wave

This project is funded through the Stellar Wave program on Drips Network. Every issue carries a complexity label — Trivial 100 pts Medium 150 pts High 200 pts — and rewards land once your PR is merged.

Pick up an issue

Built and maintained by Stellar Crucible · Apache-2.0 licensed · contributions welcome.