feat(cheatcodes): Add vm.mockCalls to mock different return data for multiple calls

[Tudmotu]

Closes #7467

Motivation

Today, we can mock the return value of a function call by using mockCall. Sometimes, it is useful to mock the same call twice with different return values.

Consider the following function:

function failsafeArb (IERC20 token, IERC20 arbToken) public {
    uint initialBalance = token.balanceOf(address(this));
    doArbitrage(token, arbToken);
    uint finalBalance = token.balanceOf(address(this));
    require(finalBalance > initialBalance, 'arbitrage failed');
}

Both invocations of token.balanceOf() have the same calldata. This means we cannot use two different mockCall to test this behavior.

With mockCalls we would test it like so:

bytes[] retdata = new bytes[](2);
retdata[0] = abi.encode(100 ether);
retdata[1] = abi.encode(99 ether);
vm.mockCalls(
    address(token),
    abi.encodeWithSelector(
        IERC20.balanceOf.selector,
        address(testContract)
    ),
    retdata
);

vm.expectRevert('arbitrage failed');
testContract.failsafeArb(token, arbToken);

Solution

I changed Cheatcodes::mocked_calls to have a type of HashMap<Address, BTreeMap<MockCallDataContext, VecDeque<MockCallReturnData>>>, note the VecDeque<...>.

I then went in inspector.rs and modified the part which handles the mocked calls, to pop the front mock return data as long as the stack has more than one element. This kept backward-compatibility in such a way which minimized the amount of necessary changes.

Cheatcodes checklist

The checklist from the cheatcodes development docs:

• Add its Solidity definition(s) in cheatcodes/spec/src/vm.rs. Ensure that all structs and functions are documented, and that all function parameters are named. This will initially fail to compile because of the automatically generated match { ... } expression. This is expected, and will be fixed in the next step
• Implement the cheatcode in cheatcodes in its category's respective module. Follow the existing implementations as a guide.
• If a struct, enum, error, or event was added to Vm, update spec::Cheatcodes::new
• Update the JSON interface by running cargo cheats twice. This is expected to fail the first time that this is run after adding a new cheatcode; see JSON interface
• Write an integration test for the cheatcode in testdata/cheats/

[Tudmotu]

Opened draft PRs for Foundry Book and Forge-Std.

[zerosnacks]

Thanks for your PR! Implementation looks good, small note in foundry-rs/forge-std#615

[grandizzy]

lgtm, just a small comment. pending other reviews

[zerosnacks]

Thanks! LGTM - pending other reviewers

[grandizzy]

Thank you, lgtm

[DaniPopes]

Thanks!