Struct TestEnvironment

Source

pub struct TestEnvironment<D>(/* private fields */)
where
    D: SubstateDatabase + CommittableSubstateDatabase + 'static;

Expand description

The environment that all tests of this testing framework are run against.

This struct may be thought of as the main struct in this testing framework which encapsulates a a self-contained instance of the Radix Engine ([EncapsulatedRadixEngine]). The functionality of the Radix Engine is exposed through the SystemApi which makes this testing environment no less capable than Scrypto code.

§Introduction

This testing framework is designed to allow you to write Scrypto-like code and use that to test your packages and blueprints and follows a different approach from the LedgerSimulator class. The test-runner is an in-memory ledger simulator which you can interact with as a user that submits transactions to the network. The approach followed by this testing framework is different, instead of submitting transactions, you’re making invocations to the Radix Engine, getting results back, and then writing assertions against what you got back.

Both the LedgerSimulator and this testing framework will prove to be useful throughout your blueprint development journey. As an example, this testing framework allows you to disable some of kernel modules that may get in your way when writing tests so it may be an optimal framework to use to ensure that the “math checks out” in your blueprint code without needing to think about costing or auth. However, when you’re reaching the final stages of developing a blueprint you may want tests that check that interactions with your blueprint will succeed in a simulated setting that is close to the real setting, which is when the LedgerSimulator comes in. Overall, we may put these two frameworks into two categories: This framework (named scrypto-test) is a framework for unit testing your blueprints and is a good framework to use to check that your DeFi logic is correct. The LedgerSimulator is an integration testing or an end-to-end testing framework to test that your blueprints work in a simulated ledger with all of the costing limits, substate limits, and other limits applied.

§Features

This framework has many new features that developers may find useful when testing their packages some of those features are:

The ability to create mock Buckets and Proofs through two main ways: by creating them out of thin air, and by disabling the auth module and minting them. This functionality can be found in the BucketFactory and ProofFactory structs and the CreationStrategy.
The ability to query the contents of Buckets and Proofs for the purpose of writing assertions against them. Not only that, but this testing framework allows you to call any method you wish on these nodes. As an example, in a test, you can get a Bucket and then create a proof out of it in manner similar to Scrypto.
The ability to enable and disable kernel modules at runtime. The Radix Engine kernel is quite modular with concepts such as auth, costing, and limits being implemented as kernel modules. Disabling or enabling kernel modules at runtime can prove to be quite useful when writing DeFi tests. As an example, you may want to not think about costing at all when writing tests and thus you may opt to disable the costing module entirely and continue your test without it. This can be done through TestEnvironment::disable_costing_module.
This testing framework uses test bindings to provide a higher-level API for calling methods and functions on a blueprint without the need to do raw TestEnvironment::call_method_typed or TestEnvironment::call_function_typed. The test bindings are generated by the blueprint macro and are feature gated behind a test feature.

§Getting Started

The following example shows a very simple test that gets XRD from the faucet and then asserts that the amount is equal to what we expect.

use scrypto_test::prelude::*;

fn my_test() -> Result<(), RuntimeError> {
    // Arrange
    let mut env = TestEnvironment::new();

    // Act
    let bucket = env.call_method_typed::<_, _, Bucket>(
        FAUCET,
        "free",
        &(),
    )?;

    // Assert
    let amount = bucket.amount(&mut env)?;
    assert_eq!(amount, dec!("10000"));

    Ok(())
}

A few things to note about the code you see above:

There is no transactions, worktop, receipt, manifests or anything of that sort! This part is “not just hidden” from this testing framework but is actually non existent! The approach that framework of wrapping a self-contained Radix Engine means that there is no need for manifests or other transaction concepts.
Methods such as Bucket::amount can be called to get the amount of resources in a bucket and then assert against that.

§Manipulating Kernel Modules

At runtime, the kernel modules can be enabled or disabled. For each kernel module there are four methods on the TestEnvironment:

A method to enable the kernel module (e.g., TestEnvironment::enable_costing_module).
A method to disable the kernel module (e.g., TestEnvironment::disable_costing_module).
A method to perform some action in a callback with the module enabled (e.g., TestEnvironment::with_costing_module_enabled).
A method to perform some action in a callback with the module disabled (e.g., TestEnvironment::with_costing_module_disabled).

