Testing contracts with Stylus

Introduction

The Stylus SDK provides a testing framework that allows developers to write and run tests directly in Rust without deploying to a blockchain. This guide will walk you through the process of writing and running tests for Stylus contracts using the built-in testing framework.

The Stylus testing framework allows you to:

Simulate an Ethereum environment for your tests
Test storage operations
Mock transaction context and block information
Test contract-to-contract interactions
Verify contract logic without deployment costs

Prerequisites

Before you begin, make sure you have:

Basic familiarity with Rust and smart contract development

Rust toolchain

Follow the instructions on Rust Lang's installation page to install a complete Rust toolchain (v1.81 or newer) on your system. After installation, ensure you can access the programs rustup, rustc, and cargo from your preferred terminal application.

Docker

The testnode we will use as well as some cargo stylus commands require Docker to operate.

You can download Docker from Docker's website.

Nitro devnode

Stylus is available on Arbitrum Sepolia, but we'll use nitro devnode which has a pre-funded wallet saving us the effort of wallet provisioning or running out of tokens to send transactions.

Install your devnode
git clone https://github.com/OffchainLabs/nitro-devnode.git
cd nitro-devnode

Launch your devnode

./run-dev-node.sh

Example Smart Contract

Let's look at the implementation of a decentralized cupcake vending machine using the Stylus SDK.

This example demonstrates the core functionality we'll test. We're going to test a Rust Smart Contract defining a cupcake vending machine. This vending machine will follow two rules:

The vending machine will distribute a cupcake to anyone who hasn't recently received one.
The vending machine's rules can't be changed by anyone.

Vending-machine contract

//!
//! Stylus Cupcake Example
//!
//! The contract is ABI-equivalent with Solidity, which means you can call it from both Solidity and Rust.
//! To do this, run `cargo stylus export-abi`.
//!
//! Note: this code is a template-only and has not been audited.
//!

// Allow `cargo stylus export-abi` to generate a main function if the "export-abi" feature is enabled. #![cfg_attr(not(feature = "export-abi"), no_main)]
extern crate alloc;

use alloy_primitives::{Address, Uint};
// Import items from the SDK. The prelude contains common traits and macros.
use stylus_sdk::alloy_primitives::U256;
use stylus_sdk::prelude::\*;
use stylus_sdk::{block, console};

// Define persistent storage using the Solidity ABI.
// `VendingMachine` will be the entrypoint for the contract.
sol_storage! { #[entrypoint]
pub struct VendingMachine {
// Mapping from user addresses to their cupcake balances.
mapping(address => uint256) cupcake_balances;
// Mapping from user addresses to the last time they received a cupcake.
mapping(address => uint256) cupcake_distribution_times;
}
}

// Declare that `VendingMachine` is a contract with the following external methods. #[public]
impl VendingMachine {
// Give a cupcake to the specified user if they are eligible (i.e., if at least 5 seconds have passed since their last cupcake).
pub fn give_cupcake_to(&mut self, user_address: Address) -> bool {
// Get the last distribution time for the user.
let last_distribution = self.cupcake_distribution_times.get(user_address);
// Calculate the earliest next time the user can receive a cupcake.
let five_seconds_from_last_distribution = last_distribution + U256::from(5);

        // Get the current block timestamp.
        let current_time = block::timestamp();
        // Check if the user can receive a cupcake.
        let user_can_receive_cupcake =
            five_seconds_from_last_distribution <= Uint::<256, 4>::from(current_time);

        if user_can_receive_cupcake {
            // Increment the user's cupcake balance.
            let mut balance_accessor = self.cupcake_balances.setter(user_address);
            let balance = balance_accessor.get() + U256::from(1);
            balance_accessor.set(balance);

            // Update the distribution time to the current time.
            let mut time_accessor = self.cupcake_distribution_times.setter(user_address);
            let new_distribution_time = block::timestamp();
            time_accessor.set(Uint::<256, 4>::from(new_distribution_time));
            return true;
        } else {
            // User must wait before receiving another cupcake.
            console!(
                "HTTP 429: Too Many Cupcakes (you must wait at least 5 seconds between cupcakes)"
            );
            return false;
        }
    }

    // Get the cupcake balance for the specified user.
    pub fn get_cupcake_balance_for(&self, user_address: Address) -> Uint<256, 4> {
        // Return the user's cupcake balance from storage.
        return self.cupcake_balances.get(user_address);
    }

}

