LiteSVM Docs

Getting Started

Install LiteSVM and write your first tests.

Quick Start Guide

This guide covers the basics: how to create an account, fund an account, and send a transaction.

Install Dependencies

Add LiteSVM to your dev dependencies:

cargo add --dev litesvm

Several Solana crates enhance the testing experience by providing essential types and utilities, in this case, we will need solana-sdk.

cargo add --dev solana-sdk
pnpm add @solana/kit @solana/kit-plugins @solana-program/system
npm install @solana/kit @solana/kit-plugins @solana-program/system
yarn add @solana/kit @solana/kit-plugins @solana-program/system
bun add @solana/kit @solana/kit-plugins @solana-program/system

Create Test File

Inside your workspace, create a folder for tests.

mkdir tests

Create a new TypeScript file for your test.

touch basic-test.ts

Create and Fund an Account

Let's write your first LiteSVM test.

Inside your tests folder, create a new file and copy this code:

tests/create_account.rs
use litesvm::LiteSVM;
use solana_sdk::signature::{Keypair, Signer};

#[test]
fn create_account() {
    // Create the test environment
    let mut svm = LiteSVM::new();

    // Create a test account
    let user = Keypair::new();

    // Fund the account with SOL
    svm.airdrop(&user.pubkey(), 1_000_000_000).unwrap();

    // Check the balance
    let balance = svm.get_balance(&user.pubkey()).unwrap();
    assert_eq!(balance, 1_000_000_000);

    println!("Account funded with {} SOL", balance as f64 / 1e9);
}

Copy this code into your test file:

basic-test.ts
import { createEmptyClient, lamports } from '@solana/kit';
import { litesvm, payer } from '@solana/kit-plugins';

// Create a client with LiteSVM and your payer
const client = createEmptyClient()
    .use(litesvm())
    .use(payer(mySigner));

// Fund the account with SOL
client.svm.airdrop(client.payer.address, lamports(5_000_000_000n));

// Check the balance
const balance = client.svm.getBalance(client.payer.address);
console.log('Balance:', balance, 'lamports');

Run Your Test

cargo test create_account -- --show-output

You should see:

running 1 test
test create_account ... ok

successes:

---- create_account stdout ----
Account funded with 1 SOL


successes:
    create_account
npx tsx basic-test.ts

You should see:

Balance: 5000000000n lamports

That's it! You just made your first litesvm test, that covers creating an account and funding it.

Execute a Transaction

Now let's create a transfer transaction.

Create a new test file and copy this code:

tests/transfer_test.rs
use litesvm::LiteSVM;
use solana_sdk::{
    signature::{Keypair, Signer},
    system_instruction,
    transaction::Transaction,
};

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

    // Create two accounts
    let alice = Keypair::new();
    let bob = Keypair::new();

    // Fund Alice
    svm.airdrop(&alice.pubkey(), 2_000_000_000).unwrap();

    // Create transfer instruction
    let transfer = system_instruction::transfer(
        &alice.pubkey(),
        &bob.pubkey(),
        1_000_000_000, // 1 SOL
    );

    // Build and sign transaction
    let tx = Transaction::new_signed_with_payer(
        &[transfer],
        Some(&alice.pubkey()),
        &[&alice],
        svm.latest_blockhash(),
    );

    // Send it (execution happens immediately)
    svm.send_transaction(tx).unwrap();

    // Check new balances
    assert_eq!(svm.get_balance(&bob.pubkey()).unwrap(), 1_000_000_000);
    assert!(svm.get_balance(&alice.pubkey()).unwrap() < 1_000_000_000);

    println!("Transfer successful!");
}

Create a new file and copy this code:

transfer-test.ts
import {
    appendTransactionMessageInstruction,
    createEmptyClient,
    createTransactionMessage,
    lamports,
    pipe,
    setTransactionMessageFeePayerSigner,
    setTransactionMessageLifetimeUsingBlockhash,
    signTransactionMessageWithSigners,
} from '@solana/kit';
import { litesvm, payer } from '@solana/kit-plugins';
import { getTransferSolInstruction } from '@solana-program/system';

// Create client with LiteSVM and payer
const client = createEmptyClient()
    .use(litesvm())
    .use(payer(mySigner));

// Fund the payer
client.svm.airdrop(client.payer.address, lamports(2_000_000_000n));

// Build the transfer instruction
const transferIx = getTransferSolInstruction({
    source: client.payer,
    destination: recipientAddress,
    amount: lamports(1_000_000_000n), // 1 SOL
});

// Build the transaction message
const transactionMessage = pipe(
    createTransactionMessage({ version: 0 }),
    tx => setTransactionMessageFeePayerSigner(client.payer, tx),
    tx => setTransactionMessageLifetimeUsingBlockhash(
        client.svm.latestBlockhashLifetime(),
        tx
    ),
    tx => appendTransactionMessageInstruction(transferIx, tx),
);

// Sign and send the transaction
const signedTx = await signTransactionMessageWithSigners(transactionMessage);
client.svm.sendTransaction(signedTx);

// Check new balances
const recipientBalance = client.svm.getBalance(recipientAddress) ?? 0n;
console.log('Recipient balance:', Number(recipientBalance) / 1e9, 'SOL');
console.log('Transfer successful!');

Test complete! This test covers executing the transfer instruction from the system program.

Run All Tests

cargo test -- --show-output

You should see:

running 1 test
test create_account ... ok

successes:

---- create_account stdout ----
Account funded with 1 SOL


successes:
    create_account

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.04s

     Running tests/test_transfer.rs (target/debug/deps/test_transfer-f174954e7483f36b)

running 1 test
test test_transfer ... ok

successes:

---- test_transfer stdout ----
Transfer successful!


successes:
    test_transfer

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.04s
npx tsx basic-test.ts && npx tsx transfer-test.ts

You should see:

Balance: 5000000000n lamports
Recipient balance: 1 SOL
Transfer successful!

That's it! Now you've successfully made litesvm tests that create and fund accounts and execute transactions.

Next Steps

Why LiteSVM → Learn why you would want to use LiteSVM for testing

Why LiteSVM

Understand how LiteSVM works and why it's different