Started test environement specific documentation

Author: Kayanski

cw-orch/examples/mock_test.rs

@@ -1,20 +1,27 @@
-use cosmwasm_std::Addr;
+use std::str::FromStr;
+
+use cosmwasm_std::{coins, Addr, BlockInfo, Decimal, Timestamp};
 
 use counter_contract::{
     contract::CounterContract,
     msg::{ExecuteMsg, GetCountResponse, InstantiateMsg, QueryMsg},
 };
-use cw_orch::prelude::{CwOrchExecute, CwOrchInstantiate, CwOrchQuery, CwOrchUpload, Mock};
+use cw_orch::prelude::{CallAs, CwOrchExecute, CwOrchInstantiate, CwOrchQuery, CwOrchUpload, Mock};
 
+/// This example shows how to create and use the cw-multi-test mock environment
 pub fn main() {
+    // ANCHOR: mock_creation
     let sender = Addr::unchecked("juno16g2rahf5846rxzp3fwlswy08fz8ccuwk03k57y");
 
     let mock = Mock::new(&sender);
+    // ANCHOR_END: mock_creation
 
+    // ANCHOR: mock_usage
     let contract_counter = CounterContract::new("mock:contract_counter", mock);
 
     let upload_res = contract_counter.upload();
     upload_res.unwrap();
+    // ANCHOR_END: mock_usage
 
     let init_res = contract_counter.instantiate(&InstantiateMsg { count: 0 }, Some(&sender), None);
     init_res.unwrap();
@@ -25,3 +32,52 @@ pub fn main() {
     let query_res = contract_counter.query::<GetCountResponse>(&QueryMsg::GetCount {});
     assert_eq!(query_res.unwrap().count, 1);
 }
+
+// This is used for documentation only
+// This is actually only used to avoid having the `mut` keyword inside the mock_usage anchor (only necessary for set_sender)
+pub fn customize() {
+    let sender = Addr::unchecked("juno16g2rahf5846rxzp3fwlswy08fz8ccuwk03k57y");
+
+    let mock = Mock::new(&sender);
+
+    let mut contract_counter = CounterContract::new("mock:contract_counter", mock.clone());
+
+    // ANCHOR: mock_customization
+    let new_sender = Addr::unchecked("entirely-new-sender");
+    mock.set_balance(&new_sender, coins(100_000, "ujunox"))
+        .unwrap();
+
+    // Reuploads as the new sender
+    contract_counter.call_as(&new_sender).upload().unwrap();
+
+    // Here the contract_counter sender is again `sender`
+
+    // Sets the new_sender as the definite sender
+    contract_counter.set_sender(&new_sender);
+
+    // From now on the contract_counter sender is `new_sender`
+    // ANCHOR_END: mock_customization
+
+    // ANCHOR: deep_mock_customization
+    mock.app
+        .borrow_mut()
+        .init_modules(|router, api, storage| {
+            router.staking.add_validator(
+                api,
+                storage,
+                &BlockInfo {
+                    height: 16736,
+                    time: Timestamp::from_seconds(13345762376),
+                    chain_id: "juno-1".to_string(),
+                },
+                cosmwasm_std::Validator {
+                    address: "new-validator-address".to_string(),
+                    commission: Decimal::from_str("0.5").unwrap(), // Greedy validator
+                    max_commission: Decimal::from_str("1").unwrap(), // Dangerous validator
+                    max_change_rate: Decimal::from_str("1").unwrap(), // Very dangerous validator
+                },
+            )
+        })
+        .unwrap();
+    // ANCHOR_END: deep_mock_customization
+}

docs/src/SUMMARY.md

@@ -12,6 +12,12 @@
   - [Scripting](./single_contract/scripting.md)
   - [Integration Tests](./single_contract/integration-tests.md)
 
+- [Integrations](./integrations/index.md)
+  - [Daemon (Live Chains)](./integrations/daemon.md)
+  - [Cw Multi Test](./integrations/cw-multi-test.md)
+  - [Osmosis Test Tube](./integrations/osmosis-test-tube.md)
+  - [Starship](./integrations/starship.md)
+
 
 - [Workspace](./workspace/index.md)
   - [Structure]()

docs/src/integrations/cw-multi-test.md

@@ -0,0 +1,55 @@
+# CW Multi Test
+
+Cw Multi Test is a rust-based test framework that allows developers to test  for multi-contract interactions without having to dispatch messages, storage and other variables themselves. With cw-orchestrator, most of the `cw-multi-test` logic is abstracted away, but you can still [learn more about the framework here](https://github.com/CosmWasm/cw-multi-test).
+
+## Quick Start
+
+The cw-multi-test integration comes at no extra cost for the developer. Creating a test environement in cw-orchestrator that leverages cw-multi-test goes along the lines of : 
+
+```rust,ignore
+    use cw_orch::prelude::*;
+    use cosmwasm_std::Addr;
+{{#include ../../../cw-orch/examples/mock_test.rs:mock_creation}}
+```
+
+> **_NOTE:_** When using cw-multi-test, the addresses are not validated like on a live chain. Therefore, you can use any string format for designating addresses. For instance,`Addr::unchecked("my-first-sender")` is a valid cw-multi-test address.
+
+> **_NOTE:_** When using cw-multi-test, no gas fees are charges to the sender address.
+
+## Interacting with contracts
+
+You can then use the resulting `Mock` variable to interact with your [contracts](../single_contract/index.md): 
+
+```rust,ignore
+{{#include ../../../cw-orch/examples/mock_test.rs:mock_usage}}
+```
+
+When executing contracts in a cw-multi-test environment, the messages and sub-messages sent along the Response of an endpoint, will be executed as well.
+This environment mocks the actual on-chain execution exactly 
+
+> If you are using the customizable Interface Macro, you will need to have implemented the `wrapper` function for interacting the the `Mock` environment. This function wil allow you to "connect" your contract endpoints to your `Contract` struct [See the dedicated page for more details](../single_contract/interfaces.md#customizable-interface-macro).
+
+
+> **_NOTE:_** Keep in mind that cw-multi-test is based solely in rust and that a lot of actual blockchain modules are not mocked in the environment. The main cosmos modules are there (Bank, Staking), but some very useful ones (tokenfactory, ibc) as well as Stargate messages are not supported by the environment.
+
+## Cloning
+
+When cloning a cw_multi_test environment, you are not cloning the entire environment, but instead you are creating a new `Mock` typed variable with the same underlying `cw_multi_test::App` object reference. This is useful for objects that require to pass the chain as an object rather than by reference.
+The underlying `cw_multi_test::App` object is however not clonable.
+
+## Additional tools
+
+The `Mock` test environment allows you to change application variables (such as the balance of an account) using wrappers around the underlying `cw_multi_test::App` object. Here are some examples of those wrappers in context : 
+
+
+```rust,ignore
+{{#include ../../../cw-orch/examples/mock_test.rs:mock_customization}}
+```
+
+## Additional customization
+
+As we don't provide wrappers around each and every functionality that cw-multi-test provides, you can also customize the underyling `cw_multi_test::App`object to your specific needs. In the following example, we create a new validator in the test environment : 
+
+```rust,ignore
+{{#include ../../../cw-orch/examples/mock_test.rs:deep_mock_customization}}
+````

docs/src/integrations/daemon.md

@@ -0,0 +1 @@
+# Integrations

docs/src/integrations/index.md

@@ -11,7 +11,10 @@ cw-orchestrator is an advanced testing and deployment tool for CosmWasm smart-co
 
 ## Features
 
-- **Testing**: cw-orchestrator provides a testing framework that makes it easy to write tests for CosmWasm contracts. It does this by providing a testing environment that mimics the behavior of a CosmWasm blockchain. This allows you to write tests that interact with your contract in the same way that it would be interacted with on a real blockchain. These kinds of tests allow developers to more easily test contract-to-contract interactions without having to deal with the overhead of running a local node. The testing framework also provides a number of utilities that make it easy to write tests for CosmWasm contracts. These utilities include the ability to easily set and query balances, set block height/time and more. Additionally by creating a wrapper interface around a project's deployment developers can share their testing infrastructure with other developers, allowing them to easily test how their contracts interact with the project.
+- **Testing**: cw-orchestrator provides a testing framework that makes it easy to write tests for CosmWasm contracts. It does this by providing a testing environment that mimics the behavior of a CosmWasm blockchain. This allows you to write tests that interact with your contract in the same way that it would be interacted with on a real blockchain. These kinds of tests allow developers to more easily test contract-to-contract interactions without having to deal with the overhead of running a local node. The testing framework also provides a number of utilities that make it easy to write tests for CosmWasm contracts. These utilities include the ability to easily set and query balances, set block height/time and more. Additionally by creating a wrapper interface around a project's deployment developers can share their testing infrastructure with other developers, allowing them to easily test how their contracts interact with the project. The testing framework supported by cw-orchestrator include : 
+  - **[Cw-Multi-Test](./integrations/cw-multi-test.md)**
+  - **[Starship](./integrations/starship.md)**
+  - **[Osmosis-test-tube](./integrations/osmosis-test-tube.md)**
 
 - **Deployment**: cw-orchestrator also provides the ability to deploy to real networks. It does this by providing an easy to use interface to a blockchain node that can be used to submit transactions, query state and inspect transaction results.