pub struct TestHost<State> { /* private fields */ }
Expand description

A Host implementation used for unit testing smart contracts.

The host provides a way to set up mock responses to transfers, and to contract invocations. This allows testing a specific entrypoint of a contract in isolation, assuming its dependents behave in the way specified by the supplied mock functions.

Additionally, this host provides some inspection capability so that after execution of an entrypoint tests can observe which accounts or contracts were affected.

Implementations

Create a new test host. **It is essential that any StateMap, StateSet or StateBox that exists in the provided state was created with the state_builder that is supplied. Otherwise the runtime error in the test.

Retrieve a reference to the underlying state builder.

Set up a mock entrypoint for handling calls to invoke_contract.

If you set up multiple handlers for the same entrypoint (to, method), then the latest handler will be used.

Set the contract balance. NB: This should be the sum of the contract’s initial balance and the amount you wish to invoke it with.

Example:

host.set_self_balance(Amount::from_ccd(10));
contract_receive(
    &ctx,
    &mut host,
    // This amount is _not_ added to the balance of the contract,
    // so calling `host.self_balance()` will return `10` initially.
    // When a contract is executed by the node the amount that is being sent (`5`)
    // is added to the balance of the contract, so that `host.self_balance()`
    // already observes it.
    Amount::from_ccd(5),
);

Check whether a given transfer occured.

Get a list of all transfers that have occurred, in the order they occurred in.

Get a list of all transfers to a specific account.

Set an account to be missing. Any transfers to this account will result in an TransferError::MissingAccount error.

This differs from the default, where all accounts are assumed to exist.

Helper function for invoking receive methods that respects the transactional nature of invocations. That is, if the invocation returns Err(_), then the host and state is rolled back to a checkpoint just before the invocation.

Trait Implementations

Perform a transfer to the given account if the contract has sufficient balance.

By default, all accounts are assumed to exist, and transfers to them will succeed (provided sufficient balance). Use make_account_missing to test out transfers to accounts not on chain.

Possible errors:

Invoke a contract entrypoint.

This uses the mock entrypoints set up with setup_mock_entrypoint. The method will fail with a panic if no responses were set for the given contract address and method.

If the invocation results in Err(_), the host and state will be rolled back. This means that the state and the logs of, e.g., transactions will look as if the invocation never occurred. See also TestHost::with_rollback.

Invoke a contract entrypoint.

This uses the mock entrypoints set up with setup_mock_entrypoint. The method will fail with a panic if no responses were set for the given contract address and method.

If the invocation results in Err(_), the host and state will be rolled back. This means that the state and the logs of, e.g., transactions will look as if the invocation never occurred. See also TestHost::with_rollback.

Get an immutable reference to the contract state.

Get a mutable reference to the contract state.

Get the contract balance. This can be set with set_self_balance and defaults to 0.

Get the state builder.

Get the state and the state builder.

The type of return values this host provides. This is the raw return value. The intention is that it will be deserialized by the consumer, via the Read implementation. Read more

The type of low-level state that is associated with the host. This provides access to low-level state operations. Read more

Make sure the contract state is fully written out, so that any changes that were done in-memory up to the point in contract execution are reflected in the actual contract state maintained by the node. Read more

Like invoke_contract_raw, except that the parameter is automatically serialized. If the parameter already implements AsRef<[u8]> or can be equivalently cheaply converted to a byte array, then invoke_contract_raw should be used, since it avoids intermediate allocations. Read more

Like invoke_contract_raw, except that the parameter is automatically serialized. If the parameter already implements AsRef<[u8]> or can be equivalently cheaply converted to a byte array, then invoke_contract_raw should be used, since it avoids intermediate allocations. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.