ape-test

class ape_test.accounts.TestAccount(*, index: int, address_str: str, private_key: str)

property address: AddressType: The address of this account. Subclasses must override and provide this value.

property alias: str: A shortened-name for quicker access to the account.

sign_message(msg: Any, **signer_options) → MessageSignature | None

Sign a message.

Parameters:

msg (Any) – The message to sign. Account plugins can handle various types of messages. For example, KeyfileAccount can handle SignableMessage, str, int, and bytes. See these docs # noqa: E501 for more type information on the SignableMessage type.
**signer_options – Additional kwargs given to the signer to modify the signing operation.

Returns:

The signature corresponding to the message.

Return type:

MessageSignature (optional)

sign_raw_msghash(msghash: HexBytes) → MessageSignature

Sign a raw message hash.

Parameters:: msghash (HexBytes) – The message hash to sign. Plugins may or may not support this operation. Default implementation is to raise NotImplementedError.
Returns:: The signature corresponding to the message.
Return type:: MessageSignature (optional)

sign_transaction(txn: TransactionAPI, **signer_options) → TransactionAPI | None

Sign a transaction.

Parameters:

txn (TransactionAPI) – The transaction to sign.
**signer_options – Additional kwargs given to the signer to modify the signing operation.

Returns:

A signed transaction.: The TransactionAPI returned by this method may not correspond to txn given as input, however returning a properly-formatted transaction here is meant to be executed. Returns None if the account does not have a transaction it wishes to execute.

Return type:

TransactionAPI (optional)

class ape_test.accounts.TestAccountContainer(*, name: str, account_type: type[AccountAPI])

property accounts: Iterator[TestAccount]

All accounts.

Returns:: Iterator[AccountAPI]

property aliases: Iterator[str]

All available aliases.

Returns:: Iterator[str]

generate_account(index: int | None = None) → TestAccountAPI: Generate a new test account.

get_test_account(index: int) → TestAccountAPI

Get the test account at the given index.

Parameters:: index (int) – The index of the test account.
Returns:: TestAccountAPI

reset(): Reset the account container to an original state.

class ape_test.config.ApeTestConfig(_case_sensitive: bool | None = None, _nested_model_default_partial_update: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _env_parse_enums: bool | None = None, _cli_prog_name: str | None = None, _cli_parse_args: bool | list[str] | tuple[str, ...] | None = None, _cli_settings_source: CliSettingsSource[Any] | None = None, _cli_parse_none_str: str | None = None, _cli_hide_none_type: bool | None = None, _cli_avoid_json: bool | None = None, _cli_enforce_required: bool | None = None, _cli_use_class_docs_for_groups: bool | None = None, _cli_exit_on_error: bool | None = None, _cli_prefix: str | None = None, _cli_flag_prefix_char: str | None = None, _cli_implicit_flags: bool | None = None, _cli_ignore_unknown_args: bool | None = None, _cli_kebab_case: bool | None = None, _secrets_dir: PathType | None = None, *, balance: int = 10000000000000000000000, coverage: CoverageConfig = CoverageConfig(track=False, reports=CoverageReportsConfig(terminal=True, xml=False, html=False), exclude=[]), disconnect_providers_after: bool = True, gas: GasConfig = GasConfig(exclude=[], reports=[]), hd_path: str = "m/44'/60'/0'/0", mnemonic: str = 'test test test test test test test test test test test junk', number_of_accounts: Annotated[int, Ge(ge=0)] = 10, provider: EthTesterProviderConfig = EthTesterProviderConfig(chain_id=1337, auto_mine=True), show_internal: bool = False, **values: Any)

balance: int: The starting-balance of every test account in Wei (NOT Ether).

coverage: CoverageConfig: Configuration related to coverage reporting.

disconnect_providers_after: bool: Set to False to keep providers connected at the end of the test run.

gas: GasConfig: Configuration related to gas reporting.

hd_path: str: The hd_path to use when generating the test accounts.

mnemonic: str: The mnemonic to use when generating the test accounts.

number_of_accounts: Annotated[int, Ge(ge=0)]: The number of test accounts to generate in the provider.

provider: EthTesterProviderConfig: Settings for the provider.

show_internal: bool: Set to True to always show Ape’s internal stack-trace in errors, useful for debugging the framework itself.

class ape_test.config.CoverageConfig(_case_sensitive: bool | None = None, _nested_model_default_partial_update: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _env_parse_enums: bool | None = None, _cli_prog_name: str | None = None, _cli_parse_args: bool | list[str] | tuple[str, ...] | None = None, _cli_settings_source: CliSettingsSource[Any] | None = None, _cli_parse_none_str: str | None = None, _cli_hide_none_type: bool | None = None, _cli_avoid_json: bool | None = None, _cli_enforce_required: bool | None = None, _cli_use_class_docs_for_groups: bool | None = None, _cli_exit_on_error: bool | None = None, _cli_prefix: str | None = None, _cli_flag_prefix_char: str | None = None, _cli_implicit_flags: bool | None = None, _cli_ignore_unknown_args: bool | None = None, _cli_kebab_case: bool | None = None, _secrets_dir: PathType | None = None, *, track: bool = False, reports: CoverageReportsConfig = CoverageReportsConfig(terminal=True, xml=False, html=False), exclude: list[CoverageExclusion] = [], **values: Any)

