diff --git a/src/pages/cw-multi-test/blocks.mdx b/src/pages/cw-multi-test/blocks.mdx index ee615d82..a579c257 100644 --- a/src/pages/cw-multi-test/blocks.mdx +++ b/src/pages/cw-multi-test/blocks.mdx @@ -6,6 +6,11 @@ import { Callout } from "nextra/components"; [BlockInfo]: https://docs.rs/cosmwasm-std/latest/cosmwasm_std/struct.BlockInfo.html [block_info]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.App.html#method.block_info +[set_block]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.App.html#method.set_block +[update_block]: + https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.App.html#method.update_block +[next_block]: https://docs.rs/cw-multi-test/latest/cw_multi_test/fn.next_block.html +[app_default]: app#appdefault # Blocks @@ -34,7 +39,8 @@ as height and timestamp, in order to test delays on the blockchain. Always increment the height **and** the timestamp of the block in tests. -In the following chapters you will find practical examples of several operations on blocks. +In the following chapters, you will find practical examples of several operations on blocks, such as +block initialization and generating a new block. ## Initialization with the default block @@ -48,6 +54,8 @@ These properties constitute the [BlockInfo] structure, which is defined in the C representing block metadata. [BlockInfo] can be retrieved at any point in a test by calling the [`block_info(){:rust}`][block_info] function provided by `App{:rust}`. +The following example illustrates this case in detail. + ```rust {4, 7} showLineNumbers copy /block_info/ /assert_eq!(12345/ /assert_eq!(1571797419879305533/ /assert_eq!("cosmos-testnet-14002"/ use cw_multi_test::App; @@ -67,12 +75,22 @@ assert_eq!(1571797419879305533, block.time.nanos()); assert_eq!("cosmos-testnet-14002", block.chain_id); ``` -## Initialization with the custom block +In line 4, the chain is initialized and _started_ with the default settings by calling the function +[`default(){:rust}`][app_default] on `App{:rust}`. In line 7, the current block metadata (of type +[BlockInfo]) is retrieved and assigned to variable `block{:rust}`. In the next few lines, the +default values are checked: -(todo) +- line 10: block `height{:rust}` is `12345{:rust}`, +- line 13: block `time{:rust}` is a Unix timestamp of value `1571797419879305533{:rust}`, which is + the numeric representation of Wednesday, October 23, 2019 02:23:39 GMT, +- line 16: block `chain_id{:rust}` has a default value `"cosmos-testnet-14002"{:rust}`. -- `app.set_block{:rust}` -- `cosmwasm_std::BlockInfo{:rust}` +## Initialization with the custom block + +Although the chain initialization with the default block may be suitable for most test cases, it is +possible to initialize the chain with a custom [BlockInfo] using the +[`set_block(){:rust}`][set_block] function provided by `App{:rust}`. The following example explains +this case in detail. ```rust showLineNumbers {8-12} /set_block/ /BlockInfo/ use cosmwasm_std::{BlockInfo, Timestamp}; @@ -101,13 +119,26 @@ assert_eq!(1723627489, block.time.seconds()); assert_eq!("starship-testnet", block.chain_id); ``` -## Generating next block with the default step +The chain is started with the default settings in line 5. Then in line 8, the +[`set_block(){:rust}`][set_block] function is called with custom block properties provided as +[BlockInfo] structure. The current block metadata is retrieved in line 12 and in the next few lines +the detailed values are checked: -(todo) +- line 18: block `height{:rust}` is now `1{:rust}`, +- line 21: new block `time{:rust}` is a Unix timestamp of value `1723627489{:rust}`, which is the + numeric representation (in seconds) of Wednesday, August 14, 2024 09:24:49 GMT, +- line 24: block `chain_id{:rust}` has now a value `"starship-testnet"{:rust}`. -- what is the default step -- `app.update_block{:rust}` -- `next_block{:rust}` +This way, you can initialize the current block in tests to best suit your requirements. + +## Generating next block with the default step + +To generate a new block in tests, you can use the [`update_block{:rust}`][update_block] function +provided by `App{:rust}`. In the following example, [`update_block{:rust}`][update_block] function +takes a function [`next_block{:rust}`][next_block] as an argument. [`next_block{:rust}`][next_block] +function - provided by **`MultiTest`** - increases the block height by `1` and advances the block +time by `5` seconds, simulating the generation of a new block every `5` seconds in a real-life +blockchain. The `chain_id{:rust}` remains unchanged. ```rust showLineNumbers {7} /update_block/ /next_block/ use cw_multi_test::{next_block, App}; @@ -133,7 +164,15 @@ assert_eq!(1571797424879305533, block.time.nanos()); assert_eq!("cosmos-testnet-14002", block.chain_id); ``` -## Generating next block with custom step +In line 7 the [`update_block{:rust}`][update_block] function is called and in the next few lines the +current block properties are checked. In line 10 the block metadata is retrieved and assigned to +variable `block{:rust}`. In line 13, we check if the block height has changed. The default block +height is `12345{:rust}`, and we check it against the value `12346{:rust}`. As this assertion +passes, you can see that the block height was indeed incremented by `1`. Similarly, the block's time +is checked against the Unix timestamp, which is 5 seconds later than the default value: +`1571797424879305533{:rust}` - `1571797419879305533{:rust}` = `5000000000{:rust}` = 5 seconds. + +## Generating next block with the custom step (todo)