docs: document testing_env! macro
@@ -7,10 +7,68 @@ mod context;
pub use context::{accounts, testing_env_with_promise_results, VMContextBuilder};
use near_vm_logic::mocks::mock_external::Receipt;
+/// Initializes a testing environment to mock interactions which would otherwise go through a
+/// validator node. This macro will initialize or overwrite the [`BLOCKCHAIN_INTERFACE`]
+/// instance which satisfies the [`BlockchainInterface`] trait for interactions from a
+/// smart contract.
+///
+/// There are five parameters that can be accepted to configure the interface with a
+/// [`MockedBlockchain`], in this order:
+/// - `context`: [`VMContext`] which contains some core information about
+/// the blockchain and message data which can be used from the smart contract.
+/// - `config` (optional): [`VMConfig`] which contains some additional information
+/// about the VM to configure parameters not directly related to the transaction being executed.
+/// - `fee_config`(optional): [`RuntimeFeesConfig`] which configures the
+/// fees for execution and storage of transactions.
+/// - `validator`(optional): a [`HashMap`]<[`AccountId`], [`Balance`]> mocking the
+/// current validators of the blockchain.
+/// - `promise_results`(optional): a [`Vec`] of [`PromiseResult`] which mocks the results
+/// of callback calls during the execution.
+///
+/// Any argument not included will use the default implementation of each.
+///
+/// # Example use
+///
+/// ```
+/// #[macro_use]
+/// extern crate near_sdk;
+///
+/// use near_sdk::test_utils::{accounts, VMContextBuilder};
+/// use near_sdk::{VMConfig, RuntimeFeesConfig};
+/// use std::collections::HashMap;
+///
+/// # fn main() {
+/// // Initializing some context is required
+/// let context = VMContextBuilder::new().signer_account_id(accounts(0)).build();
+///
+/// // Build with just the base context
+/// testing_env!(context.clone());
+///
+/// // Or include arguments up to the five optional
+/// testing_env!(
+/// context,
+/// VMConfig::default(),
+/// RuntimeFeesConfig::default(),
+/// HashMap::default(),
+/// Vec::default()
+/// );
+/// # }
+/// ```
+///
+/// [`BLOCKCHAIN_INTERFACE`]: crate::env::BLOCKCHAIN_INTERFACE
+/// [`BlockchainInterface`]: crate::BlockchainInterface
+/// [`MockedBlockchain`]: crate::MockedBlockchain
+/// [`VMContext`]: crate::VMContext
+/// [`VMConfig`]: crate::VMConfig
+/// [`RuntimeFeesConfig`]: crate::RuntimeFeesConfig
+/// [`AccountId`]: crate::AccountId
+/// [`Balance`]: crate::Balance
+/// [`PromiseResult`]: crate::PromiseResult
+/// [`HashMap`]: std::collections::HashMap
#[macro_export]
macro_rules! testing_env {
($context:expr, $config:expr, $fee_config:expr, $validator:expr, $promise_results:expr) => {
- near_sdk::env::set_blockchain_interface(Box::new(MockedBlockchain::new(
+ near_sdk::env::set_blockchain_interface(Box::new(near_sdk::MockedBlockchain::new(
$context,
$config,
$fee_config,
