Ethereum Tester

0.13.0b1 · active · verified Thu Apr 16

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.

Common errors

```
ModuleNotFoundError: No module named 'eth_tester.backends.pyevm'
```
cause 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'
```
cause 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'
```
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.

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
```
cause 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.

Warnings

breaking 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.
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.
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`.
gotcha 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.
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`.
gotcha 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.
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.

Install

pip install eth-tester Install core library
pip install eth-tester[py-evm] Install with PyEVM backend (recommended)

Imports

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

Quickstart

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']}")

view raw JSON →