Configuration related to contract coverage.

exclude: list[CoverageExclusion]: Contract methods patterns to skip. Specify contract_name: and not method_name: to skip all methods in the contract. Only specify method_name: to skip all methods across all contracts. Specify both to skip methods in a certain contracts. Entries use glob-rules; use prefix_* to skip all items with a certain prefix.

reports: CoverageReportsConfig: Enable reports.

track: bool: Setting this to True is the same as always running with the --coverage flag.

Enable reports.

html: bool | dict: Set to True to generate HTML coverage reports.

terminal: bool | dict: Set to False to hide the terminal coverage report.

xml: bool | dict: Set to True to generate an XML coverage report in your .build folder.

class ape_test.config.EthTesterProviderConfig(_case_sensitive: bool | None = None, _nested_model_default_partial_update: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _env_parse_enums: bool | None = None, _cli_prog_name: str | None = None, _cli_parse_args: bool | list[str] | tuple[str, ...] | None = None, _cli_settings_source: CliSettingsSource[Any] | None = None, _cli_parse_none_str: str | None = None, _cli_hide_none_type: bool | None = None, _cli_avoid_json: bool | None = None, _cli_enforce_required: bool | None = None, _cli_use_class_docs_for_groups: bool | None = None, _cli_exit_on_error: bool | None = None, _cli_prefix: str | None = None, _cli_flag_prefix_char: str | None = None, _cli_implicit_flags: bool | None = None, _cli_ignore_unknown_args: bool | None = None, _cli_kebab_case: bool | None = None, _secrets_dir: PathType | None = None, *, chain_id: int = 1337, auto_mine: bool = True, **values: Any)

class ape_test.config.GasConfig(_case_sensitive: bool | None = None, _nested_model_default_partial_update: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _env_parse_enums: bool | None = None, _cli_prog_name: str | None = None, _cli_parse_args: bool | list[str] | tuple[str, ...] | None = None, _cli_settings_source: CliSettingsSource[Any] | None = None, _cli_parse_none_str: str | None = None, _cli_hide_none_type: bool | None = None, _cli_avoid_json: bool | None = None, _cli_enforce_required: bool | None = None, _cli_use_class_docs_for_groups: bool | None = None, _cli_exit_on_error: bool | None = None, _cli_prefix: str | None = None, _cli_flag_prefix_char: str | None = None, _cli_implicit_flags: bool | None = None, _cli_ignore_unknown_args: bool | None = None, _cli_kebab_case: bool | None = None, _secrets_dir: PathType | None = None, *, exclude: list[GasExclusion] = [], reports: list[str] = [], **values: Any)

Configuration related to test gas reports.

exclude: list[GasExclusion]: Contract methods patterns to skip. Specify contract_name: and not method_name: to skip all methods in the contract. Only specify method_name: to skip all methods across all contracts. Specify both to skip methods in a certain contracts. Entries use glob-rules; use prefix_* to skip all items with a certain prefix.

reports: list[str]: Report-types to use. Currently, only supports terminal.

class ape_test.config.GasExclusion(_case_sensitive: bool | None = None, _nested_model_default_partial_update: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_parse_none_str: str | None = None, _env_parse_enums: bool | None = None, _cli_prog_name: str | None = None, _cli_parse_args: bool | list[str] | tuple[str, ...] | None = None, _cli_settings_source: CliSettingsSource[Any] | None = None, _cli_parse_none_str: str | None = None, _cli_hide_none_type: bool | None = None, _cli_avoid_json: bool | None = None, _cli_enforce_required: bool | None = None, _cli_use_class_docs_for_groups: bool | None = None, _cli_exit_on_error: bool | None = None, _cli_prefix: str | None = None, _cli_flag_prefix_char: str | None = None, _cli_implicit_flags: bool | None = None, _cli_ignore_unknown_args: bool | None = None, _cli_kebab_case: bool | None = None, _secrets_dir: PathType | None = None, *, contract_name: str = '*', method_name: str | None = None, **values: Any)

class ape_test.provider.ApeEVMBackend(config: ApeTestConfig): A lazier version of PyEVMBackend for the Ape framework.

class ape_test.provider.EthTesterTransactionTrace(*, call_trace_approach: TraceApproach | None = None, transaction_hash: HexStr, debug_trace_transaction_parameters: dict = {'enableMemory': True})

property return_value: Any: The return value deduced from the trace.

