{"id":8141,"library":"eth-tester","title":"Ethereum Tester","description":"eth-tester is a suite of tools for testing Ethereum applications, providing a clean, consistent API for interacting with various Ethereum backends (e.g., PyEVM, Ganache). It allows developers to simulate blockchain interactions, deploy contracts, and execute transactions in a controlled environment. The current version, 0.13.0b1, is a beta release, indicating active development. Its release cadence is often tied to releases of its core dependencies like PyEVM or major versions of Web3.py.","status":"active","version":"0.13.0b1","language":"en","source_language":"en","source_url":"https://github.com/ethereum/eth-tester","tags":["ethereum","blockchain","testing","web3","py-evm","smart-contracts","dev-tools"],"install":[{"cmd":"pip install eth-tester","lang":"bash","label":"Install core library"},{"cmd":"pip install eth-tester[py-evm]","lang":"bash","label":"Install with PyEVM backend (recommended)"}],"dependencies":[{"reason":"Provides the PyEVM backend, which is commonly used for local EVM simulation. `eth-tester` requires a backend to function beyond basic mocking.","package":"py-evm","optional":true},{"reason":"Utility functions for Ethereum, often used in conjunction with eth-tester for data encoding/decoding.","package":"eth-utils","optional":false}],"imports":[{"symbol":"EthereumTester","correct":"from eth_tester import EthereumTester"},{"symbol":"MockBackend","correct":"from eth_tester import MockBackend"},{"note":"PyEVMBackend is in a sub-module and requires the 'py-evm' extra to be installed.","wrong":"from eth_tester import PyEVMBackend","symbol":"PyEVMBackend","correct":"from eth_tester.backends.pyevm import PyEVMBackend"},{"note":"GanacheBackend is provided by the separate 'eth-tester-ganache' library.","wrong":"from eth_tester.backends.ganache import GanacheBackend","symbol":"GanacheBackend","correct":"from eth_tester_ganache import GanacheBackend"}],"quickstart":{"code":"from eth_tester import EthereumTester, MockBackend\nfrom eth_utils import encode_hex, decode_hex\n\n# 1. Initialize the EthereumTester with a MockBackend\n# The MockBackend is a simple in-memory backend provided by eth-tester.\n# It simulates basic blockchain interactions for testing purposes.\n# For a full EVM, install with 'pip install eth-tester[py-evm]' and use PyEVMBackend.\ntester = EthereumTester(backend=MockBackend())\n\nprint(\"EthereumTester initialized with MockBackend.\")\n\n# 2. Get available accounts\naccounts = tester.get_accounts()\nprint(f\"Available accounts: {[encode_hex(acc) for acc in accounts]}\")\n\n# 3. Mine a block\n# Many operations, especially transactions, only take effect after a block is mined.\ntester.mine_block()\nprint(f\"Block mined. Current block number: {tester.get_block_by_number('latest')['number']}\")\n\n# 4. Get an account's balance\n# In MockBackend, accounts start with a default balance.\naccount_0_address = accounts[0]\nbalance = tester.get_balance(account_0_address)\nprint(f\"Balance of {encode_hex(account_0_address)}: {balance} wei\")\n\n# 5. Send a simple 'transaction' (e.g., a call) which is processed after mining.\n# Note: MockBackend does not simulate value transfer or EVM state changes without a full EVM backend.\n# This example primarily demonstrates the API for sending a transaction.\ntransaction_hash = tester.send_transaction({\n    'from': account_0_address,\n    'to': accounts[1], # Sending to another account (conceptual in MockBackend)\n    'gas_price': 0,\n    'gas': 21000,\n    'value': 0,\n    'data': b''\n})\nprint(f\"Transaction sent (hash: {encode_hex(transaction_hash)})\")\n\n# Mine another block for the transaction to be included\ntester.mine_block()\nprint(f\"Block mined. Current block number: {tester.get_block_by_number('latest')['number']}\")","lang":"python","description":"This quickstart demonstrates how to initialize `EthereumTester` with the built-in `MockBackend`, retrieve accounts, mine blocks, check balances, and send a basic transaction. For full EVM functionality (e.g., real value transfers, contract deployment), a backend like `PyEVMBackend` is required."},"warnings":[{"fix":"Always pin `eth-tester` to a specific version (e.g., `eth-tester==0.13.0b1`) in your `requirements.txt` to prevent unexpected breaking changes during upgrades.","message":"Version 0.13.0b1 is a beta release. API stability is not guaranteed, and breaking changes may occur in subsequent beta or stable releases before 1.0.","severity":"breaking","affected_versions":"0.13.0b1 and potentially later 0.x.x beta versions"},{"fix":"Install `eth-tester` with the desired backend extra (e.g., `pip install eth-tester[py-evm]`) and explicitly instantiate that backend (`PyEVMBackend()`) when creating `EthereumTester`.","message":"`eth-tester` itself is an abstraction layer; it requires a specific backend (like `PyEVMBackend` or `GanacheBackend`) to simulate a full EVM. Without a proper backend, functionality is limited (e.g., MockBackend doesn't execute EVM opcodes).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `tester.mine_block()` is called after sending transactions or making changes that require block inclusion. For convenience in tests, consider using `tester.auto_mine_transactions = True`.","message":"Transactions and many state changes within `eth-tester` (especially with `PyEVMBackend`) only take effect after a block has been mined. Forgetting to call `tester.mine_block()` can lead to unexpected state.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When integrating with `web3.py`, initialize it as `w3 = Web3(Web3.EthereumTesterProvider(tester))` and then use `w3` for all `web3.py` interactions. Do not mix `tester` and `w3` APIs directly.","message":"While `eth-tester` provides an API, its most common and powerful use case is as the underlying provider for `web3.py`'s `Web3.EthereumTesterProvider`. Attempting to use `web3.py` methods directly on an `EthereumTester` instance will fail.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install `eth-tester` with the `py-evm` extra: `pip install eth-tester[py-evm]`.","cause":"The `PyEVMBackend` was imported, but the `py-evm` dependency (and its corresponding extra) was not installed.","error":"ModuleNotFoundError: No module named 'eth_tester.backends.pyevm'"},{"fix":"When using `web3.py` with `eth-tester`, create a `web3` instance using the `EthereumTesterProvider`: `from web3 import Web3; w3 = Web3(Web3.EthereumTesterProvider(tester))` then use `w3.eth...`.","cause":"Attempting to use `web3.py`'s `w3.eth` object methods (like `w3.eth.send_transaction`) directly on an `EthereumTester` instance.","error":"AttributeError: 'EthereumTester' object has no attribute 'eth'"},{"fix":"Review the transaction parameters (gas limit, data) and the contract logic. Increase the `gas` amount in the transaction, or inspect the transaction trace to find the failing opcode (requires a debugging backend).","cause":"A transaction submitted to the `eth-tester` backend (especially `PyEVMBackend`) ran out of gas, often due to an incorrect gas limit, an invalid operation, or a contract revert.","error":"eth_tester.exceptions.TransactionFailed: Transaction failed: 'out of gas'"},{"fix":"Ensure you have mined enough blocks with `tester.mine_block()` to reach the desired block number before attempting to query it.","cause":"Attempting to query a block number that has not yet been mined in the tester.","error":"ValueError: block number out of bounds"}]}