LiteSVM Documentation

Choosing between LiteSVM and the standard solana-test-validator depends on your testing requirements:

Use LiteSVM when: You want to test program logic, client code, or complex state transitions quickly. Use solana-test-validator when: You need to call specific RPC methods not supported by LiteSVM or need to test behavior that depends on actual validator mechanics.

The litesvm-utils crate provides three ergonomic traits to extend LiteSVM:

• TestHelpers: Create funded accounts, token mints, ATAs, derive PDAs, and manipulate slots.
• AssertionHelpers: One-liner assertions for account existence, ownership, SOL/token balances, and data length.
• TransactionHelpers: Execute instructions and assert success/failure/error codes.

It also includes a LiteSVMBuilder for fluent environment setup.

cargo add --dev litesvm-utils

You can bring real-world state into your LiteSVM tests using two methods:

1. Manual CLI method: Use solana account <ACCOUNT_PUBKEY> --output-file <FILE_PATH> from the Solana CLI to save account data to a file, then load it into LiteSVM.
2. Programmatic method: Use the Solana web3.js library to fetch account data from devnet/mainnet and pass that data directly into LiteSVM.

The anchor-litesvm crate allows testing Anchor programs with syntax mirroring anchor-client but without RPC overhead. Key features include:

• AnchorContext: Manages the LiteSVM instance, payer, and program. Use AnchorLiteSVM::build_with_program() for setup.
• Program builder: Type-safe instruction building via accounts(), args(), and instruction() using types from declare_program!.
• Account deserialization: Automatically handles Anchor accounts and PDAs, including discriminators.
• Event parsing: Extracts and deserializes typed events from transaction logs.

cargo add --dev anchor-litesvm

LiteSVM allows you to control the Clock sysvar to test time-dependent logic (e.g., minting schedules or expiration dates).

• Use svm.setClock() to dynamically overwrite the Clock sysvar (e.g., setting a specific unix_timestamp).
• Use svm.warpToSlot() to jump the SVM state forward to a future slot.

To use the LiteSVM NodeJS wrapper in your project, install the litesvm package using yarn.

yarn add litesvm

The litesvm-loader crate provides helpers for working with Solana's upgradeable BPF loader, handling the deployment flow (buffer account creation, chunked writing, and deployment) and changing the upgrade authority.

cargo add --dev litesvm-loader

To test your own Solana programs in LiteSVM, you can load a compiled program into the SVM instance using the addProgramFromFile method.

If you need to pull an existing program from mainnet or devnet first, use the Solana CLI command: solana program dump <PROGRAM_ID> <FILE_PATH>.

// Example usage (referencing the splLogging test pattern)
// svm.addProgramFromFile(path_to_compiled_program_file);

The litesvm-token crate provides a builder-style API for testing SPL Token programs, including operations like CreateMint, CreateAssociatedTokenAccount, MintTo, Transfer, Burn, Approve, and authority management (SetAuthority, FreezeAccount, ThawAccount).

cargo add --dev litesvm-token

To use LiteSVM in your Rust development environment, add it as a development dependency using cargo:

cargo add --dev litesvm

The litesvm-token crate provides high-level utilities for interacting with SPL Token and Token-2022 programs within a LiteSVM environment. It re-exports standard SPL Token operations such as create_mint, mint_to, transfer, burn, and create_ata.

Depending on the enabled features, it uses either the spl_token_interface or spl_token_2022_interface.