From 26253285db87b32660c34f040cccaf224b41b324 Mon Sep 17 00:00:00 2001
From: grandizzy <38490174+grandizzy@users.noreply.github.com>
Date: Wed, 28 Aug 2024 18:03:06 +0300
Subject: [PATCH] Docs for resetGasMetering and expectPartialRevert cheatcodes
 (#1265)

---
 src/SUMMARY.md                       |  1 +
 src/cheatcodes/environment.md        |  1 +
 src/cheatcodes/expect-revert.md      | 36 ++++++++++++++++++++++++++--
 src/cheatcodes/reset-gas-metering.md | 11 +++++++++
 4 files changed, 47 insertions(+), 2 deletions(-)
 create mode 100644 src/cheatcodes/reset-gas-metering.md

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index 4c65ba05e..02aef4802 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -418,6 +418,7 @@
       - [`startBroadcast`](./cheatcodes/start-broadcast.md)
       - [`stopBroadcast`](./cheatcodes/stop-broadcast.md)
       - [`pauseGasMetering`](./cheatcodes/pause-gas-metering.md)
+      - [`resetGasMetering`](./cheatcodes/reset-gas-metering.md)
       - [`resumeGasMetering`](./cheatcodes/resume-gas-metering.md)
       - [`txGasPrice`](./cheatcodes/tx-gas-price.md)
       - [`startStateDiffRecording`](./cheatcodes/start-state-diff-recording.md)
diff --git a/src/cheatcodes/environment.md b/src/cheatcodes/environment.md
index c43e00163..7d044e2b2 100644
--- a/src/cheatcodes/environment.md
+++ b/src/cheatcodes/environment.md
@@ -28,6 +28,7 @@
 - [`startBroadcast`](./start-broadcast.md)
 - [`stopBroadcast`](./stop-broadcast.md)
 - [`pauseGasMetering`](./pause-gas-metering.md)
+- [`resetGasMetering`](./reset-gas-metering.md)
 - [`resumeGasMetering`](./resume-gas-metering.md)
 - [`txGasPrice`](./tx-gas-price.md)
 - [`startStateDiffRecording`](./start-state-diff-recording.md)
diff --git a/src/cheatcodes/expect-revert.md b/src/cheatcodes/expect-revert.md
index 20223038b..486f2bab1 100644
--- a/src/cheatcodes/expect-revert.md
+++ b/src/cheatcodes/expect-revert.md
@@ -14,6 +14,10 @@ function expectRevert(bytes4 message) external;
 function expectRevert(bytes calldata message) external;
 ```
 
+```solidity
+function expectPartialRevert(bytes4 message) external;
+```
+
 ### Description
 
 If the **next call** does not revert with the expected data `message`, then `expectRevert` will.
@@ -22,12 +26,34 @@ After calling `expectRevert`, calls to other cheatcodes before the reverting cal
 
 This means, for example, we can call [`prank`](./prank.md) immediately before the reverting call.
 
-There are 3 signatures:
+There are 3 signatures for `expectRevert`:
 
 - **Without parameters**: Asserts that the next call reverts, regardless of the message.
-- **With `bytes4`**: Asserts that the next call reverts with the specified 4 bytes.
+- **With `bytes4`**: Asserts that the next call reverts with the specified 4 bytes and exact match of revert data.
 - **With `bytes`**: Asserts that the next call reverts with the specified bytes.
 
+and one signature for `expectPartialRevert`:
+- **`bytes4`**: Asserts that the next call reverts and the specified 4 bytes match the first 4 bytes of revert data.
+
+> ℹ️  **Note:**
+> 
+> Custom errors can have arguments that sometimes are difficult to calculate in a testing environment or they may be unrelated to the test at hand (e.g. a value computed in the internal function of a third-party contract). In such cases, `expectPartialRevert` can be used to ignore arguments and match only on the selector of custom error. For example, testing a function that reverts with `WrongNumber(uint256 number)` custom error:
+> ```solidity
+> function count() public {
+>     revert WrongNumber(0);
+> }
+> ```
+> should pass when using `expectPartialRevert`:
+> ```solidity
+> vm.expectPartialRevert(Counter.WrongNumber.selector);
+> counter.count();
+> ```
+> but fails if exact match expected:
+> ```solidity
+> vm.expectRevert(Counter.WrongNumber.selector);
+> counter.count();
+> ```
+
 > ⚠️ **Gotcha: Usage with low-level calls**
 >
 > Normally, a call that succeeds returns a status of `true` (along with any return data) and a call that reverts returns `false`.
@@ -104,6 +130,12 @@ function testMultipleExpectReverts() public {
 }
 ```
 
+To use `expectPartialRevert` with a custom [error type][error-type], use its selector.
+
+```solidity
+vm.expectRevert(CustomError.selector);
+```
+
 ### SEE ALSO
 
 Forge Standard Library
diff --git a/src/cheatcodes/reset-gas-metering.md b/src/cheatcodes/reset-gas-metering.md
new file mode 100644
index 000000000..b1bb2e174
--- /dev/null
+++ b/src/cheatcodes/reset-gas-metering.md
@@ -0,0 +1,11 @@
+## `resetGasMetering`
+
+### Signature
+
+```solidity
+function resetGasMetering() external;
+```
+
+### Description
+
+Resets gas metering to the gas limit of current execution frame (i.e. `gasleft()` will be restored to initial value).