Skip to content

Commit 89e963b

Browse files
committed
docs: add mock_call_when cheatcode
1 parent 39213ba commit 89e963b

File tree

4 files changed

+48
-0
lines changed

4 files changed

+48
-0
lines changed

CHANGELOG.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1212
#### Added
1313

1414
- Added a suggestion for using the `--max-n-steps` flag when the Cairo VM returns the error: `Could not reach the end of the program. RunResources has no remaining steps`.
15+
- `mock_call_when`, `start_mock_call_when`, `stop_mock_call_when` cheatcodes.
1516

1617
### Forge
1718

docs/src/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,7 @@
9494
* [fee_data_availability_mode](appendix/cheatcodes/fee_data_availability_mode.md)
9595
* [account_deployment_data](appendix/cheatcodes/account_deployment_data.md)
9696
* [mock_call](appendix/cheatcodes/mock_call.md)
97+
* [mock_call_when](appendix/cheatcodes/mock_call_when.md)
9798
* [get_class_hash](appendix/cheatcodes/get_class_hash.md)
9899
* [replace_bytecode](appendix/cheatcodes/replace_bytecode.md)
99100
* [l1_handler](appendix/cheatcodes/l1_handler.md)

docs/src/appendix/cheatcodes.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@
44
- [`mock_call`](cheatcodes/mock_call.md#mock_call) - mocks a number of contract calls to an entry point
55
- [`start_mock_call`](cheatcodes/mock_call.md#start_mock_call) - mocks contract call to an entry point
66
- [`stop_mock_call`](cheatcodes/mock_call.md#stop_mock_call) - cancels the `mock_call` / `start_mock_call` for an entry point
7+
- [`mock_call_when`](cheatcodes/mock_call_when.md#mock_call_when) - mocks a number of contract calls to an entry point for a given call data
8+
- [`start_mock_call_when`](cheatcodes/mock_call_when.md#start_mock_call_when) - mocks contract call to an entry point for a given call data
9+
- [`stop_mock_call_when`](cheatcodes/mock_call_when.md#stop_mock_call_when) - cancels the `mock_call_when` / `start_mock_call_when` for an entry point
710
- [`get_class_hash`](cheatcodes/get_class_hash.md) - retrieves a class hash of a contract
811
- [`replace_bytecode`](cheatcodes/replace_bytecode.md) - replace the class hash of a contract
912
- [`l1_handler`](cheatcodes/l1_handler.md) - executes a `#[l1_handler]` function to mock a message arriving from Ethereum
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# `mock_call_when`
2+
3+
Cheatcodes mocking contract entry point calls:
4+
5+
## `MockCallData`
6+
7+
```rust
8+
pub enum MockCallData {
9+
Any,
10+
Values: Span<felt252>,
11+
}
12+
```
13+
14+
`MockCallData` is an enum used to specify for which call data the contract entry point will be mocked.
15+
- `Any` mock the contract entry point for any call data.
16+
- `Values` mock the contract entry point only for this call data.
17+
18+
## `mock_call_when`
19+
> `fn mock_call_when<T, impl TSerde: serde::Serde<T>, impl TDestruct: Destruct<T>>(
20+
> contract_address: ContractAddress, function_selector: felt252, call_data: MockCallData, ret_data: T, n_times: u32
21+
> )`
22+
23+
Mocks contract call to a `function_selector` of a contract at the given address, with the given call data, for `n_times` first calls that are made
24+
to the contract.
25+
A call to function `function_selector` will return data provided in `ret_data` argument.
26+
An address with no contract can be mocked as well.
27+
An entrypoint that is not present on the deployed contract is also possible to mock.
28+
Note that the function is not meant for mocking internal calls - it works only for contract entry points.
29+
30+
## `start_mock_call_when`
31+
> `fn start_mock_call<T, impl TSerde: serde::Serde<T>, impl TDestruct: Destruct<T>>(
32+
> contract_address: ContractAddress, function_selector: felt252, call_data: MockCallData, ret_data: T
33+
> )`
34+
35+
Mocks contract call to a `function_selector` of a contract at the given address, with the given call data, indefinitely.
36+
See `mock_call_when` for comprehensive definition of how it can be used.
37+
38+
39+
### `stop_mock_call_when`
40+
41+
> `fn stop_mock_call_when(contract_address: ContractAddress, function_selector: felt252, call_data: MockCallData)`
42+
43+
Cancels the `mock_call_when` / `start_mock_call_when` for the function `function_selector` of a contract at the given addressn with the given call data

0 commit comments

Comments
 (0)