class ape_test.provider.LocalProvider(*args, name: str, network: NetworkAPI, provider_settings: dict = {}, request_header: dict = {}, block_page_size: int = 100, concurrency: int = 4)

property auto_mine: bool: Whether automine is enabled.

property base_fee: int: EthTester does not implement RPC eth_feeHistory. Returns the last base fee on chain.

property chain_id: int: The blockchain ID. See ChainList for a comprehensive list of IDs.

property config: ApeTestConfig: The provider’s configuration.

connect(): Connect to a provider, such as start-up a process or create an HTTP connection.

disconnect(): Disconnect from a provider, such as tear-down a process or quit an HTTP session.

estimate_gas_cost(txn: TransactionAPI, block_id: BlockID | None = None, **kwargs) → int

Estimate the cost of gas for a transaction.

Parameters:

txn (TransactionAPI) – The transaction to estimate the gas for.
block_id (Optional[BlockID]) – The block ID to use when estimating the transaction. Useful for checking a past estimation cost of a transaction.

Returns:

The estimated cost of gas to execute the transaction reported in the fee-currency’s smallest unit, e.g. Wei. If the provider’s network has been configured with a gas limit override, it will be returned. If the gas limit configuration is “max” this will return the block maximum gas limit.

Return type:

int

property gas_price: int: The price for what it costs to transact (pre-EIP-1559).

get_balance(address: Annotated[ChecksumAddress, _AddressValidator], block_id: BlockID | None = None) → int

Get the balance of an account.

Parameters:

address (AddressType) – The address of the account.
block_id (BlockID) – Optionally specify a block ID. Defaults to using the latest block.

Returns:

The account balance.

Return type:

int

get_contract_logs(log_filter: LogFilter) → Iterator[ContractLog]

Get logs from contracts.

Parameters:: log_filter (LogFilter) – A mapping of event ABIs to topic filters. Defaults to getting all events.
Returns:: Iterator[ContractLog]

get_nonce(address: Annotated[ChecksumAddress, _AddressValidator], block_id: BlockID | None = None) → int

Get the number of times an account has transacted.

Parameters:

address (AddressType) – The address of the account.
block_id (Optional[BlockID]) – The block ID for checking a previous account nonce.

Returns:

int

get_test_account(index: int) → TestAccountAPI

Retrieve one of the provider-generated test accounts.

Parameters:: index (int) – The index of the test account in the HD-Path.
Returns:: TestAccountAPI

get_transaction_trace(transaction_hash: str, **kwargs) → TraceAPI

Provide a detailed description of opcodes.

Parameters:: txn_hash (Union[HexBytes, str]) – The hash of a transaction to trace.
Returns:: A transaction trace.
Return type:: TraceAPI

get_virtual_machine_error(exception: Exception, **kwargs) → VirtualMachineError

Get a virtual machine error from an error returned from your RPC.

Parameters:

exception (Exception) – The error returned from your RPC client.

Returns:

An error representing what: went wrong in the call.

Return type:

VirtualMachineError

property max_gas: int: The max gas limit value you can use.

mine(num_blocks: int = 1)

Advance by the given number of blocks.

Parameters:: num_blocks (int) – The number of blocks allotted to mine. Defaults to 1.

property priority_fee: int: Returns 0 because test chains do not care about priority fees.

restore(snapshot_id: SnapshotID)

Regress the current call using the given snapshot ID. Allows developers to go back to a previous state.

Parameters:: snapshot_id (str) – The snapshot ID.

send_call(txn: TransactionAPI, block_id: BlockID | None = None, state: dict | None = None, **kwargs) → HexBytes

Execute a new transaction call immediately without creating a transaction on the block chain.

Parameters:

txn – TransactionAPI
block_id (Optional[BlockID]) – The block ID to use to send a call at a historical point of a contract. Useful for checking a past estimation cost of a transaction.
state (Optional[dict]) – Modify the state of the blockchain prior to sending the call, for testing purposes.
**kwargs – Provider-specific extra kwargs.

Returns:

The result of the transaction call.

Return type:

str

send_transaction(txn: TransactionAPI) → ReceiptAPI

Send a transaction to the network.

Parameters:: txn (TransactionAPI) – The transaction to send.
Returns:: ReceiptAPI

set_timestamp(new_timestamp: int)

Change the pending timestamp.

Parameters:: new_timestamp (int) – The timestamp to set.
Returns:: The new timestamp.
Return type:: int

property settings: EthTesterProviderConfig: The combination of settings from ape-config.yaml and .provider_settings.

snapshot() → SnapshotID

Record the current state of the blockchain with intent to later call the method revert() to go back to this point. This method is for local networks only.

Returns:: The snapshot ID.
Return type:: SnapshotID

property supports_tracing: bool: True when the provider can provide transaction traces.

update_settings(new_settings: dict)

Change a provider’s setting, such as configure a new port to run on. May require a reconnect.

Parameters:: new_settings (dict) – The new provider settings.