ape-test

class ape_test.ApeTestConfig(_case_sensitive: 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_prefix: str | None = None, _secrets_dir: str | Path | 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: int = 10, provider: EthTesterProviderConfig = EthTesterProviderConfig(chain_id=1337, auto_mine=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.

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.

model_config: ClassVar[SettingsConfigDict] = {'arbitrary_types_allowed': True, 'case_sensitive': False, 'cli_avoid_json': False, 'cli_enforce_required': False, 'cli_hide_none_type': False, 'cli_parse_args': None, 'cli_parse_none_str': None, 'cli_prefix': '', 'cli_prog_name': None, 'cli_settings_source': None, 'cli_use_class_docs_for_groups': False, 'env_file': None, 'env_file_encoding': None, 'env_ignore_empty': False, 'env_nested_delimiter': None, 'env_parse_enums': None, 'env_parse_none_str': None, 'env_prefix': '', 'extra': 'allow', 'json_file': None, 'json_file_encoding': None, 'protected_namespaces': ('model_', 'settings_'), 'secrets_dir': None, 'toml_file': None, 'validate_default': True, 'yaml_file': None, 'yaml_file_encoding': None}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

number_of_accounts: int

The number of test accounts to generate in the provider.

provider: EthTesterProviderConfig

Settings for the provider.

class ape_test.CoverageConfig(_case_sensitive: 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_prefix: str | None = None, _secrets_dir: str | Path | None = None, *, track: bool = False, reports: CoverageReportsConfig = CoverageReportsConfig(terminal=True, xml=False, html=False), exclude: list[ape_test.CoverageExclusion] = [], **values: Any)

Configuration related to contract coverage.

exclude: list[ape_test.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.

model_config: ClassVar[SettingsConfigDict] = {'arbitrary_types_allowed': True, 'case_sensitive': False, 'cli_avoid_json': False, 'cli_enforce_required': False, 'cli_hide_none_type': False, 'cli_parse_args': None, 'cli_parse_none_str': None, 'cli_prefix': '', 'cli_prog_name': None, 'cli_settings_source': None, 'cli_use_class_docs_for_groups': False, 'env_file': None, 'env_file_encoding': None, 'env_ignore_empty': False, 'env_nested_delimiter': None, 'env_parse_enums': None, 'env_parse_none_str': None, 'env_prefix': '', 'extra': 'allow', 'json_file': None, 'json_file_encoding': None, 'protected_namespaces': ('model_', 'settings_'), 'secrets_dir': None, 'toml_file': None, 'validate_default': True, 'yaml_file': None, 'yaml_file_encoding': None}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

reports: CoverageReportsConfig

Enable reports.

track: bool

Setting this to True is the same as always running with the --coverage flag.

class ape_test.CoverageReportsConfig(_case_sensitive: 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_prefix: str | None = None, _secrets_dir: str | Path | None = None, *, terminal: bool | dict = True, xml: bool | dict = False, html: bool | dict = False, **values: Any)

Enable reports.

html: bool | dict

Set to True to generate HTML coverage reports.

model_config: ClassVar[SettingsConfigDict] = {'arbitrary_types_allowed': True, 'case_sensitive': False, 'cli_avoid_json': False, 'cli_enforce_required': False, 'cli_hide_none_type': False, 'cli_parse_args': None, 'cli_parse_none_str': None, 'cli_prefix': '', 'cli_prog_name': None, 'cli_settings_source': None, 'cli_use_class_docs_for_groups': False, 'env_file': None, 'env_file_encoding': None, 'env_ignore_empty': False, 'env_nested_delimiter': None, 'env_parse_enums': None, 'env_parse_none_str': None, 'env_prefix': '', 'extra': 'allow', 'json_file': None, 'json_file_encoding': None, 'protected_namespaces': ('model_', 'settings_'), 'secrets_dir': None, 'toml_file': None, 'validate_default': True, 'yaml_file': None, 'yaml_file_encoding': None}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

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.EthTesterProviderConfig(_case_sensitive: 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_prefix: str | None = None, _secrets_dir: str | Path | None = None, *, chain_id: int = 1337, auto_mine: bool = True, **values: Any)
model_config: ClassVar[SettingsConfigDict] = {'arbitrary_types_allowed': True, 'case_sensitive': False, 'cli_avoid_json': False, 'cli_enforce_required': False, 'cli_hide_none_type': False, 'cli_parse_args': None, 'cli_parse_none_str': None, 'cli_prefix': '', 'cli_prog_name': None, 'cli_settings_source': None, 'cli_use_class_docs_for_groups': False, 'env_file': None, 'env_file_encoding': None, 'env_ignore_empty': False, 'env_nested_delimiter': None, 'env_parse_enums': None, 'env_parse_none_str': None, 'env_prefix': '', 'extra': 'allow', 'json_file': None, 'json_file_encoding': None, 'protected_namespaces': ('model_', 'settings_'), 'secrets_dir': None, 'toml_file': None, 'validate_default': True, 'yaml_file': None, 'yaml_file_encoding': None}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ape_test.GasConfig(_case_sensitive: 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_prefix: str | None = None, _secrets_dir: str | Path | None = None, *, exclude: list[ape_test.GasExclusion] = [], reports: list[str] = [], **values: Any)

Configuration related to test gas reports.

exclude: list[ape_test.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.

model_config: ClassVar[SettingsConfigDict] = {'arbitrary_types_allowed': True, 'case_sensitive': False, 'cli_avoid_json': False, 'cli_enforce_required': False, 'cli_hide_none_type': False, 'cli_parse_args': None, 'cli_parse_none_str': None, 'cli_prefix': '', 'cli_prog_name': None, 'cli_settings_source': None, 'cli_use_class_docs_for_groups': False, 'env_file': None, 'env_file_encoding': None, 'env_ignore_empty': False, 'env_nested_delimiter': None, 'env_parse_enums': None, 'env_parse_none_str': None, 'env_prefix': '', 'extra': 'allow', 'json_file': None, 'json_file_encoding': None, 'protected_namespaces': ('model_', 'settings_'), 'secrets_dir': None, 'toml_file': None, 'validate_default': True, 'yaml_file': None, 'yaml_file_encoding': None}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

reports: list[str]

Report-types to use. Currently, only supports terminal.

class ape_test.GasExclusion(_case_sensitive: 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_prefix: str | None = None, _secrets_dir: str | Path | None = None, *, contract_name: str = '*', method_name: str | None = None, **values: Any)
model_config: ClassVar[SettingsConfigDict] = {'arbitrary_types_allowed': True, 'case_sensitive': False, 'cli_avoid_json': False, 'cli_enforce_required': False, 'cli_hide_none_type': False, 'cli_parse_args': None, 'cli_parse_none_str': None, 'cli_prefix': '', 'cli_prog_name': None, 'cli_settings_source': None, 'cli_use_class_docs_for_groups': False, 'env_file': None, 'env_file_encoding': None, 'env_ignore_empty': False, 'env_nested_delimiter': None, 'env_parse_enums': None, 'env_parse_none_str': None, 'env_prefix': '', 'extra': 'allow', 'json_file': None, 'json_file_encoding': None, 'protected_namespaces': ('model_', 'settings_'), 'secrets_dir': None, 'toml_file': None, 'validate_default': True, 'yaml_file': None, 'yaml_file_encoding': None}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ape_test.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.

connect()

Connect a 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: int | HexStr | HexBytes | Literal['earliest', 'latest', 'pending'] | 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_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_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

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.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property priority_fee: int

Returns 0 because test chains do not care about priority fees.

restore(snapshot_id: str | int | bytes)

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: int | HexStr | HexBytes | Literal['earliest', 'latest', 'pending'] | None = None, state: dict | None = None, **kwargs) HexBytes

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

Parameters:
  • txnTransactionAPI

  • 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() str | int | bytes

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.

class ape_test.TestAccount(*, index: int, address_str: str, private_key: str)
property address: ChecksumAddress

The address of this account. Subclasses must override and provide this value.

property alias: str

A shortened-name for quicker access to the account.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

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.TestAccountContainer(*args, name: str, account_type: type[ape.api.accounts.AccountAPI], num_generated: int = 0, mnemonic: str = '', num_of_accounts: int = 0, hd_path: str = '')
property accounts: Iterator[TestAccount]

All accounts.

Returns:

Iterator[AccountAPI]

property aliases: Iterator[str]

All available aliases.

Returns:

Iterator[str]

generate_account() TestAccountAPI

Generate a new test account.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].