Key Takeaways:
- Chialisp testing with simulators lets you validate smart contracts locally without testnet or mainnet transactions, saving time and preventing costly on-chain errors before deployment
- CLVM testing validates puzzle logic in milliseconds using run and brun commands, while blockchain simulator testing provides complete integration validation including wallet interactions and coin lifecycles
- The Chia Blockchain Simulator comes pre-funded with 21 million TXCH, eliminating the need for testnet coins while providing full blockchain functionality for comprehensive testing
- Progressive testing strategy starts with fast CLVM validation, advances to simulator integration testing, then builds automated test suites using cdv test for production-ready code
- Combining multiple testing approaches—CLVM for logic, simulator for integration, and automated frameworks for regression—ensures your Chialisp code works correctly across all scenarios
Chialisp testing with simulators gives you complete control over your development environment, letting you validate smart contract behavior without spending real XCH or waiting for testnet confirmations. Whether you’re building simple puzzles or complex DeFi protocols, mastering these testing tools separates experimental code from production-ready smart contracts that safely handle real value on the Chia blockchain.
Understanding Chialisp Testing With Simulators
Chialisp testing with simulators means validating your smart contract code in controlled environments that replicate blockchain behavior without requiring actual mainnet or testnet transactions. As of February 2026, Chia Network continues active development with recent releases focusing on improved mempool performance, preliminary PoS2 plot format support, and enhanced simulator capabilities. This approach accelerates development cycles by providing instant feedback on puzzle logic, coin spending mechanics, and wallet integration scenarios.
The Chia ecosystem provides three primary simulation levels for testing Chialisp code. CLVM-level testing validates puzzle logic using run and brun commands that compile and execute code in milliseconds. Blockchain simulator testing creates actual coins on a simulated chain, letting you test complete spend scenarios including timelocks, announcements, and multi-coin interactions. Automated test frameworks combine both approaches into comprehensive test suites that run on every code change, catching regressions before they reach production.
Why Testing Matters in Chialisp Development
Testing prevents expensive mistakes in blockchain development where bugs become permanent once transactions confirm on mainnet. Smart contracts managing custody solutions, DeFi protocols, or tokenized assets require rigorous validation to ensure they handle edge cases correctly and can’t be exploited by malicious actors. The immutable nature of blockchain transactions means you can’t simply patch bugs in production—every spend executes your puzzle’s logic exactly as written, making thorough pre-deployment testing essential.
According to Chia Network’s official developer documentation, “The simulator gives you complete control of a private Chia blockchain, including the ability to advance and revert blocks as needed.” This level of control enables testing scenarios that would be impractical or impossible on testnet, such as rapidly advancing time to test timelocks or reverting failed transactions to try alternative approaches without losing test coins.
Simulator testing also dramatically reduces development friction compared to testnet workflows. Instead of requesting testnet coins from faucets, waiting for transaction confirmations, and managing wallet synchronization, simulators provide instant funding, immediate block generation, and complete transaction visibility. This acceleration lets you iterate through test-fix-verify cycles in minutes rather than hours, maintaining development momentum throughout the smart contract creation process.
Three Types of Chialisp Simulators Explained
The Chia development ecosystem offers distinct simulation tools serving different testing needs throughout the smart contract development lifecycle. Understanding when to use each simulator type optimizes your testing workflow and catches different categories of bugs at appropriate development stages.
CLVM Testing: Pure Logic Validation
CLVM testing validates puzzle logic without blockchain context by compiling Chialisp to bytecode and executing it with test parameters. The run command compiles your Chialisp source into CLVM bytecode, while brun executes that compiled code with solution parameters you provide. This approach completes in milliseconds for simple puzzles and under a second for complex logic, making it ideal for rapid iteration during initial development.
CLVM testing catches syntax errors, logic mistakes, and condition generation problems before you create actual blockchain coins. For example, testing a password-locked coin puzzle validates that correct passwords generate proper CREATE_COIN conditions while incorrect passwords fail appropriately. However, CLVM testing can’t verify blockchain-specific behavior like coin announcements, timelock enforcement, or wallet software compatibility since these require actual blockchain state.
Blockchain Simulator Testing: Complete Integration
The Chia Blockchain Simulator provides a complete private blockchain where you can create coins, spend them with your puzzles, and verify the blockchain accepts or rejects transactions as expected. This simulator replicates full node, wallet, and farmer functionality in a controlled environment with instant block generation and the ability to advance or revert blockchain state as needed for testing.
Blockchain simulator testing validates integration scenarios that CLVM testing can’t address. You can test timelock conditions by farming blocks to advance time, verify coin announcements work correctly between related spends, confirm your puzzle generates valid spend bundles that wallets accept, and validate that complex multi-coin patterns behave correctly when multiple puzzles interact. The simulator comes pre-funded with 21 million TXCH in the prefarm, eliminating the need for testnet coin acquisition.
Automated Testing Frameworks: Continuous Validation
Automated testing frameworks like cdv test and pytest-based test suites combine CLVM and simulator testing into reproducible test batteries that run on every code change. These frameworks let you write test cases once and execute them continuously, catching regressions when you modify existing code and validating that new features don’t break existing functionality.
The cdv test command initializes a testing structure in your project directory, creating skeleton test files you expand with specific test cases for your puzzles. Tests can use the cdv.test Python package to programmatically interact with simulated coins, generate spend bundles, and assert expected outcomes. This approach scales to complex projects where manual testing becomes impractical, ensuring code quality remains high as your codebase grows.
Setting Up Your Chialisp Testing Environment
Proper environment setup prevents common installation issues and ensures all testing tools work correctly together. The setup process involves installing Python, creating isolated virtual environments, and installing the Chia development toolchain in the correct order to avoid dependency conflicts.
Installing Chia Dev Tools for CLVM Testing
Installing Chia Dev Tools requires Python 3.10 or higher (Python 3.12 recommended as of 2025) and pip package manager. Create a virtual environment before installation to avoid dependency conflicts, as mixing system-wide Python packages with Chia tools often causes version incompatibility issues. As of February 2026, the current stable version of chia-blockchain is 2.5.7, released in November 2025. The Chia Dev Tools package depends on chia-blockchain version 2.5.0 or higher.
First, verify your Python version meets requirements by running python3 –version or python –version depending on your system. Create a virtual environment in your project directory with python3 -m venv venv, then activate it with source venv/bin/activate on Linux/Mac or venv\Scripts\activate on Windows. You’ll see (venv) appear in your terminal prompt confirming activation.
Install Chia Dev Tools within the activated virtual environment using pip install chia-dev-tools. This command installs cdv along with dependencies including run and brun commands for CLVM testing. Verify successful installation by running cdv –version, which should display the installed version number. The installation provides immediate access to CLVM testing capabilities without requiring full blockchain synchronization.
Installing the Chia Blockchain Simulator
The Chia Blockchain Simulator requires installing from source rather than binary packages, as simulator functionality isn’t included in standard Chia wallet installers. Note: It’s recommended to run the simulator in a separate virtual environment as there are dependency differences between cdv and the main chia-blockchain repository. Clone the chia-blockchain repository from GitHub and follow the installation from source instructions in the official documentation.
After installing from source and activating your virtual environment, initialize the simulator with chia dev sim create. This command prompts you to either use existing keys or generate new ones, then creates the simulator directory structure in ~/.chia/simulator/main/. The initialization process generates several k-19 plots for farming test blocks and sets up the configuration files the simulator needs.
Start the simulator with chia dev sim start, which launches a full node daemon configured for simulator mode. The simulator uses different ports than mainnet and testnet (typically port 50127 for P2P and 16872 for RPC), allowing you to run it simultaneously with a synced mainnet or testnet node if desired. Verify the simulator is running with chia dev sim status, which displays network information, block height, and your pre-funded wallet balance.
Installing Additional Development Tools
The Chia VSCode Extension provides real-time diagnostics that catch errors during coding, before you even reach the testing phase. Install it from the Visual Studio Code marketplace by searching for “Chialisp” and installing the extension published by Chia Network. The extension requires a 64-bit version of any OS supported by both Chia and Visual Studio Code, including Windows, macOS, and Debian-based Linux distributions.
After installation, create a chialisp.json file in your workspace root listing directories you’ll include other files from. This configuration enables the extension to provide accurate code completion and go-to-definition functionality across your project files. The extension uses the modern Chialisp compiler from clvm_tools_rs, ensuring syntax highlighting and diagnostics match the actual compiler behavior.
CLVM Testing: Testing Puzzle Logic
CLVM testing forms the foundation of Chialisp development by validating puzzle logic before creating actual blockchain coins. This testing level catches the majority of bugs in your code logic, condition generation, and solution handling at near-instant speed, making it the first testing approach you should master.
Using Run and Brun Commands
The run command compiles Chialisp source code into CLVM bytecode, which the Chia blockchain’s virtual machine executes. Running run ‘(+ 2 3)’ returns compiled bytecode like (+ (q . 2) (q . 3)), which explicitly quotes literal values to distinguish them from environment references. This compilation step catches syntax errors and structural problems in your Chialisp code before execution.
The brun command executes compiled CLVM bytecode with solution parameters you provide. After compiling a puzzle with run, execute it with brun followed by the compiled bytecode and a quoted solution. For example, brun ‘(+ (q . 2) (q . 3))’ ‘()’ executes the addition and returns 5. When testing puzzles that require parameters, the solution is passed as a separate argument in quotes, letting you test the same compiled puzzle with multiple different solutions.
Testing Puzzle Conditions and Logic
Effective CLVM testing validates that your puzzle generates correct conditions for valid solutions and fails appropriately for invalid ones. Test both the happy path where everything works correctly and edge cases where solutions are malformed, missing required parameters, or attempting to violate puzzle constraints. For puzzles with conditional logic, test all branches to ensure each path generates expected conditions.
When testing puzzles that generate blockchain conditions like CREATE_COIN or AGG_SIG_ME, verify the condition codes and parameters match exactly what you intend. A puzzle that should create a coin for 1000 mojos should generate condition (51 puzzle_hash 1000), where 51 is the CREATE_COIN condition code. Testing these conditions with brun confirms your puzzle logic produces correct outputs before you test on a simulated blockchain.
Writing Reusable Test Scripts
As puzzles grow more complex, maintaining test commands in shell history becomes impractical. Instead, save your Chialisp source in .clsp files and create shell scripts or Python scripts that compile and test them with various solution parameters. This approach makes tests repeatable and shareable with other developers working on the same puzzles.
A simple bash script might compile a puzzle with run, capture the output, then execute multiple brun commands with different solutions to validate various scenarios. Python scripts using the subprocess module can automate this process further, parsing brun output to assert expected results and reporting which tests passed or failed. These reusable test scripts become increasingly valuable as you iterate on puzzle designs and need to verify that changes don’t break existing functionality.
Blockchain Simulator Testing
Blockchain simulator testing validates complete coin lifecycles from creation through spending, including blockchain-specific behaviors that CLVM testing can’t verify. This testing level ensures your puzzles work correctly when actual coins are created, spent, and confirmed in blocks, catching integration issues before testnet or mainnet deployment.
Creating and Funding Test Coins
The simulator automatically provides pre-funded wallet addresses when you initialize it, giving you immediate access to test XCH without requesting testnet coins. Check your wallet balance with chia wallet show to see the 21 million TXCH from the prefarm available for testing. This prefarm provides essentially unlimited test coins for development purposes.
Create test coins using standard Chia wallet commands just as you would on mainnet or testnet. Send coins to addresses derived from your puzzle hashes using chia wallet send, which creates transactions that the simulator can immediately farm into blocks. Unlike testnet where you wait for confirmation, simulator blocks can be generated instantly with chia dev sim farm, letting you create and confirm transactions in seconds rather than minutes.
Testing Coin Spending and Validation
Spending simulated coins validates that your puzzle generates spend bundles the blockchain accepts and that your solution parameters work correctly with wallet software. Use wallet commands or the cdv rpc pushtx command to submit spend bundles to the simulator, then farm blocks to confirm them. The simulator will reject invalid spends just like a real full node, letting you debug spend bundle construction before risking real coins.
Test timelock conditions by farming multiple blocks to advance the blockchain’s timestamp, then verify your time-locked coins can only be spent after the timelock expires. Test announcement assertions by creating multiple related spends that must happen simultaneously, confirming the blockchain only accepts them when all required announcements are present. These integration tests catch issues that pure logic testing misses.
Using Simulator RPC Commands
The simulator exposes RPC endpoints identical to mainnet and testnet full nodes, letting you programmatically interact with the simulated blockchain. Commands like chia rpc full_node get_blockchain_state return information about the current block height, difficulty, and sync status. The cdv rpc family of commands provides convenient wrappers for common RPC operations during testing.
Advanced simulator features include the ability to revert blocks with chia dev sim revert, which rolls back the blockchain state to a previous height while maintaining your wallet’s coins in their pre-spend state. This feature enables testing alternative spend scenarios without recreating coins from scratch. You can also control auto-farming behavior, disabling automatic block generation when you need precise control over transaction ordering and timing.
Automated Testing With CDV Test Framework
The cdv test framework provides a structured approach to writing automated tests that combine CLVM validation with blockchain simulator integration. These tests run consistently across development cycles, catching regressions when code changes and validating that new features work correctly.
Initializing Test Suites
Initialize testing infrastructure in your project with cdv test –init, which creates a tests directory containing a test_skeleton.py file demonstrating the framework structure. This skeleton shows how to import the cdv.test package, set up test fixtures that provide simulated blockchain access, and write test functions that assert expected behaviors.
The cdv.test package provides utilities for programmatically interacting with simulated coins, including functions to create coins with custom puzzles, generate solutions, construct spend bundles, and submit them to the simulated blockchain. Tests can assert that valid spends succeed, invalid spends fail with expected error messages, and that coin states change correctly after spends confirm.
Writing Effective Test Cases
Effective test cases cover both success and failure scenarios for your puzzles. Test that valid solutions produce expected results, invalid solutions fail with appropriate errors, edge cases like zero amounts or empty lists are handled correctly, and complex multi-coin scenarios work when multiple puzzles interact. Structure tests to be independent and repeatable, avoiding dependencies between test cases that make failures difficult to debug.
Use descriptive test function names that clearly indicate what scenario is being tested. A test named test_password_puzzle_accepts_correct_password immediately communicates its purpose, while test_1 provides no context when it fails. Include assertion messages that explain what went wrong when tests fail, helping you quickly identify the problem without re-reading the entire test code.
Running and Debugging Tests
Run your test suite with cdv test from your project root directory. The framework executes all test functions, reporting which passed and which failed along with assertion error messages. Failed tests include stack traces showing exactly where the failure occurred, helping you quickly locate the problematic code.
When tests fail, use Python’s built-in debugging tools to step through test execution and inspect variables at each stage. The pdb debugger lets you set breakpoints in test code, examine coin states, and verify that intermediate values match expectations. This debugging capability makes automated tests valuable not just for catching regressions, but for understanding complex puzzle behaviors during initial development.
Choosing the Right Testing Approach: A Practical Decision Guide
Choosing the right testing approach depends on your development stage and what specific behavior you need to verify. Early development benefits from fast CLVM testing cycles, mid-development requires simulator validation, and production readiness demands comprehensive automated testing across all scenarios.
Progressive Testing Strategy
Start every puzzle with CLVM testing to validate core logic and conditions. Once basic functionality works, move to blockchain simulator testing to verify coin mechanics and wallet interactions. Finally, build automated test suites that combine both approaches into comprehensive validation that runs on every code change. This progressive strategy catches bugs early when they’re cheapest to fix while ensuring production code meets quality standards.
For simple puzzles with straightforward logic, CLVM testing might suffice throughout development. Complex custody solutions, singleton state machines, or DeFi protocols require all three testing levels to adequately validate behavior across edge cases and integration scenarios.
Common Testing Workflows and Best Practices
Successful Chialisp testing follows established workflows that balance speed with thoroughness. The standard progression moves from compilation through unit testing to integration validation, with each stage catching different categories of issues.
Standard Testing Workflow
Begin by compiling your Chialisp puzzle with the run command, which converts human-readable Chialisp into executable CLVM bytecode. This compilation step catches syntax errors and basic structural issues immediately. Next, execute unit tests using brun with various solution parameters to verify your puzzle logic handles expected inputs correctly and rejects invalid ones appropriately.
After confirming logic correctness through CLVM testing, advance to simulator testing where you create actual coins, spend them with your puzzle, and verify the blockchain accepts or rejects transactions as expected. Test timelock conditions by advancing simulator blocks, verify coin announcements work correctly, and confirm wallet software can interact with your puzzle as intended.
Catching Edge Cases Early
Edge case testing separates production-ready code from untested prototypes. Test boundary conditions like zero amounts, maximum values, empty lists, and unexpected data types in your solutions. Verify your puzzle handles malformed solutions gracefully rather than creating exploitable conditions. Test all failure paths to confirm your puzzle rejects invalid spends for the right reasons.
Combined with systematic testing across all three simulation levels, this tooling significantly reduces bugs that reach production.
Preparing for Lesson 15: Upgradability Patterns
Comprehensive testing becomes even more critical when developing upgradable puzzles, which Lesson 15 will cover in detail. Upgradable patterns add complexity that requires extensive validation to ensure upgrade mechanisms work correctly and can’t be exploited. The testing foundations you build now will prove essential for validating upgradable smart contract behavior in the next lesson.
Conclusion
Mastering chialisp testing with simulators gives you confidence that your smart contracts work correctly before deployment to mainnet. By combining fast CLVM testing for logic validation with comprehensive blockchain simulation for integration testing, you catch bugs early and avoid costly on-chain mistakes. Whether you’re testing simple puzzles or complex DeFi protocols, choosing the right simulation tool for your development stage accelerates your workflow while maintaining code quality. Start with CLVM testing for rapid iteration, advance to simulator testing for real-world validation, and build automated test suites to maintain quality as your codebase grows.
Chialisp Testing With Simulators FAQs
What is chialisp testing with simulators?
Chialisp testing with simulators is the process of validating your smart contract code using controlled environments that mimic blockchain behavior without requiring actual mainnet or testnet transactions. Simulators range from simple CLVM executors that test puzzle logic to complete blockchain simulators that replicate coin creation, spending, and confirmation.
How do I test chialisp code with simulators?
Test chialisp code with simulators by first installing Chia Dev Tools, then using run to compile your puzzle and brun to execute it with test solutions. For integration testing, initialize the Chia Blockchain Simulator with chia dev sim create and chia dev sim start to test complete coin lifecycles and wallet interactions.
What’s the difference between CLVM testing and blockchain simulator testing?
CLVM testing validates puzzle logic in isolation by executing compiled Chialisp with test parameters and checking the resulting conditions, completing in milliseconds for simple puzzles and under a second for complex logic. Blockchain simulator testing creates actual coins on a simulated blockchain and validates complete spend scenarios including wallet interactions, timelocks, and multi-coin patterns, taking seconds per test but providing comprehensive integration validation.
Do I need a testnet wallet to test chialisp with simulators?
No, you don’t need a testnet wallet to test chialisp with simulators. The Chia Blockchain Simulator provides pre-funded wallet addresses automatically with 21 million TXCH from the prefarm and lets you test all wallet functionality locally, eliminating the need for testnet coins, transaction confirmations, or external blockchain dependencies.
What are the best tools for chialisp testing with simulators?
The best tools for chialisp testing with simulators include Chia Dev Tools for CLVM-level testing with run and brun commands, the Chia Blockchain Simulator for full integration testing, the cdv test suite for automated framework-based testing, and the Chia VSCode Extension for real-time diagnostics during development.
Chialisp Testing With Simulators Citations
- Chia Network Documentation – Simulator User Guide: https://docs.chia.net/guides/simulator-user-guide/
- Chialisp.com – Coin Lifecycle Introduction: https://chialisp.com/docs/coin_lifecycle/
- Chia Dev Tools GitHub Repository: https://github.com/Chia-Network/chia-dev-tools
- Chia Blockchain GitHub Repository: https://github.com/Chia-Network/chia-blockchain
- Chia VSCode Chialisp LSP – GitHub Repository: https://github.com/Chia-Network/vscode-chialisp-lsp
- Chia Documentation – Simulator CLI Reference: https://docs.chia.net/simulator-cli/
- Chia Documentation – Simulator RPC Reference: https://docs.chia.net/simulator-rpc/
- Chia Network Documentation – Intro to Chialisp: https://docs.chia.net/guides/crash-course/intro-to-chialisp/
