ape-test

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

property address: Annotated[ChecksumAddress, _AddressValidator]: The address of this account. Subclasses must override and provide this value.

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

property public_key: HexBytes

The public key for the account.

`{notice} Account might not have this property if feature is unsupported or inaccessible. `

remove_delegate(**txn_kwargs)

Has the account class remove the override for the value of its delegate. For plugins that support this feature, the way they choose to handle it can vary. For example, on a network using an EIP7702-like feature available it will reset the delegate to empty. However, if a plugin chooses to handle it, the resulting action (if successful) should make sure that the value that self.delegate returns None after it is completed.

By default, this method raises APINotImplementedError signaling that support is not available for this feature. Calling this may result in other errors if implemented.

Parameters:: **txn_kwargs – Additional transaction kwargs passed to create_transaction(), such as gas max_fee, or max_priority_fee. For a list of available transaction kwargs, see TransactionAPI.

set_delegate(contract: BaseAddress | Annotated[ChecksumAddress, _AddressValidator] | str, **txn_kwargs)

Have the account class override the value of its delegate. For plugins that support this feature, the way they choose to handle it can vary. For example, it could be a call to upgrade itself using some built-in method for a smart wallet (with default txn args) e.g. the Safe smart wallet (https://github.com/ApeWorX/ape-safe), or it could be to use an EIP- 7702-like feature available on the network to set a delegate for that account. However if a plugin chooses to handle it, the resulting action (if successful) should make sure that the value that self.delegate returns is the same as contract after it is completed.

By default, this method raises APINotImplementedError signaling that support is not available for this feature. Calling this may result in other errors if implemented.

Parameters:

(` (contract) – class:~ape.contracts.ContractInstance`): The contract instance to override the delegate with.
**txn_kwargs – Additional transaction kwargs passed to create_transaction(), such as gas max_fee, or max_priority_fee. For a list of available transaction kwargs, see TransactionAPI.

sign_authorization(address: Annotated[ChecksumAddress, _AddressValidator], chain_id: int | None = None, nonce: int | None = None) → MessageSignature | None

Sign an EIP-7702 Authorization.

Parameters:

address (Any) – A delegate address to sign the authorization for.
chain_id (Optional[int]) – The chain ID that the authorization should be valid for. A value of 0 means that the authorization is valid for any chain. Default tells implementation to use the currently connected network’s chain_id.
nonce (Optional[int]) – The nonce to use to sign authorization with. Defaults to account’s current nonce.

Returns:

The signature corresponding to the message.

Return type:

MessageSignature (optional)

`{caution} This action has the capability to be extremely destructive to the signer, and might lead to full account compromise. All implementations are recommended to ensure that the signer be made aware of the severity and impact of this action through some callout. `

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 APINotImplementedError.
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_nested_max_split: int | 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=[]), enable_fixture_rebasing: bool = True, 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, isolation: bool | IsolationConfig = True, **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.

enable_fixture_rebasing: bool: Set to False to ignore fixture rebasing when non-function scoped fixtures become invalidated.

gas: GasConfig: Configuration related to gas reporting.

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

isolation: bool | IsolationConfig: Configure which scope-specific isolation to enable. Set to False to disable all and True (default) to disable all.

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_nested_max_split: int | 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_nested_max_split: int | 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_nested_max_split: int | 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_nested_max_split: int | 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.config.IsolationConfig(_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_nested_max_split: int | 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, *, enable_session: bool = True, enable_package: bool = True, enable_module: bool = True, enable_class: bool = True, enable_function: bool = True, **values: Any)

enable_class: bool: Set to False to disable class isolation.

enable_function: bool: Set to False to disable function isolation.

enable_module: bool: Set to False to disable module isolation.

enable_package: bool: Set to False to disable package isolation.

enable_session: bool: Set to False to disable session isolation.

class ape_test.provider.ApeEVMBackend(config: ApeTestConfig, chain_id: int): 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 http_uri: str | None: Return the raw HTTP/HTTPS URI to connect to this provider, if supported.

property ipc_path: Path | None: Return the IPC path for the provider, if supported.

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.

property ws_uri: str | None: Return the raw WS/WSS URI to connect to this provider, if supported.