Skip to content

Commit

Permalink
Added link to AppBuilder. (#205)
Browse files Browse the repository at this point in the history
  • Loading branch information
DariuszDepta authored Dec 10, 2024
2 parents 9d527ed + 7180991 commit ecfdc62
Showing 1 changed file with 23 additions and 17 deletions.
40 changes: 23 additions & 17 deletions src/pages/cw-multi-test/blocks.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ tags: ["multitest", "blocks"]
import { Callout } from "nextra/components";

[BlockInfo]: https://docs.rs/cosmwasm-std/latest/cosmwasm_std/struct.BlockInfo.html
[AppBuilder]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.AppBuilder.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]:
Expand Down Expand Up @@ -52,7 +53,7 @@ In **`MultiTest`**, the chain is initialized with a default block that has the f

These properties constitute the [`BlockInfo{:rust}`][BlockInfo] structure, which is defined in the
CosmWasm library for representing block metadata. [`BlockInfo{:rust}`][BlockInfo] can be retrieved
at any point in a test by calling the [`block_info(){:rust}`][block_info] function provided by
at any point in a test by calling the [`block_info{:rust}`][block_info] method provided by
`App{:rust}`.

The following example illustrates this case in detail.
Expand All @@ -77,21 +78,21 @@ assert_eq!("cosmos-testnet-14002", block.chain_id);
```

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
[`default{:rust}`][app_default] on `App{:rust}`. In line 7, the current block metadata (of type
[`BlockInfo{:rust}`][BlockInfo]) is retrieved and assigned to variable `block{:rust}`. In the next
few lines, the default values are checked:

- 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,
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}`.

## 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{:rust}`][BlockInfo] using the
[`set_block(){:rust}`][set_block] function provided by `App{:rust}`. The following example explains
this case in detail.
[`set_block{:rust}`][set_block] method provided by `App{:rust}`. The following example explains this
case in detail.

```rust showLineNumbers {8-12} /set_block/ /BlockInfo/
use cosmwasm_std::{BlockInfo, Timestamp};
Expand Down Expand Up @@ -121,25 +122,30 @@ assert_eq!("starship-testnet", block.chain_id);
```

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
[`set_block{:rust}`][set_block] method is called with custom block properties provided as
[`BlockInfo{:rust}`][BlockInfo] structure. The current block metadata is retrieved in line 12 and in
the next few lines the detailed values are checked:

- 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,
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}`.

This way, you can initialize the current block in tests to best suit your requirements.

<Callout type="info" emoji="">
You can also initialize the blockchain simulator with the custom block using [AppBuilder], as
shown in this [example](app-builder#with_block).
</Callout>

## 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.
To generate a new block in tests, you can use the [`update_block{:rust}`][update_block] method
provided by `App{:rust}`. In the following example, [`update_block{:rust}`][update_block] method
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};
Expand All @@ -165,8 +171,8 @@ assert_eq!(1571797424879305533, block.time.nanos());
assert_eq!("cosmos-testnet-14002", block.chain_id);
```

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
In line 7 the [`update_block{:rust}`][update_block] method 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
Expand All @@ -178,7 +184,7 @@ is checked against the Unix timestamp, which is 5 seconds later than the default
Several events on the blockchain occur after a period longer than a few seconds. In such cases,
incrementing the block time multiple times until the desired time is reached would be impractical.
In **`MultiTest`**, it is possible to advance the block using a specific block height and time. To
achieve this, pass a custom closure to the [`update_block(){:rust}`][update_block] function. This
achieve this, pass a custom closure to the [`update_block{:rust}`][update_block] method. This
closure takes a mutable [`BlockInfo{:rust}`][BlockInfo] structure as an argument and modifies its
properties, as shown in the example below.

Expand Down Expand Up @@ -210,7 +216,7 @@ assert_eq!("cosmos-testnet-14002", block.chain_id);
```

In line 4, the default block is initialized during the chain start. Then in line 7, the
[`update_block(){:rust}`][update_block] function takes a custom closure as an argument. This closure
[`update_block{:rust}`][update_block] method takes a custom closure as an argument. This closure
increments the block height by **10000** and advances the block time by **6 days**. Similarly like
in prevous examples, the new block metadata is retrieved and the current properties are checked. The
new block height should be `12345{:rust}` + `10000{:rust}` = `22345{:rust}`. The new block time
Expand Down

0 comments on commit ecfdc62

Please sign in to comment.