Add global cheatcodes example and extend appendix (#2533)

<!-- Reference any GitHub issues resolved by this PR -->

Closes #2394 

## Introduced changes

<!-- A brief description of the changes -->

- Add example of global cheatcode usage in `Using cheatcodes` section
- Extend appendix with global cheatcodes reference

## Checklist

<!-- Make sure all of these are complete -->

- [x] Linked relevant issue
- [x] Updated relevant documentation
- [x] Added relevant tests
- [x] Performed self-review of the code
- [x] Added changes to `CHANGELOG.md`

---------

Co-authored-by: Jan Smółka <[email protected]>

docs/listings/snforge_overview/crates/using_cheatcodes/tests/caller_address.cairo

@@ -1,4 +1,5 @@
 pub mod failing;
 pub mod proper_use;
+pub mod proper_use_global;
 pub mod cancel;
 pub mod span;

docs/listings/snforge_overview/crates/using_cheatcodes/tests/caller_address/proper_use_global.cairo

@@ -0,0 +1,34 @@
+use snforge_std::{
+ declare, ContractClassTrait, DeclareResultTrait, start_cheat_caller_address_global,
+ stop_cheat_caller_address_global
+};
+use using_cheatcodes::{ICheatcodeCheckerDispatcher, ICheatcodeCheckerDispatcherTrait};
+
+#[test]
+fn call_and_invoke_global() {
+ let contract = declare("CheatcodeChecker").unwrap().contract_class();
+ let (contract_address_a, _) = contract.deploy(@array![]).unwrap();
+ let (contract_address_b, _) = contract.deploy(@array![]).unwrap();
+ let dispatcher_a = ICheatcodeCheckerDispatcher { contract_address: contract_address_a };
+ let dispatcher_b = ICheatcodeCheckerDispatcher { contract_address: contract_address_b };
+
+ let balance_a = dispatcher_a.get_balance();
+ let balance_b = dispatcher_b.get_balance();
+ assert_eq!(balance_a, 0);
+ assert_eq!(balance_b, 0);
+
+ // Change the caller address to 123, both targets a and b will be affected
+ // global cheatcodes work indefinitely until stopped
+ start_cheat_caller_address_global(123.try_into().unwrap());
+
+ dispatcher_a.increase_balance(100);
+ dispatcher_b.increase_balance(100);
+
+ let balance_a = dispatcher_a.get_balance();
+ let balance_b = dispatcher_b.get_balance();
+ assert_eq!(balance_a, 100);
+ assert_eq!(balance_b, 100);
+
+ // Cancel the cheat
+ stop_cheat_caller_address_global();
+}

docs/src/SUMMARY.md

@@ -66,6 +66,7 @@
  * [init](appendix/snforge/init.md)
  * [clean-cache](appendix/snforge/clean-cache.md)
 * [Cheatcodes Reference](appendix/cheatcodes.md)
+ * [Cheating Globally](appendix/cheatcodes/global.md)
  * [CheatSpan](appendix/cheatcodes/cheat_span.md)
  * [caller_address](appendix/cheatcodes/caller_address.md)
  * [block_number](appendix/cheatcodes/block_number.md)

docs/src/appendix/cheatcodes/global.md

@@ -0,0 +1,6 @@
+# Cheating Globally
+
+Cheatcodes which have `_global` suffix allow to change specific properties in blockchain state for all targets and for indefinite time span. Therefore, you don't pass the target address, nor the span.
+
+See the [Cheating Addresses Globally](../../testing/using-cheatcodes.md#cheating-addresses-globally) example.
+

docs/src/testing/using-cheatcodes.md

@@ -98,6 +98,15 @@ Tests: 0 passed, 1 failed, 0 skipped, 0 ignored, 4 filtered out
 
 We see that the second `increase_balance` fails since we cancelled the cheatcode.
 
+### Cheating Addresses Globally
+
+In case you want to cheat the caller address for all contracts, you can use the global cheatcode which has the `_global` suffix. Note, that we don't specify target, nor the span, because this cheatcode type works globally and indefinitely.
+For more see [Cheating Globally](../appendix/cheatcodes/global.md).
+
+```rust
+{{#include ../../listings/snforge_overview/crates/using_cheatcodes/tests/caller_address/proper_use_global.cairo}}
+```
+
 ### Cheating the Constructor
 
 Most of the cheatcodes like `cheat_caller_address`, `mock_call`, `cheat_block_timestamp`, `cheat_block_number`, `elect` do work in the constructor of the contracts.