Writing Tests

The Stylus SDK testing framework is available through the stylus_sdk::testing module, which is re-exported when targeting native architectures. This allows you to write and run tests using Rust's standard testing infrastructure.

Setting Up Your Test Environment

To write tests for your contract, follow these steps:

Create a test module in your contract file or in a separate file
Import the testing framework
Create a test VM environment
Initialize your contract with the test VM
Write your test assertions

Here's a complete example of how to test our NFT contract:

test file

use stylus_sdk::{alloy_primitives::Address, prelude::*};
use stylus_test::*;

use stylus_cupcake_example::*;

#[test]
fn test_give_cupcake() {
    // Setup test environment
    let vm = TestVM::default();
    let mut contract = VendingMachine::from(&vm);

    // Create a test user address
    let user = Address::from([0x1; 20]);

    // First cupcake should succeed
    assert!(contract.give_cupcake_to(user));

    // Balance should be 1
    assert_eq!(contract.get_cupcake_balance_for(user), 1.into());

    // Immediate second attempt should fail (needs 5 second wait)
    assert!(!contract.give_cupcake_to(user));

    // Balance should still be 1
    assert_eq!(contract.get_cupcake_balance_for(user), 1.into());

    // Advance block timestamp by 6 seconds
    vm.set_timestamp(6);

    // Should be able to get another cupcake now
    assert!(contract.give_cupcake_to(user));

    // Balance should be 2
    assert_eq!(contract.get_cupcake_balance_for(user), 2.into());
}

#[test]
fn test_get_cupcake_balance() {
    let vm = TestVM::default();
    let mut contract = VendingMachine::from(&vm);

    // Create a test user address
    let user = Address::from([0x2; 20]);

    // Initial balance should be 0
    assert_eq!(contract.get_cupcake_balance_for(user), 0.into());

    // Give a cupcake
    assert!(contract.give_cupcake_to(user));

    // Balance should be 1
    assert_eq!(contract.get_cupcake_balance_for(user), 1.into());
}
```rust
</CustomDetails>

<!-- ### Advanced Testing Features -->

<!-- #### Customizing the Test Environment -->

<!-- You can customize your test environment using `TestVMBuilder` for more complex scenarios: -->


#### Testing Contract Interactions

To test contract interactions, you can mock calls to other contracts:

```rust
#[test]
fn test_external_contract_interaction() {
    let vm = TestVM::default();

    // Address of an external contract
    let external_contract = Address::from([0x5; 20]);

    // Mock data and response
    let call_data = vec![/* function selector and parameters */];
    let expected_response = vec![/* expected return data */];

    // Mock the call
    vm.mock_call(external_contract, call_data.clone(), Ok(expected_response));

    // Initialize your contract
    let contract = StylusTestNFT::from(&vm);

    // Test logic that involves calling the external contract
    // ...
}

Testing Storage

The testing framework automatically handles persistent storage simulation. Storage operations in your tests will work exactly as they would on-chain, but in a controlled test environment.

#[test]
fn test_storage_persistence() {
    let vm = TestVM::default();

    // You can also set storage values directly
    let key = U256::from(1);
    let value = B256::from([0xff; 32]);
    vm.set_storage(key, value);

    // And retrieve them
    assert_eq!(vm.get_storage(key), value);
}

Best Practices

Test Organization
- Keep tests in a separate module marked with #[cfg(test)]
- Group related tests together
Test Isolation
- Create a new TestVM instance for each test
- Don't rely on state from previous tests
Comprehensive Testing
- Test happy paths and error cases
- Test edge cases and boundary conditions
- Test access control and authorization
Meaningful Assertions
- Make assertions that verify the actual behavior you care about
- Use descriptive error messages in assertions

Running Tests

Testing with cargo-stylus

When using the cargo-stylus CLI tool, you can run tests with:

cargo stylus test

You can also run specific tests by name:

cargo test test_mint

Conclusion

Testing is an essential part of smart contract development to ensure security, correctness, and reliability. The Stylus SDK provides powerful testing tools that allow you to thoroughly test your contracts before deployment.

The ability to test Rust contracts directly, without requiring a blockchain environment, makes the development cycle faster and more efficient.

Introduction​

Prerequisites​

Example Smart Contract​

Writing Tests​

Setting Up Your Test Environment​

Testing Storage​

Best Practices​

Running Tests​

Testing with cargo-stylus​

Conclusion​