Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added link to AppBuilder. #205

Merged
merged 1 commit into from
Dec 10, 2024
Merged

Added link to AppBuilder. #205

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 23 additions & 17 deletions src/pages/cw-multi-test/blocks.mdx
View file
Open in desktop
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
Loading