The simple enable and disable methods are quite straightforward: call them to enable or disable a kernel module. The with_* methods are a little bit more intricate, they allow you to perform some actions with a specific kernel either enabled or disabled and then resets the state of the kernel modules afterwards. As an example:

use scrypto_test::prelude::*;

// Arrange
let mut env = TestEnvironment::new();

// Act
let bucket = env.with_auth_module_disabled(|env| {
    /* Auth Module is disabled just before this point */
    ResourceManager(XRD).mint_fungible(100.into(), env)
    /* Kernel modules are reset just after this point. */
})?;

// Assert
let amount = bucket.amount(&mut env)?;
assert_eq!(amount, dec!("100"));

§Common Arranges or Teardowns

There are cases where you may have many tests that all share a large portion of your arrange or teardown logic. While this framework does not specifically provide solutions for this, there are many useful Rust patterns that may be employed here to allow you to do this: the simplest and the most elegant is probably by using callback functions.

Imagine this, you’re building a Dex and many of the tests you write require you to have two resources with a very large supply so you can write your tests with. You can achieve this by doing something like:

use scrypto_test::prelude::*;

pub fn two_resource_environment<F>(func: F)
where
    F: FnOnce(DefaultTestEnvironment, FungibleBucket, FungibleBucket),
{
    let mut env = TestEnvironment::new();
    let bucket1 = ResourceBuilder::new_fungible(OwnerRole::None)
        .mint_initial_supply(dec!("100000000000"), &mut env)
        .unwrap();
    let bucket2 = ResourceBuilder::new_fungible(OwnerRole::None)
        .mint_initial_supply(dec!("100000000000"), &mut env)
        .unwrap();
    func(env, bucket1, bucket2)

    /* Potential teardown happens here */
}

#[test]
fn contribution_provides_expected_amount_of_pool_units() {
    two_resource_environment(|mut env, bucket1, bucket2| {
        /* Your test goes here */
    })
}

You may have a function like two_resource_environment seen above which sets up the environment and then some callback and potentially then executes some teardown code. Another way to do this would be through simple factory and destructor methods.

Struct TestEnvironmentCopy item path

§Introduction

§Features

§Getting Started

§Manipulating Kernel Modules

§Common Arranges or Teardowns

Implementations§

impl TestEnvironment<InMemorySubstateDatabase>

pub fn new() -> Self

impl<D> TestEnvironment<D>where D: SubstateDatabase + CommittableSubstateDatabase + 'static,

pub fn call_function_typed<I, O>( &mut self, package_address: PackageAddress, blueprint_name: &str, function_name: &str, args: &I, ) -> Result<O, RuntimeError>where I: ScryptoEncode, O: ScryptoDecode,

§Arguments

§Returns

§Panics

pub fn call_method_typed<N, I, O>( &mut self, node_id: N, method_name: &str, args: &I, ) -> Result<O, RuntimeError>where N: Into<NodeId>, I: ScryptoEncode, O: ScryptoDecode,

§Arguments

§Returns

§Panics

pub fn call_direct_access_method_typed<N, I, O>( &mut self, node_id: N, method_name: &str, args: &I, ) -> Result<O, RuntimeError>where N: Into<NodeId>, I: ScryptoEncode, O: ScryptoDecode,

§Arguments

§Returns

§Panics

pub fn call_module_method_typed<N, I, O>( &mut self, node_id: N, module: AttachedModuleId, method_name: &str, args: &I, ) -> Result<O, RuntimeError>where N: Into<NodeId>, I: ScryptoEncode, O: ScryptoDecode,

§Arguments

§Returns

§Panics

