Registry / testing / eth-tester

eth-tester

JSON →
library0.13.0b1pypypi✓ verified 89d ago

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.

pip install eth-tester
INSTALL
IMPORT
SIG · ETH-TESTER
E
eth-tester
testingpythonv0.13.0b1
Install
6.9s avg
Import
3738ms
Disk
65MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v0.13.0b1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 3.821s · 63.1MB
glibc
py 3.10–3.940 runs
installs and imports cleanly · install 6.9s · import 3.656s · 66MB
65MB installed
● package 65MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

EthereumTester
✓ from eth_tester import EthereumTester
MockBackend
✓ from eth_tester import MockBackend
PyEVMBackend
✓ from eth_tester.backends.pyevm import PyEVMBackend
✗ from eth_tester import PyEVMBackend
PyEVMBackend is in a sub-module and requires the 'py-evm' extra to be installed.
GanacheBackend
✓ from eth_tester_ganache import GanacheBackend
✗ from eth_tester.backends.ganache import GanacheBackend
GanacheBackend is provided by the separate 'eth-tester-ganache' library.

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.

from eth_tester import EthereumTester, MockBackend from eth_utils import encode_hex, decode_hex # 1. Initialize the EthereumTester with a MockBackend # The MockBackend is a simple in-memory backend provided by eth-tester. # It simulates basic blockchain interactions for testing purposes. # For a full EVM, install with 'pip install eth-tester[py-evm]' and use PyEVMBackend. tester = EthereumTester(backend=MockBackend()) print("EthereumTester initialized with MockBackend.") # 2. Get available accounts accounts = tester.get_accounts() print(f"Available accounts: {[encode_hex(acc) for acc in accounts]}") # 3. Mine a block # Many operations, especially transactions, only take effect after a block is mined. tester.mine_block() print(f"Block mined. Current block number: {tester.get_block_by_number('latest')['number']}") # 4. Get an account's balance # In MockBackend, accounts start with a default balance. account_0_address = accounts[0] balance = tester.get_balance(account_0_address) print(f"Balance of {encode_hex(account_0_address)}: {balance} wei") # 5. Send a simple 'transaction' (e.g., a call) which is processed after mining. # Note: MockBackend does not simulate value transfer or EVM state changes without a full EVM backend. # This example primarily demonstrates the API for sending a transaction. transaction_hash = tester.send_transaction({ 'from': account_0_address, 'to': accounts[1], # Sending to another account (conceptual in MockBackend) 'gas_price': 0, 'gas': 21000, 'value': 0, 'data': b'' }) print(f"Transaction sent (hash: {encode_hex(transaction_hash)})") # Mine another block for the transaction to be included tester.mine_block() print(f"Block mined. Current block number: {tester.get_block_by_number('latest')['number']}")
Debug
Known issues
breakingVersion 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.
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.
affects: 0.13.0b1 and potentially later 0.x.x beta versions
gotcha`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).
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`.
affects: All versions
gotchaTransactions 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.
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`.
affects: All versions
gotchaWhile `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.
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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'eth_tester.backends.pyevm'
The `PyEVMBackend` was imported, but the `py-evm` dependency (and its corresponding extra) was not installed.
fix
Install `eth-tester` with the `py-evm` extra: `pip install eth-tester[py-evm]`.
AttributeError: 'EthereumTester' object has no attribute 'eth'
Attempting to use `web3.py`'s `w3.eth` object methods (like `w3.eth.send_transaction`) directly on an `EthereumTester` instance.
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...`.
eth_tester.exceptions.TransactionFailed: Transaction failed: 'out of gas'
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.
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).
ValueError: block number out of bounds
Attempting to query a block number that has not yet been mined in the tester.
fix
Ensure you have mined enough blocks with `tester.mine_block()` to reach the desired block number before attempting to query it.
Upgrade
Version history
0.13.0b1latest on PyPI · released Apr 23, 2025
Audit
Dependencies
py-evmoptionalProvides the PyEVM backend, which is commonly used for local EVM simulation. `eth-tester` requires a backend to function beyond basic mocking.
eth-utilsrequiredUtility functions for Ethereum, often used in conjunction with eth-tester for data encoding/decoding.
Agent activity
17 hits · last 30 days
node
16
Resources
eth-tester — pip install eth-tester · libregistry