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