pub fn with_kernel<F, O>(&mut self, callback: F) -> Owhere F: FnOnce(&TestKernel<'_, D>) -> O,

pub fn with_kernel_mut<F, O>(&mut self, callback: F) -> Owhere F: FnOnce(&mut TestKernel<'_, D>) -> O,

pub fn enable_kernel_trace_module(&mut self)

pub fn enable_limits_module(&mut self)

pub fn enable_costing_module(&mut self)

pub fn enable_auth_module(&mut self)

pub fn enable_transaction_runtime_module(&mut self)

pub fn enable_execution_trace_module(&mut self)

pub fn disable_kernel_trace_module(&mut self)

pub fn disable_limits_module(&mut self)

pub fn disable_costing_module(&mut self)

pub fn disable_auth_module(&mut self)

pub fn disable_transaction_runtime_module(&mut self)

pub fn disable_execution_trace_module(&mut self)

pub fn with_kernel_trace_module_enabled<F, O>(&mut self, callback: F) -> Owhere F: FnOnce(&mut Self) -> O,

pub fn with_limits_module_enabled<F, O>(&mut self, callback: F) -> Owhere F: FnOnce(&mut Self) -> O,

pub fn with_costing_module_enabled<F, O>(&mut self, callback: F) -> Owhere F: FnOnce(&mut Self) -> O,

pub fn with_auth_module_enabled<F, O>(&mut self, callback: F) -> Owhere F: FnOnce(&mut Self) -> O,

pub fn with_transaction_runtime_module_enabled<F, O>( &mut self, callback: F, ) -> Owhere F: FnOnce(&mut Self) -> O,

pub fn with_execution_trace_module_enabled<F, O>(&mut self, callback: F) -> Owhere F: FnOnce(&mut Self) -> O,

pub fn with_kernel_trace_module_disabled<F, O>(&mut self, callback: F) -> Owhere F: FnOnce(&mut Self) -> O,

pub fn with_limits_module_disabled<F, O>(&mut self, callback: F) -> Owhere F: FnOnce(&mut Self) -> O,

pub fn with_costing_module_disabled<F, O>(&mut self, callback: F) -> Owhere F: FnOnce(&mut Self) -> O,

pub fn with_auth_module_disabled<F, O>(&mut self, callback: F) -> Owhere F: FnOnce(&mut Self) -> O,

pub fn with_transaction_runtime_module_disabled<F, O>( &mut self, callback: F, ) -> Owhere F: FnOnce(&mut Self) -> O,

pub fn with_execution_trace_module_disabled<F, O>(&mut self, callback: F) -> Owhere F: FnOnce(&mut Self) -> O,

pub fn enabled_modules(&self) -> EnabledModules

pub fn set_enabled_modules(&mut self, enabled_modules: EnabledModules)

pub fn enable_module(&mut self, module: EnabledModules)

pub fn disable_module(&mut self, module: EnabledModules)

pub fn with_component_state<S, N, F, O>( &mut self, node_id: N, callback: F, ) -> Result<O, RuntimeError>where S: ScryptoDecode, N: Into<NodeId>, F: FnMut(&mut S, &mut Self) -> O,

§Arguments

§Returns

§Panics

pub fn get_current_epoch(&mut self) -> Epoch

pub fn set_current_epoch(&mut self, epoch: Epoch)

pub fn get_current_time(&mut self) -> Instant

pub fn set_current_time(&mut self, instant: Instant)

Trait Implementations§

impl Default for TestEnvironment<InMemorySubstateDatabase>

fn default() -> Self

impl<D> SystemActorApi<RuntimeError> for TestEnvironment<D>where D: SubstateDatabase + CommittableSubstateDatabase + 'static,

fn actor_get_blueprint_id(&mut self) -> Result<BlueprintId, RuntimeError>

fn actor_open_field( &mut self, object_handle: ActorStateHandle, field: FieldIndex, flags: LockFlags, ) -> Result<FieldHandle, RuntimeError>

fn actor_is_feature_enabled( &mut self, object_handle: ActorStateHandle, feature: &str, ) -> Result<bool, RuntimeError>

fn actor_get_node_id( &mut self, ref_handle: ActorRefHandle, ) -> Result<NodeId, RuntimeError>

fn actor_emit_event( &mut self, event_name: String, event_data: Vec<u8>, event_flags: EventFlags, ) -> Result<(), RuntimeError>

impl<D> SystemActorIndexApi<RuntimeError> for TestEnvironment<D>where D: SubstateDatabase + CommittableSubstateDatabase + 'static,

fn actor_index_insert( &mut self, object_handle: ActorStateHandle, collection_index: CollectionIndex, key: Vec<u8>, buffer: Vec<u8>, ) -> Result<(), RuntimeError>

fn actor_index_remove( &mut self, object_handle: ActorStateHandle, collection_index: CollectionIndex, key: Vec<u8>, ) -> Result<Option<Vec<u8>>, RuntimeError>

fn actor_index_scan_keys( &mut self, object_handle: ActorStateHandle, collection_index: CollectionIndex, limit: u32, ) -> Result<Vec<Vec<u8>>, RuntimeError>

fn actor_index_drain( &mut self, object_handle: ActorStateHandle, collection_index: CollectionIndex, limit: u32, ) -> Result<Vec<(Vec<u8>, Vec<u8>)>, RuntimeError>

fn actor_index_insert_typed<K, V>( &mut self, object_handle: u32, collection_index: u8, key: K, value: V, ) -> Result<(), E>where K: ScryptoEncode, V: ScryptoEncode,

fn actor_index_remove_typed<V>( &mut self, object_handle: u32, collection_index: u8, key: Vec<u8>, ) -> Result<Option<V>, E>where V: ScryptoDecode,

Struct TestEnvironment

impl<D> TestEnvironment<D>
where D: SubstateDatabase + CommittableSubstateDatabase + 'static,

pub fn call_function_typed<I, O>( &mut self, package_address: PackageAddress, blueprint_name: &str, function_name: &str, args: &I, ) -> Result<O, RuntimeError>
where I: ScryptoEncode, O: ScryptoDecode,

pub fn call_method_typed<N, I, O>( &mut self, node_id: N, method_name: &str, args: &I, ) -> Result<O, RuntimeError>
where N: Into<NodeId>, I: ScryptoEncode, O: ScryptoDecode,

pub fn call_direct_access_method_typed<N, I, O>( &mut self, node_id: N, method_name: &str, args: &I, ) -> Result<O, RuntimeError>
where N: Into<NodeId>, I: ScryptoEncode, O: ScryptoDecode,

pub fn call_module_method_typed<N, I, O>( &mut self, node_id: N, module: AttachedModuleId, method_name: &str, args: &I, ) -> Result<O, RuntimeError>
where N: Into<NodeId>, I: ScryptoEncode, O: ScryptoDecode,

pub fn with_kernel<F, O>(&mut self, callback: F) -> O
where F: FnOnce(&TestKernel<'_, D>) -> O,

pub fn with_kernel_mut<F, O>(&mut self, callback: F) -> O
where F: FnOnce(&mut TestKernel<'_, D>) -> O,

pub fn with_kernel_trace_module_enabled<F, O>(&mut self, callback: F) -> O
where F: FnOnce(&mut Self) -> O,

pub fn with_limits_module_enabled<F, O>(&mut self, callback: F) -> O
where F: FnOnce(&mut Self) -> O,

pub fn with_costing_module_enabled<F, O>(&mut self, callback: F) -> O
where F: FnOnce(&mut Self) -> O,

pub fn with_auth_module_enabled<F, O>(&mut self, callback: F) -> O
where F: FnOnce(&mut Self) -> O,

pub fn with_transaction_runtime_module_enabled<F, O>( &mut self, callback: F, ) -> O
where F: FnOnce(&mut Self) -> O,

pub fn with_execution_trace_module_enabled<F, O>(&mut self, callback: F) -> O
where F: FnOnce(&mut Self) -> O,

pub fn with_kernel_trace_module_disabled<F, O>(&mut self, callback: F) -> O
where F: FnOnce(&mut Self) -> O,

pub fn with_limits_module_disabled<F, O>(&mut self, callback: F) -> O
where F: FnOnce(&mut Self) -> O,

pub fn with_costing_module_disabled<F, O>(&mut self, callback: F) -> O
where F: FnOnce(&mut Self) -> O,

pub fn with_auth_module_disabled<F, O>(&mut self, callback: F) -> O
where F: FnOnce(&mut Self) -> O,

pub fn with_transaction_runtime_module_disabled<F, O>( &mut self, callback: F, ) -> O
where F: FnOnce(&mut Self) -> O,

pub fn with_execution_trace_module_disabled<F, O>(&mut self, callback: F) -> O
where F: FnOnce(&mut Self) -> O,

pub fn with_component_state<S, N, F, O>( &mut self, node_id: N, callback: F, ) -> Result<O, RuntimeError>
where S: ScryptoDecode, N: Into<NodeId>, F: FnMut(&mut S, &mut Self) -> O,

impl<D> SystemActorApi<RuntimeError> for TestEnvironment<D>
where D: SubstateDatabase + CommittableSubstateDatabase + 'static,

impl<D> SystemActorIndexApi<RuntimeError> for TestEnvironment<D>
where D: SubstateDatabase + CommittableSubstateDatabase + 'static,

fn actor_index_insert_typed<K, V>( &mut self, object_handle: u32, collection_index: u8, key: K, value: V, ) -> Result<(), E>
where K: ScryptoEncode, V: ScryptoEncode,

fn actor_index_remove_typed<V>( &mut self, object_handle: u32, collection_index: u8, key: Vec<u8>, ) -> Result<Option<V>, E>
where V: ScryptoDecode,

fn actor_index_scan_keys_typed<K>( &mut self, object_handle: u32, collection_index: u8, limit: u32, ) -> Result<Vec<K>, E>
where K: ScryptoDecode,

fn actor_index_drain_typed<K, V>( &mut self, object_handle: u32, collection_index: u8, limit: u32, ) -> Result<Vec<(K, V)>, E>
where K: ScryptoDecode, V: ScryptoDecode,

impl<D> SystemActorKeyValueEntryApi<RuntimeError> for TestEnvironment<D>
where D: SubstateDatabase + CommittableSubstateDatabase + 'static,

fn actor_remove_key_value_entry_typed<V>( &mut self, object_handle: u32, collection_index: u8, key: &Vec<u8>, ) -> Result<Option<V>, E>
where V: ScryptoDecode,

impl<D> SystemActorSortedIndexApi<RuntimeError> for TestEnvironment<D>
where D: SubstateDatabase + CommittableSubstateDatabase + 'static,

fn actor_sorted_index_insert_typed<V>( &mut self, object_handle: u32, collection_index: u8, sorted_key: ([u8; 2], Vec<u8>), value: V, ) -> Result<(), E>
where V: ScryptoEncode,

fn actor_sorted_index_remove_typed<V>( &mut self, object_handle: u32, collection_index: u8, sorted_key: &([u8; 2], Vec<u8>), ) -> Result<Option<V>, E>
where V: ScryptoDecode,

fn actor_sorted_index_scan_typed<K, V>( &mut self, object_handle: u32, collection_index: u8, count: u32, ) -> Result<Vec<(K, V)>, E>
where K: ScryptoDecode, V: ScryptoDecode,

impl<D> SystemBlueprintApi<RuntimeError> for TestEnvironment<D>
where D: SubstateDatabase + CommittableSubstateDatabase + 'static,

impl<D> SystemCostingApi<RuntimeError> for TestEnvironment<D>
where D: SubstateDatabase + CommittableSubstateDatabase + 'static,

impl<D> SystemExecutionTraceApi<RuntimeError> for TestEnvironment<D>
where D: SubstateDatabase + CommittableSubstateDatabase + 'static,

impl<D> SystemFieldApi<RuntimeError> for TestEnvironment<D>
where D: SubstateDatabase + CommittableSubstateDatabase + 'static,

fn field_read_typed<S>(&mut self, handle: u32) -> Result<S, E>
where S: ScryptoDecode,

fn field_write_typed<S>(&mut self, handle: u32, substate: &S) -> Result<(), E>
where S: ScryptoEncode,

impl<D> SystemKeyValueEntryApi<RuntimeError> for TestEnvironment<D>
where D: SubstateDatabase + CommittableSubstateDatabase + 'static,

fn key_value_entry_get_typed<S>(&mut self, handle: u32) -> Result<Option<S>, E>
where S: ScryptoDecode,

fn key_value_entry_set_typed<S>( &mut self, handle: u32, value: S, ) -> Result<(), E>
where S: ScryptoEncode,

impl<D> SystemKeyValueStoreApi<RuntimeError> for TestEnvironment<D>
where D: SubstateDatabase + CommittableSubstateDatabase + 'static,

impl<D> SystemObjectApi<RuntimeError> for TestEnvironment<D>
where D: SubstateDatabase + CommittableSubstateDatabase + 'static,