Skip to content

Commit 1eaec6e

Browse files
DariuszDeptaDariuszDepta
authored
Added documentation for storage (#245)
2 parents 82514f0 + ff2f0c7 commit 1eaec6e

File tree

4 files changed

+356
-15
lines changed

4 files changed

+356
-15
lines changed

‎src/pages/cw-multi-test/api.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ can use any implementation of the [Api][Api] trait in your tests by utilizing th
5555

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

58-
| Methods of [Api][Api] trait | Description |
58+
| Methods of [Api] trait | Description |
5959
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
6060
| [`addr_canonicalize{:rust}`][addr_canonicalize] | Converts a human-readable address into its canonical binary representation. |
6161
| [`addr_humanize{:rust}`][addr_humanize] | Converts a canonical address into human-readable address. |

‎src/pages/cw-multi-test/app-builder.mdx

Lines changed: 101 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,13 @@ import { Callout } from "nextra/components";
2222
https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.AppBuilder.html#method.with_block
2323
[with_gov]:
2424
https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.AppBuilder.html#method.with_gov
25+
[with_storage]:
26+
https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.AppBuilder.html#method.with_storage
2527
[addr_make]:
2628
https://docs.rs/cosmwasm-std/latest/cosmwasm_std/testing/struct.MockApi.html#method.addr_make
29+
[MockStorage]: https://docs.rs/cosmwasm-std/latest/cosmwasm_std/testing/type.MockStorage.html
30+
[storage]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.App.html#method.storage
31+
[storage_mut]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.App.html#method.storage_mut
2732

2833
# `AppBuilder`
2934

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

295300
## `with_storage`
296301

297-
(WIP)
302+
By default, **`MultiTest`** uses [`MockStorage{:rust}`][MockStorage], which is provided by the
303+
CosmWasm library. [`MockStorage{:rust}`][MockStorage] is an in-memory storage that does not persist
304+
data beyond the test execution. Any values stored in it during testing are lost once the test
305+
completes.
306+
307+
To use the default storage, simply initialize a chain with the default settings, as shown in the
308+
following code snippet. After initialization, [`App{:rust}`][App] provides two methods to access the
309+
storage: [`storage{:rust}`][storage] and [`storage_mut{:rust}`][storage_mut]. The former is used for
310+
reading the storage, while the latter allows both reading and writing.
311+
312+
```rust showLineNumbers {4} /storage_mut()/ /storage()/
313+
use cosmwasm_std::Storage;
314+
use cw_multi_test::{no_init, AppBuilder};
315+
316+
let mut app = AppBuilder::default().build(no_init);
317+
318+
let key = b"key";
319+
let value = b"value";
320+
321+
app.storage_mut().set(key, value);
322+
323+
assert_eq!(value, app.storage().get(key).unwrap().as_slice());
324+
```
325+
326+
You can also explicitly provide a [`MockStorage{:rust}`][MockStorage] instance to the
327+
[`with_storage{:rust}`][with_storage] method of [`AppBuilder{:rust}`][AppBuilder]. The example below
328+
achieves the same result as the previous one.
329+
330+
```rust showLineNumbers {1,6} /storage_mut()/ /storage()/
331+
use cosmwasm_std::testing::MockStorage;
332+
use cosmwasm_std::Storage;
333+
use cw_multi_test::{no_init, AppBuilder};
334+
335+
let mut app = AppBuilder::default()
336+
.with_storage(MockStorage::new())
337+
.build(no_init);
338+
339+
let key = b"key";
340+
let value = b"value";
341+
342+
app.storage_mut().set(key, value);
343+
344+
assert_eq!(value, app.storage().get(key).unwrap().as_slice());
345+
```
346+
347+
Initializing a chain with a [`MockStorage{:rust}`][MockStorage] instance using the
348+
[`with_storage{:rust}`][with_storage] method of [`AppBuilder{:rust}`][AppBuilder] allows for
349+
sophisticated storage initialization before the chain starts. A simplified example is shown below.
350+
In lines 8-9 the storage is created and initialized, then passed to `with_storage{:rust}` method in
351+
line 11. The initialization code in line 9 can of course be more complex in your test case.
352+
353+
```rust showLineNumbers {8,9,11} /with_storage/
354+
use cosmwasm_std::testing::MockStorage;
355+
use cosmwasm_std::Storage;
356+
use cw_multi_test::{no_init, AppBuilder};
357+
358+
let key = b"key";
359+
let value = b"value";
360+
361+
let mut storage = MockStorage::new();
362+
storage.set(key, value);
363+
364+
let app = AppBuilder::default().with_storage(storage).build(no_init);
365+
366+
assert_eq!(value, app.storage().get(key).unwrap().as_slice());
367+
```
368+
369+
It is worth noting that the same initialization can be implemented directly in a callback function
370+
passed to [`build{:rust}`][build] method of [`AppBuilder{:rust}`][AppBuilder] as shown in the
371+
following example:
372+
373+
```rust showLineNumbers {11} /build/
374+
use cosmwasm_std::testing::MockStorage;
375+
use cosmwasm_std::Storage;
376+
use cw_multi_test::AppBuilder;
377+
378+
let key = b"key";
379+
let value = b"value";
380+
381+
let app = AppBuilder::default()
382+
.with_storage(MockStorage::new())
383+
.build(|router, api, storage| {
384+
storage.set(key, value);
385+
});
386+
387+
assert_eq!(value, app.storage().get(key).unwrap().as_slice());
388+
```
389+
390+
<Callout>
391+
In the examples above, to keep the simple, we accessed the storage directly and focused on the chain
392+
initialization part involving the `with_storage{:rust}` method of `AppBuilder{:rust}`.
393+
Please note, that inside smart contract code, the storage used by the chain should be accessed through
394+
libraries such as [Storey](/storey) and [StoragePlus](/cw-storage-plus).
395+
</Callout>
396+
397+
You can find additional information about storage in [Storage](storage) chapter.
298398

299399
## `with_wasm`
300400

‎src/pages/cw-multi-test/features.mdx

Lines changed: 26 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,19 @@
22
tags: ["multitest", "features"]
33
---
44

5+
[mock_env_block]: https://docs.rs/cosmwasm-std/latest/cosmwasm_std/testing/fn.mock_env.html
6+
[MockApi]: https://docs.rs/cosmwasm-std/latest/cosmwasm_std/testing/struct.MockApi.html
7+
[MockStorage]: https://docs.rs/cosmwasm-std/latest/cosmwasm_std/testing/type.MockStorage.html
8+
[BankKeeper]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.BankKeeper.html
9+
[StakeKeeper]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.StakeKeeper.html
10+
[DistributionKeeper]:
11+
https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.DistributionKeeper.html
12+
[GovFailingModule]: https://docs.rs/cw-multi-test/latest/cw_multi_test/type.GovFailingModule.html
13+
[StargateFailing]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.StargateFailing.html
14+
[WasmKeeper]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.WasmKeeper.html
15+
[FailingModule]: https://docs.rs/cw-multi-test/latest/cw_multi_test/struct.FailingModule.html
16+
[IbcFailingModule]: https://docs.rs/cw-multi-test/latest/cw_multi_test/type.IbcFailingModule.html
17+
518
# Features
619

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

18-
| Feature | Default<br/>implementation | Feature<br/>flag | AppBuilder<br/>constructor | Functionality |
19-
| ------------------------ | ---------------------------------------------------------------------------------------------------------------- | :--------------: | ---------------------------------------------------- | -------------------------------------------------- |
20-
| [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. |
21-
| [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. |
22-
| Storage | [`MockStorage{:rust}`](https://docs.rs/cosmwasm-std/latest/cosmwasm_std/testing/type.MockStorage.html) | | [`with_storage`](app-builder#with_storage) | Access to storage. |
23-
| 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. |
24-
| 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. |
25-
| 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. |
26-
| [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. |
27-
| 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. |
28-
| 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. |
29-
| 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. |
30-
| 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. |
31+
| Feature | Default<br/>implementation | Feature<br/>flag | AppBuilder<br/>constructor | Functionality |
32+
| ------------------ | ------------------------------------------------- | :--------------: | ---------------------------------------------------- | -------------------------------------------------- |
33+
| [Blocks](blocks) | [`mock_env().block{:rust}`][mock_env_block] | | [`with_block`](app-builder#with_block) | Operations on blocks. |
34+
| [Api](api) | [`MockApi{:rust}`][MockApi] | | [`with_api`](app-builder#with_api) | Access to CosmWasm API. |
35+
| [Storage](storage) | [`MockStorage{:rust}`][MockStorage] | | [`with_storage`](app-builder#with_storage) | Access to storage. |
36+
| Bank | [`BankKeeper{:rust}`][BankKeeper] | | [`with_bank`](app-builder#with_bank) | Interactions with **Bank** module. |
37+
| Staking | [`StakeKeeper{:rust}`][StakeKeeper] | `staking` | [`with_staking`](app-builder#with_staking) | Interactions with **Staking** module. |
38+
| Distribution | [`DistributionKeeper{:rust}`][DistributionKeeper] | `staking` | [`with_distribution`](app-builder#with_distribution) | Interactions with **Distribution** module. |
39+
| Governance | [`GovFailingModule{:rust}`][GovFailingModule] | | [`with_gov`](app-builder#with_gov) | Interactions with **Governance** module. |
40+
| Stargate | [`StargateFailing{:rust}`][StargateFailing] | `stargate` | [`with_stargate`](app-builder#with_stargate) | Operations using `Stargate` and/or `Any` messages. |
41+
| Wasm | [`WasmKeeper{:rust}`][WasmKeeper] | | [`with_wasm`](app-builder#with_wasm) | Interactions with **Wasm** module. |
42+
| Custom | [`FailingModule{:rust}`][FailingModule] | | [`new_custom`](app-builder#new_custom) | Operations using custom module. |
43+
| IBC | [`IbcFailingModule{:rust}`][IbcFailingModule] | `stargate` | [`with_ibc`](app-builder#with_ibc) | Inter-blockchain communication operations. |
3144

3245
## Feature flags summary
3346

0 commit comments

Comments
 (0)