litesvm-utils

Framework-agnostic testing utilities for LiteSVM - One-line token operations, assertions, and account management for any Solana program.

Overview

litesvm-utils provides ergonomic testing utilities that work with any Solana program - Native, Anchor, SPL, or custom frameworks. It eliminates boilerplate by providing one-line helpers for common testing operations.

Use this crate if you're testing:

• Native Solana programs
• SPL programs
• Non-Anchor custom frameworks
• Or if you need just testing utilities without Anchor-specific features

Note: If you're testing Anchor programs, consider using anchor-litesvm instead, which builds on this crate and adds Anchor-specific features.

Installation

[dev-dependencies]
litesvm-utils = "0.3"

Quick Start

use litesvm_utils::{LiteSVMBuilder, TestHelpers, AssertionHelpers, TransactionHelpers};
use solana_sdk::signature::Signer;

#[test]
fn test_my_program() {
    // 1. Setup with your program
    let mut svm = LiteSVMBuilder::build_with_program(program_id, &program_bytes);

    // 2. Create test accounts (one line each!)
    let payer = svm.create_funded_account(10_000_000_000).unwrap();

    // 3. Token operations (one line each!)
    let mint = svm.create_token_mint(&payer, 9).unwrap();
    let token_account = svm.create_associated_token_account(&mint.pubkey(), &payer).unwrap();
    svm.mint_to(&mint.pubkey(), &token_account, &payer, 1_000_000).unwrap();

    // 4. Execute your instruction
    let ix = your_program_instruction(...);
    let result = svm.send_instruction(ix, &[&payer]).unwrap();

    // 5. Rich result analysis
    result.assert_success();
    assert!(result.compute_units() < 200_000);
    assert!(result.has_log("Success"));

    // 6. State assertions
    svm.assert_token_balance(&token_account, 1_000_000);
    svm.assert_account_exists(&some_pda);
}

Features

Test Account Helpers

// Create funded accounts
let user = svm.create_funded_account(10_000_000_000)?;
let accounts = svm.create_funded_accounts(5, 1_000_000_000)?;

Token Operations

// Create mint and token accounts
let mint = svm.create_token_mint(&authority, 9)?;
let token_account = svm.create_token_account(&mint.pubkey(), &owner)?;
let ata = svm.create_associated_token_account(&mint.pubkey(), &owner)?;

// Mint tokens
svm.mint_to(&mint.pubkey(), &token_account, &authority, 1_000_000)?;

Transaction Helpers

// Send single instruction
let result = svm.send_instruction(ix, &[&signer])?;

// Send multiple instructions
let result = svm.send_instructions(&[ix1, ix2], &[&signer])?;

// Analyze results
result.assert_success();
result.assert_failure();
result.assert_error("InsufficientFunds");

// Debug
result.print_logs();
let cu = result.compute_units();
let logs = result.logs();

Assertions

// Account existence
svm.assert_account_exists(&pubkey);
svm.assert_account_closed(&pubkey);

// Ownership and data
svm.assert_account_owner(&account, &program_id);
svm.assert_account_data_len(&account, 165);

// Balances
svm.assert_token_balance(&token_account, 1_000_000);
svm.assert_sol_balance(&account, 10_000_000_000);
svm.assert_mint_supply(&mint, 1_000_000);

PDA Utilities

// Get PDA
let pda = svm.get_pda(&[b"seed", user.as_ref()], &program_id);

// Get PDA with bump
let (pda, bump) = svm.get_pda_with_bump(&[b"seed"], &program_id);

// Derive (alias)
let pda = svm.derive_pda(&[b"seed"], &program_id);

Clock Manipulation

// Get current slot
let slot = svm.get_current_slot();

// Advance time
svm.advance_slot(100);

API Reference

Traits

Builder

// New empty SVM
let svm = LiteSVMBuilder::new().build();

// With single program
let svm = LiteSVMBuilder::build_with_program(program_id, &bytes);

// With multiple programs
let svm = LiteSVMBuilder::build_with_programs(&[
    (program1_id, &program1_bytes),
    (program2_id, &program2_bytes),
]);

// Chained building
let svm = LiteSVMBuilder::new()
    .deploy_program(program_id, &bytes)
    .build();

Testing

This crate has comprehensive test coverage:

cargo test -p litesvm-utils    # 52 tests

Related Crates

• anchor-litesvm - Anchor-specific testing (builds on this crate)
• litesvm - The underlying fast Solana VM

License

MIT License - see LICENSE for details.