anza-xyz/mollusk

What it solves

Developing and testing Solana programs normally requires either spinning up a full validator runtime or dealing with heavyweight components like AccountsDB and Bank. Mollusk eliminates that friction by providing a small, fast test environment that executes a Solana program's compiled ELF file directly through a minified Solana Virtual Machine (SVM). It skips the large validator machinery entirely, which makes tests run exceptionally quickly.

Because it has no place to look up accounts from a blockchain database, the user must hand it an explicit list of accounts for each test. That trade-off is what keeps the harness fast and predictable.

How it works

Mollusk builds its test environment from low-level SVM components rather than simulating a validator runtime. Its main processor, process_instruction, creates compact versions of Agave's program cache, transaction context, and invoke context, then uses those to run the program's ELF through the BPF Loader.

Key execution paths:

• Single instructions — process_instruction runs one instruction; process_and_validate_instruction runs one instruction and then applies a set of checks (via the Check enum) on the result, such as asserting success, verifying compute unit usage, or checking that specific accounts have expected lamport balances.
• Instruction chains — process_instruction_chain and process_and_validate_instruction_chain run a sequence of instructions in order. These are explicitly not equivalent to Solana transactions — Mollusk imposes no transaction-like constraints on chains (no loaded-account-key limits, no size checks) — they are purely for testing program execution flow.
• Account setup helpers — The mollusk-svm-account crate provides builders for common account types (System, Mint, TokenAccount, Stake), automatically resolving rent-exempt minimums based on account data length. For custom program state, developers can implement the AccountState trait to serialize their data and let the harness size and fund the account automatically.
• Stateful testing — MolluskContext wraps Mollusk in a stateful container that manages an account store, so developers can run multiple instructions without manually passing account lists each time. It works with any implementation of the AccountStore trait; a simple HashMap<Pubkey, Account> works out of the box.
• Compute unit benchmarking — The MolluskComputeUnitBencher measures how many compute units a program consumes per benchmark case, records deltas between runs, and writes a markdown report. A matrix variant (MolluskComputeUnitMatrixBencher) compares multiple program versions side-by-side in a table.
• Fixtures — When the fuzz or fuzz-fd feature flags are enabled, Mollusk can generate structured test fixtures from any test run by setting the EJECT_FUZZ_FIXTURES environment variable. Each fixture represents one instruction with its inputs, configuration, and expected result. Fixtures can be replayed against a different version of the program — a classic use case is testing a new program version against fixtures generated from the old version's test suite. Two fixture layouts are supported: Mollusk's own layout and the Firedancer team's layout, both based on Protobuf definitions.

Who it's for

Solana program developers who need fast, focused unit or integration tests without standing up a full validator. Also useful for developers who want to benchmark compute unit usage across program versions, or who want to reuse an existing test suite's scenarios as fixtures to validate a rewritten or upgraded program.

Highlights

• Exceptionally fast test harness — skips large Agave components like AccountsDB and Bank entirely
• Direct execution of the program's ELF via the BPF Loader
• Simple single-instruction and instruction-chain APIs with built-in result validation via the Check enum
• Account builders that handle rent-exempt minimums automatically
• Stateful testing via MolluskContext with pluggable account store implementations
• Compute unit benchmarking with markdown reports and delta tracking across runs
• Fixture generation and replay for testing different program versions against the same scenarios