Test Scenario

For complicated transaction testing, Sui features the test_scenario module. This module provides functions to emulate transactions, define senders, and check the results of transactions.

/// This module contains a dummy store implementation where anyone can purchase
/// the same book for any amount of SUI greater than zero. The store owner can
/// collect the proceeds using the `StoreOwnerCap` capability.
/// In the tests section, we use the `test_scenario` module to simulate a few
/// transactions and test the store functionality. The test scenario is a very
/// powerful tool which can be used to simulate multiple transactions in a single
/// test.
/// The reference for this module is the "Black Books" TV series.
module examples::black_books {
    use sui::sui::SUI;
    use sui::coin::{Self, Coin};
    use sui::balance::{Self, Balance};

    /// Trying to purchase the book for 0 SUI.
    const ECantBeZero: u64 = 0;

    /// A store owner capability. Allows the owner to collect proceeds.
    public struct StoreOwnerCap has key, store { id: UID }

    /// The "Black Books" store located in London.
    /// Only sells one book: "The Little Book of Calm".
    public struct BlackBooks has key {
        id: UID,
        balance: Balance<SUI>,

    /// The only book sold by the Black Books store.
    public struct LittleBookOfCalm has key, store { id: UID }

    /// Share the store object and transfer the store owner capability to the sender.
    fun init(ctx: &mut TxContext) {
        transfer::transfer(StoreOwnerCap {
            id: object::new(ctx)
        }, ctx.sender());

        transfer::share_object(BlackBooks {
            id: object::new(ctx),
            balance: balance::zero()

    /// Purchase the "Little Book of Calm" for any amount of SUI greater than zero.
    public fun purchase(
        store: &mut BlackBooks, coin: Coin<SUI>, ctx: &mut TxContext
    ): LittleBookOfCalm {
        assert!(coin.value() > 0, ECantBeZero);

        // create a new book
        LittleBookOfCalm { id: object::new(ctx) }

    /// Collect the proceeds from the store and return them to the sender.
    public fun collect(
        store: &mut BlackBooks, _cap: &StoreOwnerCap, ctx: &mut TxContext
    ): Coin<SUI> {
        let amount = store.balance.value();

    // === Tests ===

    // The `init` is not run in tests, and normally a test_only function is
    // provided so that the module can be initialized in tests. Having it public
    // is important for tests located in other modules.
    public fun init_for_testing(ctx: &mut TxContext) {

    // using a test-only attibute because this dependency can't be used in
    // production code and `sui move build` will complain about unused imports.
    // the `sui::test_scenario` module is only available in tests.
    #[test_only] use sui::test_scenario;

    // This test uses `test_scenario` to emulate actions performed by 3 accounts.
    // A single scenario follows this structure:
    // - `begin` - starts the first tx and creates the sceanario
    // - `next_tx` ... - starts the next tx and sets the sender
    // - `end` - wraps up the scenario
    // It provides functions to start transactions, get the `TxContext, pull
    // objects from account inventory and shared pool, and check transaction
    // effects.
    // In this test scenario:
    // 1. Bernard opens the store;
    // 2. Manny buys the book for 10 SUI and sends it to Fran;
    // 3. Fran sends the book back and buys it herself for 5 SUI;
    // 4. Bernard collects the proceeds and transfers the store to Fran;
    fun the_book_store_drama() {
        // it's a good idea to name addresses for readability
        // Bernard is the store owner, Manny is searching for the book,
        // and Fran is the next door store owner.
        let (bernard, manny, fran) = (@0x1, @0x2, @0x3);

        // create a test scenario with sender; initiates the first transaction
        let mut scenario = test_scenario::begin(bernard);

        // === First transaction ===

        // run the module initializer
        // we use curly braces to explicitly scope the transaction;
            // `test_scenario::ctx` returns the `TxContext`

        // `next_tx` is used to initiate a new transaction in the scenario and
        // set the sender to the specified address. It returns `TransactionEffects`
        // which can be used to check object changes and events.
        let prev_effects = scenario.next_tx(manny);

        // make assertions on the effects of the first transaction
        let created_ids = prev_effects.created();
        let shared_ids = prev_effects.shared();
        let sent_ids = prev_effects.transferred_to_account();
        let events_num = prev_effects.num_user_events();

        assert!(created_ids.length() == 2, 0);
        assert!(shared_ids.length() == 1, 1);
        assert!(sent_ids.size() == 1, 2);
        assert!(events_num == 0, 3);

        // === Second transaction ===

        // we will store the `book_id` in a variable so we can use it later
        let book_id = {
            // test scenario can pull shared and sender-owned objects
            // here we pull the store from the pool
            let mut store = scenario.take_shared<BlackBooks>();
            let ctx = scenario.ctx();
            let coin = coin::mint_for_testing<SUI>(10_000_000_000, ctx);

            // call the purchase function
            let book = store.purchase(coin, ctx);
            let book_id = object::id(&book);

            // send the book to Fran
            transfer::transfer(book, fran);

            // now return the store to the pool

            // return the book ID so we can use it across transactions

        // === Third transaction ===

        // next transaction - Fran looks in her inventory and finds the book
        // she decides to return it to Manny and buy another one herself
            // objects can be taken from the sender by ID (if there's multiple)
            // or if there's only one object: `take_from_sender<T>(&scenario)`
            let book = scenario.take_from_sender_by_id<LittleBookOfCalm>(book_id);
            // send the book back to Manny
            transfer::transfer(book, manny);

            // now repeat the same steps as before
            let mut store = scenario.take_shared<BlackBooks>();
            let ctx = scenario.ctx();
            let coin = coin::mint_for_testing<SUI>(5_000_000_000, ctx);

            // same as before - purchase the book
            let book = store.purchase(coin, ctx);
            transfer::transfer(book, fran);

            // don't forget to return

        // === Fourth transaction ===

        // last transaction - Bernard collects the proceeds and transfers the store to Fran
        test_scenario::next_tx(&mut scenario, bernard);
            let mut store = scenario.take_shared<BlackBooks>();
            let cap = scenario.take_from_sender<StoreOwnerCap>();
            let ctx = scenario.ctx();
            let coin = store.collect(&cap, ctx);

            transfer::public_transfer(coin, bernard);
            transfer::transfer(cap, fran);

        // finally, the test scenario needs to be finalized