Skip to content

Commit

Permalink
Added documentation for storage (#245)
Browse files Browse the repository at this point in the history
  • Loading branch information
@DariuszDepta
DariuszDepta authored Feb 6, 2025
2 parents 82514f0 + ff2f0c7 commit 1eaec6e
Show file tree
Hide file tree
Showing 4 changed files with 356 additions and 15 deletions.
2 changes: 1 addition & 1 deletion src/pages/cw-multi-test/api.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ can use any implementation of the [Api][Api] trait in your tests by utilizing th

The table below summarizes all methods of the [Api][Api] trait with short descriptions:

| Methods of [Api][Api] trait | Description |
| Methods of [Api] trait | Description |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`addr_canonicalize{:rust}`][addr_canonicalize] | Converts a human-readable address into its canonical binary representation. |
| [`addr_humanize{:rust}`][addr_humanize] | Converts a canonical address into human-readable address. |
Expand Down
102 changes: 101 additions & 1 deletion src/pages/cw-multi-test/app-builder.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,13 @@ import { Callout } from "nextra/components";
https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.AppBuilder.html#method.with_block
[with_gov]:
https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.AppBuilder.html#method.with_gov
[with_storage]:
https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.AppBuilder.html#method.with_storage
[addr_make]:
https://docs.rs/cosmwasm-std/latest/cosmwasm_std/testing/struct.MockApi.html#method.addr_make
[MockStorage]: https://docs.rs/cosmwasm-std/latest/cosmwasm_std/testing/type.MockStorage.html
[storage]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.App.html#method.storage
[storage_mut]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.App.html#method.storage_mut

# `AppBuilder`

Expand Down Expand Up @@ -294,7 +299,102 @@ You can find more usage examples of the built-in governance modules in the

## `with_storage`

(WIP)
By default, **`MultiTest`** uses [`MockStorage{:rust}`][MockStorage], which is provided by the
CosmWasm library. [`MockStorage{:rust}`][MockStorage] is an in-memory storage that does not persist
data beyond the test execution. Any values stored in it during testing are lost once the test
completes.

To use the default storage, simply initialize a chain with the default settings, as shown in the
following code snippet. After initialization, [`App{:rust}`][App] provides two methods to access the
storage: [`storage{:rust}`][storage] and [`storage_mut{:rust}`][storage_mut]. The former is used for
reading the storage, while the latter allows both reading and writing.

```rust showLineNumbers {4} /storage_mut()/ /storage()/
use cosmwasm_std::Storage;
use cw_multi_test::{no_init, AppBuilder};

let mut app = AppBuilder::default().build(no_init);

let key = b"key";
let value = b"value";

app.storage_mut().set(key, value);

assert_eq!(value, app.storage().get(key).unwrap().as_slice());
```

You can also explicitly provide a [`MockStorage{:rust}`][MockStorage] instance to the
[`with_storage{:rust}`][with_storage] method of [`AppBuilder{:rust}`][AppBuilder]. The example below
achieves the same result as the previous one.

```rust showLineNumbers {1,6} /storage_mut()/ /storage()/
use cosmwasm_std::testing::MockStorage;
use cosmwasm_std::Storage;
use cw_multi_test::{no_init, AppBuilder};

let mut app = AppBuilder::default()
.with_storage(MockStorage::new())
.build(no_init);

let key = b"key";
let value = b"value";

app.storage_mut().set(key, value);

assert_eq!(value, app.storage().get(key).unwrap().as_slice());
```

Initializing a chain with a [`MockStorage{:rust}`][MockStorage] instance using the
[`with_storage{:rust}`][with_storage] method of [`AppBuilder{:rust}`][AppBuilder] allows for
sophisticated storage initialization before the chain starts. A simplified example is shown below.
In lines 8-9 the storage is created and initialized, then passed to `with_storage{:rust}` method in
line 11. The initialization code in line 9 can of course be more complex in your test case.

```rust showLineNumbers {8,9,11} /with_storage/
use cosmwasm_std::testing::MockStorage;
use cosmwasm_std::Storage;
use cw_multi_test::{no_init, AppBuilder};

let key = b"key";
let value = b"value";

let mut storage = MockStorage::new();
storage.set(key, value);

let app = AppBuilder::default().with_storage(storage).build(no_init);

assert_eq!(value, app.storage().get(key).unwrap().as_slice());
```

It is worth noting that the same initialization can be implemented directly in a callback function
passed to [`build{:rust}`][build] method of [`AppBuilder{:rust}`][AppBuilder] as shown in the
following example:

```rust showLineNumbers {11} /build/
use cosmwasm_std::testing::MockStorage;
use cosmwasm_std::Storage;
use cw_multi_test::AppBuilder;

let key = b"key";
let value = b"value";

let app = AppBuilder::default()
.with_storage(MockStorage::new())
.build(|router, api, storage| {
storage.set(key, value);
});

assert_eq!(value, app.storage().get(key).unwrap().as_slice());
```

<Callout>
In the examples above, to keep the simple, we accessed the storage directly and focused on the chain
initialization part involving the `with_storage{:rust}` method of `AppBuilder{:rust}`.
Please note, that inside smart contract code, the storage used by the chain should be accessed through
libraries such as [Storey](/storey) and [StoragePlus](/cw-storage-plus).
</Callout>

You can find additional information about storage in [Storage](storage) chapter.

## `with_wasm`

Expand Down
39 changes: 26 additions & 13 deletions src/pages/cw-multi-test/features.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,19 @@
tags: ["multitest", "features"]
---

