Anvil and Hardhat#
Tests run on the in-process revm engine by default.
Instead, they can run on an Anvil or Hardhat development chain that Wake talks to over JSON-RPC.
This is useful to connect to an already running node, to let external tools attach to the testing chain, or to test against the behavior of a specific client.
Hardhat support is deprecated.
This page lists what differs from the rest of the testing framework documentation, which describes the default engine.
Switching the engine#
The engine is selected in wake.toml:
The development chain has to be installed separately. Anvil is under active development, so keep it up to date:
Command-line arguments passed to the launched chain are set by the cmd_args options of the testing.anvil and testing.hardhat namespaces.
Connecting to a chain#
chain.connect() launches a new development chain for the duration of the test.
Given a URI, it connects to an already running chain instead:
- an HTTP connection (e.g.
http://localhost:8545), - a WebSocket connection (e.g.
ws://localhost:8545), - an IPC socket (e.g.
/tmp/anvil.ipc).
from wake.testing import *
@chain.connect("ws://localhost:8545")
def test_counter():
print(chain.chain_id)
When launching a new chain, the accounts, chain_id, fork and hardfork keyword arguments override the command-line arguments from the configuration, and two more keyword arguments are accepted:
| Keyword argument | Description | Default value |
|---|---|---|
min_gas_price |
minimum gas price accepted by the chain | 0 |
block_base_fee_per_gas |
base fee per gas for the next block | 0 |
None of the keyword arguments can be used when connecting to a running chain or when working with Hardhat.
Chain members#
Besides the members described in Chains and blocks, JSON-RPC chains have the following properties:
| Property | Description |
|---|---|
client_version |
client version as reported by the web3_clientVersion JSON-RPC method |
default_tx_confirmations |
default number of confirmations (mined blocks) needed before a transaction object is returned |
gas_price |
gas price used for transactions that do not specify one |
max_priority_fee_per_gas |
max priority fee per gas used for transactions that do not specify one |
require_signed_txs |
whether to send signed transactions or unsigned transactions |
All of them except client_version can be assigned to. JSON-RPC chains also have the following methods:
| Method | Description |
|---|---|
mine_many |
mine multiple blocks with an optional timestamp delta between blocks |
reset |
reset the chain to its initial state |
set_min_gas_price |
set the minimum gas price accepted by the chain |
set_next_block_base_fee_per_gas |
set the base fee per gas for the next block |
update_accounts |
update the accounts list |
chain.txs can also be indexed by a transaction hash (a string starting with 0x), chain.blocks supports len() and iteration, and chain.chain_interface exposes the JSON-RPC methods of the node (get_block, get_transaction, debug_trace_transaction, get_logs, ...), with type being a property rather than a method.
The testing.block_history option does not apply: the development chain keeps its own history.
Transaction arguments#
JSON-RPC chains implement the following transaction arguments in addition to those described in Interacting with contracts:
| Argument | Description |
|---|---|
gas_limit="auto" |
estimate the gas limit before sending the transaction |
access_list="auto" |
create the access list before sending the transaction |
max_fee_per_gas |
maximum fee per gas of an EIP-1559 transaction |
max_priority_fee_per_gas |
maximum priority fee per gas of an EIP-1559 transaction |
confirmations |
number of blocks to be mined before the transaction object is returned; 0 returns it immediately after the transaction is sent |
The transaction type is derived from the arguments. revert=False (revert_on_failure=False) for estimate and access_list requests is not supported.
Sending transactions from any account
The from_ argument can be used to send transactions from any account (including contract) or address by impersonating it.
However, this may come at a cost of decreased performance (see Performance considerations).
When sending transactions from an account with code (contract), the contract behaves as if it had no code during the execution of the transaction!
Transaction objects#
With confirmations=0, a transaction object is returned before the transaction is mined.
tx.wait() waits for it, and accessing properties that need the receipt, e.g. status, events, return_value or error, waits implicitly.
A revert error of such a transaction is not raised; it is available in tx.error.
tx.status is ExecutionStatusEnum.PENDING until the transaction is mined, and tx_callback is not invoked for transactions sent with confirmations=0.
Transaction objects additionally have the following properties:
| Property | Description |
|---|---|
chain_id |
chain ID of the transaction |
effective_gas_price |
effective gas price of the transaction |
gas_limit |
gas limit specified in the transaction |
nonce |
nonce specified in the transaction |
r, s |
parts of the ECDSA signature |
type |
type of the transaction |
value |
amount of Wei sent in the transaction |
and depending on the transaction type:
| Transaction type | Additional properties |
|---|---|
LegacyTransaction (type 0) |
gas_price, v |
Eip2930Transaction (type 1, EIP-2930) |
access_list, gas_price, y_parity |
Eip1559Transaction (type 2, EIP-1559) |
access_list, max_fee_per_gas, max_priority_fee_per_gas, y_parity |
Eip7702Transaction (type 4, EIP-7702) |
access_list, authorization_list, max_fee_per_gas, max_priority_fee_per_gas, y_parity |
To send multiple transactions in a single block, disable automine, send the transactions with confirmations=0 and gas_limit="auto", re-enable automine and call chain.mine().
Blocks#
Block objects additionally have the following properties: base_fee_per_gas, difficulty, extra_data, gas_limit, logs_bloom, miner, mix_hash, nonce, parent_hash, receipts_root, seal_fields, sha3_uncles, size, state_root, total_difficulty, transactions_root and uncles.
Other differences#
- An account's
noncecan only be incremented. - The contract code size limit (EIP-170) and initcode size limit (EIP-3860) are enforced, while the default engine does not enforce them, see Troubleshooting.