Quick Start

View litesvm-utils on crates.io

Installation

Make sure you have all the needed dependencies:

cargo add --dev litesvm litesvm-utils

The litesvm-utils crate provides essential helper traits and utilities that simplify Solana program testing. It reduces common testing boilerplate from 30+ lines to minimal, readable code through ergonomic APIs.

TestHelpers Trait

Create funded accounts with a single method call
Set up token mints and token accounts easily
Derive PDAs without boilerplate
Manage slots for time-based testing

AssertionHelpers Trait

Assert account states (exists, closed, owner)
Verify token balances and mint supplies
Check SOL balances
Validate account data lengths

TransactionHelpers Trait

Execute instructions with rich result handling
Assert transaction success or failure
Check for specific error codes
Inspect transaction logs and compute units

LiteSVMBuilder

Fluent builder pattern for test environment setup
Deploy programs with method chaining
Convenient static factory methods

Quick Example

Here's a complete example showing the power of litesvm-utils:

use litesvm_utils::{AssertionHelpers, LiteSVM, Signer, TestHelpers, TransactionHelpers};
use solana_sdk::{native_token::LAMPORTS_PER_SOL, system_instruction};

#[test]
fn test_with_utils() {
    let mut svm = LiteSVM::new();

    // Create funded accounts in one line
    let alice = svm.create_funded_account(10 * LAMPORTS_PER_SOL).unwrap();
    let bob = svm.create_funded_account(0).unwrap();

    // Create a token mint easily
    let mint = svm.create_token_mint(&alice, 9).unwrap();

    // Create associated token accounts (returns Pubkey)
    let alice_ata = svm.create_associated_token_account(&mint.pubkey(), &alice).unwrap();
    let bob_ata = svm.create_associated_token_account(&mint.pubkey(), &bob).unwrap();

    // Mint tokens
    svm.mint_to(&mint.pubkey(), &alice_ata, &alice, 1000).unwrap();

    // Assert balances
    svm.assert_token_balance(&alice_ata, 1000);
    svm.assert_token_balance(&bob_ata, 0);

    // Execute a SOL transfer with rich result handling
    let transfer_ix = system_instruction::transfer(
        &alice.pubkey(),
        &bob.pubkey(),
        LAMPORTS_PER_SOL,
    );

    let result = svm.send_instruction(transfer_ix, &[&alice]).unwrap();
    result.assert_success();

    // Verify the transfer
    svm.assert_sol_balance(&bob.pubkey(), LAMPORTS_PER_SOL);
}

Key Benefits

Before litesvm-utils

// Creating a funded account manually
let keypair = Keypair::new();
let airdrop_tx = Transaction::new_signed_with_payer(
    &[system_instruction::transfer(
        &payer.pubkey(),
        &keypair.pubkey(),
        lamports,
    )],
    Some(&payer.pubkey()),
    &[&payer],
    svm.latest_blockhash(),
);
svm.send_transaction(airdrop_tx).unwrap();

After litesvm-utils

// One line to create a funded account
let keypair = svm.create_funded_account(lamports).unwrap();

Trait Overview

TestHelpers

Method	Returns	Description
`create_funded_account(lamports)`	`Result<Keypair>`	Creates a keypair and funds it
`create_funded_accounts(count, lamports)`	`Result<Vec<Keypair>>`	Creates multiple funded keypairs
`create_token_mint(authority, decimals)`	`Result<Keypair>`	Creates an SPL token mint
`create_token_account(mint, owner)`	`Result<Keypair>`	Creates a regular token account
`create_associated_token_account(mint, owner)`	`Result<Pubkey>`	Creates an ATA, returns its address
`mint_to(mint, account, authority, amount)`	`Result<()>`	Mints tokens to an account
`derive_pda(seeds, program_id)`	`(Pubkey, u8)`	Derives a PDA with bump seed
`get_pda(seeds, program_id)`	`Pubkey`	Gets just the PDA address
`get_pda_with_bump(seeds, program_id)`	`(Pubkey, u8)`	Alias for `derive_pda`
`get_current_slot()`	`u64`	Returns current slot
`advance_slot(slots)`	`()`	Advances time by N slots

AssertionHelpers

Method	Description
`assert_account_exists(pubkey)`	Panics if account does not exist
`assert_account_closed(pubkey)`	Panics if account exists and has data/lamports
`assert_token_balance(account, amount)`	Verifies token balance
`assert_sol_balance(pubkey, lamports)`	Verifies SOL balance
`assert_mint_supply(mint, supply)`	Verifies mint total supply
`assert_account_owner(pubkey, owner)`	Verifies account owner
`assert_account_data_len(pubkey, len)`	Verifies data length

TransactionHelpers

Method	Returns	Description
`send_instruction(ix, signers)`	`Result<TransactionResult, TransactionError>`	Sends a single instruction
`send_instructions(ixs, signers)`	`Result<TransactionResult, TransactionError>`	Sends multiple instructions in one tx
`send_transaction_result(tx)`	`Result<TransactionResult, TransactionError>`	Sends a raw `Transaction`

Troubleshooting

Common Errors

Error	Cause	Solution
`AccountNotFound`	Trying to use an account that doesn't exist	Use `create_funded_account` first
`InsufficientFunds`	Not enough lamports for transaction	Increase initial funding amount
`OwnerMismatch`	Account owned by wrong program	Verify correct program ID
`AssertionFailed`	Balance or state doesn't match expected	Check your test logic