Document vm.mockCalls (#1325)

* Document vm.mockCalls

* Add mockCall and mockCalls with `msg.value` param to cheatcodes readme

* Add example in mockCalls for mocking with msg.value

Author: Tudmotu

src/SUMMARY.md

@@ -422,6 +422,7 @@
       - [`setNonce`](./cheatcodes/set-nonce.md)
       - [`getNonce`](./cheatcodes/get-nonce.md)
       - [`mockCall`](./cheatcodes/mock-call.md)
+      - [`mockCalls`](./cheatcodes/mock-calls.md)
       - [`mockCallRevert`](./cheatcodes/mock-call-revert.md)
       - [`mockFunction`](./cheatcodes/mock-function.md)
       - [`clearMockedCalls`](./cheatcodes/clear-mocked-calls.md)

src/cheatcodes/README.md

@@ -307,6 +307,20 @@ interface CheatCodes {
     // function will be mocked.
     function mockCall(address, bytes calldata, bytes calldata) external;
 
+    /// Mocks a call to an address with a specific `msg.value`, returning specified data.
+    /// Calldata match takes precedence over `msg.value` in case of ambiguity.
+    function mockCall(address, uint256, bytes calldata, bytes calldata) external;
+
+    // Mocks multiple call to an address, returning specified data for each call.
+    //
+    // Calldata can either be strict or a partial match, e.g. if you only
+    // pass a Solidity selector to the expected calldata, then the entire Solidity
+    // function will be mocked.
+    function mockCalls(address, bytes calldata, bytes[] calldata) external;
+
+    /// Mocks multiple calls to an address with a specific `msg.value`, returning specified data for each call.
+    function mockCalls(address, uint256, bytes calldata, bytes[] calldata) external;
+
     // Reverts a call to an address, returning the specified error
     //
     // Calldata can either be strict or a partial match, e.g. if you only

src/cheatcodes/environment.md

@@ -21,6 +21,7 @@
 - [`setNonce`](./set-nonce.md)
 - [`getNonce`](./get-nonce.md)
 - [`mockCall`](./mock-call.md)
+- [`mockCalls`](./mock-calls.md)
 - [`mockCallRevert`](./mock-call-revert.md)
 - [`mockFunction`](./mock-function.md)
 - [`clearMockedCalls`](./clear-mocked-calls.md)

src/cheatcodes/mock-calls.md

@@ -0,0 +1,75 @@
+## `mockCalls`
+
+### Signature
+
+```solidity
+function mockCalls(address where, bytes calldata data, bytes[] calldata retdata) external;
+```
+
+```solidity
+function mockCalls(
+    address where,
+    uint256 value,
+    bytes calldata data,
+    bytes[] calldata retdata
+) external;
+```
+
+### Description
+
+Mocks all calls to an address `where` if the call data either strictly or loosely
+matches `data` and returns different data for each call based on the `retdata`
+array values.
+
+See [`mockCall`](./mock-call.md) for more information on mocking calls and
+matching precedence.
+
+> ℹ️ **Note**
+>
+> Any invocation of the mocked call beyond the number of elements in `retdata`
+> will receive the last `retdata` element in response. `clearMockedCalls` can be
+> called to clear the mock
+
+### Examples
+
+Mocking multiple `balanceOf(address)` calls:
+
+```solidity
+function testMockCall() public {
+    bytes[] memory mocks = new bytes[](2);
+    mocks[0] = abi.encode(2 ether);
+    mocks[1] = abi.encode(1 ether);
+
+    vm.mockCalls(
+        address(0),
+        abi.encodeWithSelector(IERC20.balanceOf.selector, address(1)),
+        mocks
+    );
+
+    assertEq(IERC20(address(0)).balanceOf(address(1)), 2 ether);
+    assertEq(IERC20(address(0)).balanceOf(address(1)), 1 ether);
+}
+```
+
+Mocking multiple calls with `msg.value`:
+
+```solidity
+function testMockCallsWithMsgValue() public {
+    bytes[] memory mocks = new bytes[](2);
+    mocks[0] = abi.encode(2 ether);
+    mocks[1] = abi.encode(1 ether);
+
+    vm.mockCalls(
+        address(0),
+        1 ether,
+        abi.encodeWithSelector(DexPool.swapETHForToken.selector),
+        mocks
+    );
+
+    uint tokenAmount1 = DexPool(address(0)).swapETHForToken{value: 1 ether}();
+    uint tokenAmount2 = DexPool(address(0)).swapETHForToken{value: 1 ether}();
+
+    assertEq(tokenAmount1, 2 ether);
+    assertEq(tokenAmount2, 1 ether);
+}
+```