Crate litesvm_testing

LiteSVM Testing Utilities

Copyright (C) 2024 LiteSVM Testing Framework Contributors - Licensed under GPL v3.0-or-later

A comprehensive testing framework for Solana programs using LiteSVM. Provides ergonomic, type-safe assertions for transaction results, logs, and all levels of Solana errors.

Core Features

• 📋 Log Assertions: Verify program logs contain expected content
• 🎯 Error Testing: Complete coverage of transaction, instruction, and system errors
• 🔧 Dual API Styles: Direct function calls and fluent method chaining
• ⚡ Precision Control: “Anywhere” matching vs surgical instruction-index targeting
• 🛡️ Type Safety: Work with SystemError enums instead of raw error codes
• 📚 Educational Examples: Learn API progression from verbose to elegant

API Styles

Direct Functions (traditional):

demand_logs_contain("Hello!", result);
demand_system_error(SystemError::ResultWithNegativeLamports, result);

Fluent Methods (chainable):

result.demand_logs_contain("Hello!")
      .demand_system_error(SystemError::ResultWithNegativeLamports);

Error Testing Hierarchy

🏗️ Transaction Level: Validation errors before execution

• demand_transaction_error(TransactionError::AlreadyProcessed, result)

📍 Instruction Level: Errors during instruction execution

• demand_instruction_error(InstructionError::Custom(1), result)
• demand_instruction_error_at_index(1, InstructionError::Custom(1), result)

⚙️ System Level: Type-safe system program errors

• demand_system_error(SystemError::ResultWithNegativeLamports, result) (anywhere)
• demand_system_error_at_index(1, SystemError::ResultWithNegativeLamports, result) (surgical)

Complete Examples

API Progression Tutorial:

• test_system_error_insufficient_funds.rs - Shows Good → Better → Best → Best+ approaches

Framework Integration:

• Anchor: examples/anchor/simple-anchor-tests/ - Complete Anchor program testing with IDL integration
• Pinocchio: examples/pinocchio/simple-pinocchio-tests/ - Lightweight testing with minimal boilerplate

Modules

prelude

Convenient re-exports for LiteSVM testing.

Traits

DemandFluency

Trait for fluent assertions on transaction results.

Functions

demand_instruction_error

Asserts that a transaction fails with a specific instruction error, regardless of index.

demand_instruction_error_at_index

Asserts that a specific instruction fails with a specific error.

demand_logs_contain

Asserts that a transaction’s logs contain a specific string.

demand_logs_contain_at_index

Asserts that a specific log entry contains an expected string.

demand_system_error

Asserts that a system error occurs, regardless of which instruction index produced it.

demand_system_error_at_index

Asserts that a system error occurs at a specific instruction index.

demand_transaction_error

Asserts that a transaction error matches the expected error.

setup_svm_and_fee_payer

Sets up a fresh LiteSVM instance with a funded fee payer account.