feat: document gas snapshot cheatcodes (#1323)

* add gas snapshots, update state snapshots

* embed cheatcodes

* link to cheatcodes

* update description

Author: zerosnacks

src/SUMMARY.md

@@ -39,7 +39,8 @@
 - [Deploying and Verifying](./forge/deploying.md)
 - [Gas Tracking](./forge/gas-tracking.md)
   - [Gas Reports](./forge/gas-reports.md)
-  - [Gas Snapshots](./forge/gas-snapshots.md)
+  - [Gas Function Snapshots](./forge/gas-function-snapshots.md)
+  - [Gas Section Snapshots](./forge/gas-section-snapshots.md)
 - [Debugger](./forge/debugger.md)
 
 # Cast Overview
@@ -429,6 +430,8 @@
       - [`txGasPrice`](./cheatcodes/tx-gas-price.md)
       - [`startStateDiffRecording`](./cheatcodes/start-state-diff-recording.md)
       - [`stopAndReturnStateDiff`](./cheatcodes/stop-and-return-state-diff.md)
+      - [`snapshotState`](./cheatcodes/state-snapshots.md)
+      - [`snapshotGas`](./cheatcodes/gas-snapshots.md)
     - [Assertions](./cheatcodes/assertions.md)
       - [`expectRevert`](./cheatcodes/expect-revert.md)
       - [`expectEmit`](./cheatcodes/expect-emit.md)
@@ -493,7 +496,6 @@
       - [`createWallet`](./cheatcodes/create-wallet.md)
       - [`copyStorage`](./cheatcodes/copy-storage.md)
       - [`setArbitraryStorage`](./cheatcodes/set-arbitrary-storage.md)
-    - [Snapshots](./cheatcodes/snapshots.md)
     - [RPC](./cheatcodes/rpc.md)
     - [Files](./cheatcodes/fs.md)
   - [Forge Standard Library Reference](./reference/forge-std/README.md)

src/cheatcodes/gas-snapshots.md

@@ -0,0 +1,175 @@
+## `snapshotGas` cheatcodes
+
+### Signature
+
+```solidity
+/// Start a snapshot capture of the current gas usage by name.
+/// The group name is derived from the contract name.
+function startSnapshotGas(string calldata name) external;
+
+/// Start a snapshot capture of the current gas usage by name in a group.
+function startSnapshotGas(string calldata group, string calldata name) external;
+
+/// Stop the snapshot capture of the current gas by latest snapshot name, capturing the gas used since the start.
+function stopSnapshotGas() external returns (uint256 gasUsed);
+
+/// Stop the snapshot capture of the current gas usage by name, capturing the gas used since the start.
+/// The group name is derived from the contract name.
+function stopSnapshotGas(string calldata name) external returns (uint256 gasUsed);
+
+/// Stop the snapshot capture of the current gas usage by name in a group, capturing the gas used since the start.
+function stopSnapshotGas(string calldata group, string calldata name) external returns (uint256 gasUsed);
+
+/// Snapshot capture an arbitrary numerical value by name.
+/// The group name is derived from the contract name.
+function snapshotValue(string calldata name, uint256 value) external;
+
+/// Snapshot capture an arbitrary numerical value by name in a group.
+function snapshotValue(string calldata group, string calldata name, uint256 value) external;
+
+/// Snapshot capture the gas usage of the last call by name from the callee perspective.
+function snapshotGasLastCall(string calldata name) external returns (uint256 gasUsed);
+
+/// Snapshot capture the gas usage of the last call by name in a group from the callee perspective.
+function snapshotGasLastCall(string calldata group, string calldata name) external returns (uint256 gasUsed);
+```
+
+### Description
+
+`snapshotGas*` cheatcodes allow you to capture gas usage in your tests. This can be useful to track how much gas your logic is consuming. You can capture the gas usage of the last call by name, capture an arbitrary numerical value by name, or start and stop a snapshot capture of the current gas usage by name.
+
+In order to strictly compare gas usage across test runs, set the `FORGE_SNAPSHOT_CHECK` environment variable to `true` before running your tests. This will compare the gas usage of your tests against the last snapshot and fail if the gas usage has changed. By default the snapshots directory will be newly created and its contents removed before each test run to ensure no stale data is present.
+
+It is intended that the `snapshots` directory created when using the `snapshotGas*` cheatcodes is checked into version control. This allows you to track changes in gas usage over time and compare gas usage during code reviews.
+
+When running `forge clean` the `snapshots` directory will be deleted.
+
+### Examples
+
+Capturing the gas usage of a section of code that calls an external contract:
+
+```solidity
+contract SnapshotGasTest is Test {
+    uint256 public slot0;
+
+    Flare public flare;
+
+    function setUp() public {
+        flare = new Flare();
+    }
+
+    function testSnapshotGas() public {
+        vm.startSnapshotGas("externalA");
+        flare.run(256);
+        uint256 gasUsed = vm.stopSnapshotGas();
+    }
+}
+```
+
+Capturing the gas usage of multiple sections of code that modify the internal state:
+
+
+```solidity
+contract SnapshotGasTest is Test {
+    uint256 public slot0;
+
+
+    /// Writes to `snapshots/SnapshotGasTest.json` group with name `internalA`, `internalB`, and `internalC`.
+    function testSnapshotGas() public {
+        vm.startSnapshotGas("internalA");
+        slot0 = 1;
+        vm.stopSnapshotGas();
+
+        vm.startSnapshotGas("internalB");
+        slot0 = 2;
+        vm.stopSnapshotGas();
+
+        vm.startSnapshotGas("internalC");
+        slot0 = 0;
+        vm.stopSnapshotGas();
+    }
+}
+```
+
+Capturing the gas usage of a section of code that modifies both the internal state and calls an external contract:
+
+```solidity
+contract SnapshotGasTest is Test {
+    uint256 public slot0;
+    Flare public flare;
+
+    function setUp() public {
+        flare = new Flare();
+    }
+
+    /// Writes to `snapshots/SnapshotGasTest.json` group with name `combinedA`.
+    function testSnapshotGas() public {
+        vm.startSnapshotGas("combinedA");
+        flare.run(256);
+        slot0 = 1;
+        vm.stopSnapshotGas();
+    }
+}
+```
+
+```solidity
+
+Capturing an arbitrary numerical value (such as the bytecode size of a contract):
+
+```solidity
+contract SnapshotGasTest is Test {
+    uint256 public slot0;
+
+    /// Writes to `snapshots/SnapshotGasTest.json` group with name `valueA`, `valueB`, and `valueC`.
+    function testSnapshotValue() public {
+        uint256 a = 123;
+        uint256 b = 456;
+        uint256 c = 789;
+
+        vm.snapshotValue("valueA", a);
+        vm.snapshotValue("valueB", b);
+        vm.snapshotValue("valueC", c);
+    }
+}
+```
+
+Capturing the gas usage of the last call from the callee perspective:
+
+```solidity
+contract SnapshotGasTest is Test {
+    Flare public flare;
+
+    function setUp() public {
+        flare = new Flare();
+    }
+
+    /// Writes to `snapshots/SnapshotGasTest.json` group with name `lastCallA`.
+    function testSnapshotGasLastCall() public {
+        flare.run(1);
+        vm.snapshotGasLastCall("lastCallA");
+    }
+}
+```
+
+For each of the above examples you can also use the `group` variant of the cheatcodes to group the snapshots together in a custom group.
+
+```solidity
+contract SnapshotGasTest is Test {
+    uint256 public slot0;
+
+    /// Writes to `snapshots/CustomGroup.json` group with name `internalA`, `internalB`, and `internalC`.
+    function testSnapshotGas() public {
+        vm.startSnapshotGas("CustomGroup", "internalA");
+        slot0 = 1;
+        vm.stopSnapshotGas();
+
+        vm.startSnapshotGas("CustomGroup", "internalB");
+        slot0 = 2;
+        vm.stopSnapshotGas();
+
+        vm.startSnapshotGas("CustomGroup", "internalC");
+        slot0 = 0;
+        vm.stopSnapshotGas();
+    }
+}
+```

src/cheatcodes/snapshots.md

@@ -0,0 +1,81 @@
+## `snapshotState` cheatcodes
+
+### Signature
+
+```solidity
+/// Snapshot the current state of the evm.
+/// Returns the ID of the snapshot that was created.
+/// To revert a snapshot use `revertToState`.
+function snapshotState() external returns (uint256 snapshotId);
+
+/// Revert the state of the EVM to a previous snapshot
+/// Takes the snapshot ID to revert to.
+/// Returns `true` if the snapshot was successfully reverted.
+/// Returns `false` if the snapshot does not exist.
+/// **Note:** This does not automatically delete the snapshot. To delete the snapshot use `deleteStateSnapshot`.
+function revertToState(uint256 snapshotId) external returns (bool success);
+
+/// Revert the state of the EVM to a previous snapshot and automatically deletes the snapshots
+/// Takes the snapshot ID to revert to.
+/// Returns `true` if the snapshot was successfully reverted and deleted.
+/// Returns `false` if the snapshot does not exist.
+function revertToStateAndDelete(uint256 snapshotId) external returns (bool success);
+
+/// Removes the snapshot with the given ID created by `snapshot`.
+/// Takes the snapshot ID to delete.
+/// Returns `true` if the snapshot was successfully deleted.
+/// Returns `false` if the snapshot does not exist.
+function deleteStateSnapshot(uint256 snapshotId) external returns (bool success);
+
+/// Removes _all_ snapshots previously created by `snapshot`.
+function deleteStateSnapshots() external;
+```
+
+### Description
+
+`snapshotState` takes a snapshot of the state of the blockchain and returns the identifier of the created snapshot.
+
+`revertToState` reverts the state of the blockchain to the given state snapshot. This deletes the given snapshot, as well as any snapshots taken after (e.g.: reverting to id 2 will delete snapshots with ids 2, 3, 4, etc.).
+
+### Examples
+
+```solidity
+struct Storage {
+    uint slot0;
+    uint slot1;
+}
+
+contract SnapshotStateTest is Test {
+    Storage store;
+    uint256 timestamp;
+
+    function setUp() public {
+        store.slot0 = 10;
+        store.slot1 = 20;
+        vm.deal(address(this), 5 ether);            // balance = 5 ether
+        timestamp = block.timestamp;
+    }
+
+    function testSnapshotState() public {
+        uint256 snapshot = vm.snapshotState();      // saves the state
+
+        // let's change the state
+        store.slot0 = 300;
+        store.slot1 = 400;
+        vm.deal(address(this), 500 ether);
+        vm.warp(12345);                             // block.timestamp = 12345
+
+        assertEq(store.slot0, 300);
+        assertEq(store.slot1, 400);
+        assertEq(address(this).balance, 500 ether);
+        assertEq(block.timestamp, 12345);
+
+        vm.revertToState(snapshot);                 // restores the state
+
+        assertEq(store.slot0, 10, "snapshot revert for slot 0 unsuccessful");
+        assertEq(store.slot1, 20, "snapshot revert for slot 1 unsuccessful");
+        assertEq(address(this).balance, 5 ether, "snapshot revert for balance unsuccessful");
+        assertEq(block.timestamp, timestamp, "snapshot revert for timestamp unsuccessful");
+    }
+}
+```

src/cheatcodes/state-snapshots.md

@@ -1,4 +1,4 @@
-## Gas Snapshots
+## Gas Function Snapshots
 
 Forge can generate gas snapshots for all your test functions. This can
 be useful to get a general feel for how much gas your contract will consume,

src/forge/gas-snapshots.md renamed to src/forge/gas-function-snapshots.md

@@ -0,0 +1,7 @@
+# Gas Section Snapshots
+
+Forge can capture gas snapshots over arbitrary sections inside of your test functions. This can be useful to get a granular measurement of how much gas your logic is consuming as both external calls and internal gas usage are measured.
+
+Instead of running a command like `forge snapshot` or `forge test --gas-report`, you use the `snapshotGas` [cheatcodes](./cheatcodes.md) in your tests to capture gas usage as follows:
+
+{{#include ../cheatcodes/gas-snapshots.md}}

src/forge/gas-section-snapshots.md

@@ -2,16 +2,20 @@
 
 Forge can help you estimate how much gas your contract will consume.
 
-Currently, Forge ships with two different tools for this job, but they may be merged in the future:
+Currently, Forge ships with three different tools for this job:
 
 - [**Gas reports**](./gas-reports.md): Gas reports give you an overview of how much Forge thinks the
   individual functions in your contracts will consume in gas.
-- [**Gas snapshots**](./gas-snapshots.md): Gas snapshots give you an overview of how much
-  each test consumes in gas.
+- [**Gas function snapshots**](./gas-function-snapshots.md): Gas function snapshots give you an overview of how much
+  each test function consumes in gas.
+- [**Gas section snapshots**](./gas-section-snapshots.md): Gas section snapshots give you the ability to capture gas usage over arbitrary sections inside of test functions.
+  This also tracks internal gas usage. You can access this by using the `snapshotGas*` cheatcodes inside your tests.
 
-Gas reports and gas snapshots differ in some ways:
+Gas reports, gas function snapshots and gas section snapshots differ in some ways:
 
 - Gas reports use tracing to figure out gas costs for individual contract calls.  
   This gives more granular insight, at the cost of speed.
-- Gas snapshots have more built-in tools, such as diffs and exporting the results to a file.  
+- Gas function snapshots have more built-in tools, such as diffs and exporting the results to a file.
   Snapshots are not as granular as gas reports, but they are faster to generate.
+- Gas section snapshots provides the most granular way to capture gas usage. Every captured gas snapshot is written to a file in a `snapshots` directory.
+  By default these snapshots are grouped by the contract name of the test.