[mock_env_block]: https://docs.rs/cosmwasm-std/latest/cosmwasm_std/testing/fn.mock_env.html
[MockApi]: https://docs.rs/cosmwasm-std/latest/cosmwasm_std/testing/struct.MockApi.html
[MockStorage]: https://docs.rs/cosmwasm-std/latest/cosmwasm_std/testing/type.MockStorage.html
[BankKeeper]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.BankKeeper.html
[StakeKeeper]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.StakeKeeper.html
[DistributionKeeper]:
https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.DistributionKeeper.html
[GovFailingModule]: https://docs.rs/cw-multi-test/latest/cw_multi_test/type.GovFailingModule.html
[StargateFailing]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.StargateFailing.html
[WasmKeeper]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.WasmKeeper.html
[FailingModule]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.FailingModule.html
[IbcFailingModule]: https://docs.rs/cw-multi-test/latest/cw_multi_test/type.IbcFailingModule.html

# Features

## Features summary
Expand All @@ -15,19 +28,19 @@ you can provide your own, using `AppBuilder`'s function listed in **AppBuilder&n
column. Names of **`MultiTest`** feature flags required to enable specific functionality are shown
in the column **Feature&nbsp;flag**.

| Feature | Default<br/>implementation | Feature<br/>flag | AppBuilder<br/>constructor | Functionality |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------- | :--------------: | ---------------------------------------------------- | -------------------------------------------------- |
| [Blocks](blocks) | [`mock_env().block{:rust}`](https://docs.rs/cosmwasm-std/latest/cosmwasm_std/testing/fn.mock_env.html) | | [`with_block`](app-builder#with_block) | Operations on blocks. |
| [Api](api) | [`MockApi{:rust}`](https://docs.rs/cosmwasm-std/latest/cosmwasm_std/testing/struct.MockApi.html) | | [`with_api`](app-builder#with_api) | Access to CosmWasm API. |
| Storage | [`MockStorage{:rust}`](https://docs.rs/cosmwasm-std/latest/cosmwasm_std/testing/type.MockStorage.html) | | [`with_storage`](app-builder#with_storage) | Access to storage. |
| Bank | [`BankKeeper{:rust}`](https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.BankKeeper.html) | | [`with_bank`](app-builder#with_bank) | Interactions with **Bank** module. |
| Staking | [`StakeKeeper{:rust}`](https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.StakeKeeper.html) | `staking` | [`with_staking`](app-builder#with_staking) | Interactions with **Staking** module. |
| Distribution | [`DistributionKeeper{:rust}`](https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.DistributionKeeper.html) | `staking` | [`with_distribution`](app-builder#with_distribution) | Interactions with **Distribution** module. |
| [Governance](governance) | [`GovFailingModule{:rust}`](https://docs.rs/cw-multi-test/latest/cw_multi_test/type.GovFailingModule.html) | | [`with_gov`](app-builder#with_gov) | Interactions with **Governance** module. |
| Stargate | [`StargateFailing{:rust}`](https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.StargateFailing.html) | `stargate` | [`with_stargate`](app-builder#with_stargate) | Operations using `Stargate` and/or `Any` messages. |
| Wasm | [`WasmKeeper{:rust}`](https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.WasmKeeper.html) | | [`with_wasm`](app-builder#with_wasm) | Interactions with **Wasm** module. |
| Custom | [`FailingModule{:rust}`](https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.FailingModule.html) | | [`new_custom`](app-builder#new_custom) | Operations using custom module. |
| IBC | [`IbcFailingModule{:rust}`](https://docs.rs/cw-multi-test/latest/cw_multi_test/type.IbcFailingModule.html) | `stargate` | [`with_ibc`](app-builder#with_ibc) | Inter-blockchain communication operations. |
| Feature | Default<br/>implementation | Feature<br/>flag | AppBuilder<br/>constructor | Functionality |
| ------------------ | ------------------------------------------------- | :--------------: | ---------------------------------------------------- | -------------------------------------------------- |
| [Blocks](blocks) | [`mock_env().block{:rust}`][mock_env_block] | | [`with_block`](app-builder#with_block) | Operations on blocks. |
| [Api](api) | [`MockApi{:rust}`][MockApi] | | [`with_api`](app-builder#with_api) | Access to CosmWasm API. |
| [Storage](storage) | [`MockStorage{:rust}`][MockStorage] | | [`with_storage`](app-builder#with_storage) | Access to storage. |
| Bank | [`BankKeeper{:rust}`][BankKeeper] | | [`with_bank`](app-builder#with_bank) | Interactions with **Bank** module. |
| Staking | [`StakeKeeper{:rust}`][StakeKeeper] | `staking` | [`with_staking`](app-builder#with_staking) | Interactions with **Staking** module. |
| Distribution | [`DistributionKeeper{:rust}`][DistributionKeeper] | `staking` | [`with_distribution`](app-builder#with_distribution) | Interactions with **Distribution** module. |
| Governance | [`GovFailingModule{:rust}`][GovFailingModule] | | [`with_gov`](app-builder#with_gov) | Interactions with **Governance** module. |
| Stargate | [`StargateFailing{:rust}`][StargateFailing] | `stargate` | [`with_stargate`](app-builder#with_stargate) | Operations using `Stargate` and/or `Any` messages. |
| Wasm | [`WasmKeeper{:rust}`][WasmKeeper] | | [`with_wasm`](app-builder#with_wasm) | Interactions with **Wasm** module. |
| Custom | [`FailingModule{:rust}`][FailingModule] | | [`new_custom`](app-builder#new_custom) | Operations using custom module. |
| IBC | [`IbcFailingModule{:rust}`][IbcFailingModule] | `stargate` | [`with_ibc`](app-builder#with_ibc) | Inter-blockchain communication operations. |

## Feature flags summary

Expand Down
Loading

0 comments on commit 1eaec6e

Please sign in to comment.