Gas snapshots - Show a link to the test file on failures (#7883)

* chore: update function gas snapshots file to test duplicate contracts

* feat: show source path in failed snapshot check for function gas snapshots

* feat: show source path in failed snapshot check for snapshot cheatcodes

* Create fuzzy-ravens-promise.md

* Update fuzzy-ravens-promise.md

Author: schaable

.changeset/fuzzy-ravens-promise.md

@@ -0,0 +1,5 @@
+---
+"hardhat": patch
+---
+
+Show a link to the test file on failures in the gas snapshots output message ([#7864](https://github.com/NomicFoundation/hardhat/issues/7864))

v-next/example-project/.gas-snapshot

@@ -17,9 +17,11 @@ CalculatorTest#testSnapshotGasSubtraction() (gas: 57557)
 CalculatorTest#testSnapshotValues() (gas: 82076)
 CalculatorTest#testSubtraction() (gas: 59962)
 CalculatorTest#testSubtractionUnderflow() (gas: 9920)
-CounterTest#testFuzzInc(uint8) (runs: 256, μ: 109380, ~: 61119)
-CounterTest#testInitialValue() (gas: 11173)
-CounterTest#testSnapshotGasLastCall() (gas: 31032)
-CounterTest#testSnapshotGasRegion() (gas: 41130)
-CounterTest#testSnapshotValue() (gas: 38393)
+contracts/Counter.t.sol:CounterTest#testFuzzInc(uint8) (runs: 256, μ: 109380, ~: 61119)
+contracts/Counter.t.sol:CounterTest#testInitialValue() (gas: 11173)
+contracts/Counter.t.sol:CounterTest#testSnapshotGasLastCall() (gas: 31032)
+contracts/Counter.t.sol:CounterTest#testSnapshotGasRegion() (gas: 41130)
+contracts/Counter.t.sol:CounterTest#testSnapshotValue() (gas: 38393)
+test/contracts/Counter.t.sol:CounterTest#testFuzzInc(uint8) (runs: 256, μ: 98211, ~: 59474)
+test/contracts/Counter.t.sol:CounterTest#testInitialValue() (gas: 11151)
 TestContract#testExpectArithmetic() (gas: 9899)

v-next/example-project/test/contracts/Counter.t.sol

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import "../../contracts/Counter.sol";
+import "forge-std/Test.sol";
+
+/**
+ * This test contract is intentionally duplicated from
+ * v-next/example-project/contracts/Counter.t.sol to test gas
+ * snapshot functionality in the hardhat gas analytics plugin.
+ */
+contract CounterTest is Test {
+  Counter counter;
+
+  function setUp() public {
+    console.log("Setting up");
+    counter = new Counter();
+    console.log("Counter set up");
+  }
+
+  function testInitialValue() public view {
+    console.log("Testing initial value");
+    require(counter.x() == 0, "Initial value should be 0");
+  }
+
+  function testFuzzInc(uint8 x) public {
+    console.log("Fuzz testing inc");
+    for (uint8 i = 0; i < x; i++) {
+      counter.inc();
+    }
+    require(counter.x() == x, "Value after calling inc x times should be x");
+  }
+}

v-next/hardhat/src/internal/builtin-plugins/gas-analytics/function-gas-snapshots.ts

@@ -12,8 +12,12 @@ import {
 import { findDuplicates } from "@nomicfoundation/hardhat-utils/lang";
 import chalk from "chalk";
 
-import { getFullyQualifiedName } from "../../../utils/contract-names.js";
+import {
+  getFullyQualifiedName,
+  parseFullyQualifiedName,
+} from "../../../utils/contract-names.js";
 
+import { getUserFqn } from "./gas-analytics-manager.js";
 import { formatSectionHeader } from "./helpers.js";
 
 export const FUNCTION_GAS_SNAPSHOTS_FILE = ".gas-snapshot";
@@ -24,6 +28,12 @@ export interface FunctionGasSnapshot {
   gasUsage: StandardTestKindGasUsage | FuzzTestKindGasUsage;
 }
 
+export interface FunctionGasSnapshotWithMetadata extends FunctionGasSnapshot {
+  metadata: {
+    source: string;
+  };
+}
+
 export interface StandardTestKindGasUsage {
   kind: "standard";
   gas: bigint;
@@ -43,6 +53,7 @@ export interface FunctionGasSnapshotComparison {
 }
 
 export interface FunctionGasSnapshotChange {
+  source: string;
   contractNameOrFqn: string;
   functionSig: string;
   kind: "standard" | "fuzz";
@@ -63,20 +74,23 @@ export function getFunctionGasSnapshotsPath(basePath: string): string {
 
 export function extractFunctionGasSnapshots(
   suiteResults: SuiteResult[],
-): FunctionGasSnapshot[] {
+): FunctionGasSnapshotWithMetadata[] {
   const duplicateContractNames = findDuplicates(
     suiteResults.map(({ id }) => id.name),
   );
 
-  const snapshots: FunctionGasSnapshot[] = [];
+  const snapshots: FunctionGasSnapshotWithMetadata[] = [];
   for (const { id: suiteId, testResults } of suiteResults) {
     for (const { name: functionSig, kind: testKind } of testResults) {
       if ("calls" in testKind) {
         continue;
       }
 
+      const userFqn = getUserFqn(
+        getFullyQualifiedName(suiteId.source, suiteId.name),
+      );
       const contractNameOrFqn = duplicateContractNames.has(suiteId.name)
-        ? getFullyQualifiedName(suiteId.source, suiteId.name)
+        ? userFqn
         : suiteId.name;
 
       const gasUsage =
@@ -96,6 +110,9 @@ export function extractFunctionGasSnapshots(
         contractNameOrFqn,
         functionSig,
         gasUsage,
+        metadata: {
+          source: parseFullyQualifiedName(userFqn).sourceName,
+        },
       });
     }
   }
@@ -225,7 +242,7 @@ export function parseFunctionGasSnapshots(
 
 export function compareFunctionGasSnapshots(
   previousSnapshots: FunctionGasSnapshot[],
-  currentSnapshots: FunctionGasSnapshot[],
+  currentSnapshots: FunctionGasSnapshotWithMetadata[],
 ): FunctionGasSnapshotComparison {
   const previousSnapshotsMap = new Map(
     previousSnapshots.map((s) => [
@@ -270,6 +287,7 @@ export function compareFunctionGasSnapshots(
         actual: Number(actualValue),
         runs:
           currentKind === "fuzz" ? Number(current.gasUsage.runs) : undefined,
+        source: current.metadata.source,
       });
     }
     previousSnapshotsMap.delete(key);
@@ -301,7 +319,7 @@ export async function checkFunctionGasSnapshots(
 ): Promise<FunctionGasSnapshotCheckResult> {
   const functionGasSnapshots = extractFunctionGasSnapshots(suiteResults);
 
-  let previousFunctionGasSnapshots;
+  let previousFunctionGasSnapshots: FunctionGasSnapshot[];
   try {
     previousFunctionGasSnapshots = await readFunctionGasSnapshots(basePath);
   } catch (error) {
@@ -418,6 +436,7 @@ export function printFunctionGasSnapshotChanges(
     const isLast = i === changes.length - 1;
 
     logger(`  ${change.contractNameOrFqn}#${change.functionSig}`);
+    logger(chalk.grey(`    (in ${change.source})`));
 
     if (change.kind === "fuzz") {
       logger(chalk.grey(`    Runs: ${change.runs}`));

v-next/hardhat/src/internal/builtin-plugins/gas-analytics/snapshot-cheatcodes.ts

@@ -12,6 +12,12 @@ import {
 } from "@nomicfoundation/hardhat-utils/fs";
 import chalk from "chalk";
 
+import {
+  getFullyQualifiedName,
+  parseFullyQualifiedName,
+} from "../../../utils/contract-names.js";
+
+import { getUserFqn } from "./gas-analytics-manager.js";
 import { formatSectionHeader } from "./helpers.js";
 
 export const SNAPSHOT_CHEATCODES_DIR = "snapshots";
@@ -24,6 +30,19 @@ export type SnapshotCheatcodesMap = Map<
   >
 >;
 
+export type SnapshotCheatcodesWithMetadataMap = Map<
+  string, // group
+  Record<
+    string, // name
+    {
+      value: string;
+      metadata: {
+        source: string;
+      };
+    }
+  >
+>;
+
 export interface SnapshotCheatcode {
   group: string;
   name: string;
@@ -35,6 +54,7 @@ export interface SnapshotCheatcodeChange {
   name: string;
   expected: number;
   actual: number;
+  source: string;
 }
 
 export interface SnapshotCheatcodesComparison {
@@ -58,14 +78,18 @@ export function getSnapshotCheatcodesPath(
 
 export function extractSnapshotCheatcodes(
   suiteResults: SuiteResult[],
-): SnapshotCheatcodesMap {
-  const snapshots: SnapshotCheatcodesMap = new Map();
-  for (const { testResults } of suiteResults) {
+): SnapshotCheatcodesWithMetadataMap {
+  const snapshots: SnapshotCheatcodesWithMetadataMap = new Map();
+  for (const { id: suiteId, testResults } of suiteResults) {
     for (const { valueSnapshotGroups: snapshotGroups } of testResults) {
       if (snapshotGroups === undefined) {
         continue;
       }
 
+      const userFqn = getUserFqn(
+        getFullyQualifiedName(suiteId.source, suiteId.name),
+      );
+
       for (const group of snapshotGroups) {
         let snapshot = snapshots.get(group.name);
         if (snapshot === undefined) {
@@ -74,7 +98,12 @@ export function extractSnapshotCheatcodes(
         }
 
         for (const entry of group.entries) {
-          snapshot[entry.name] = entry.value;
+          snapshot[entry.name] = {
+            value: entry.value,
+            metadata: {
+              source: parseFullyQualifiedName(userFqn).sourceName,
+            },
+          };
         }
       }
     }
@@ -85,16 +114,21 @@ export function extractSnapshotCheatcodes(
 
 export async function writeSnapshotCheatcodes(
   basePath: string,
-  snapshotCheatcodes: SnapshotCheatcodesMap,
+  snapshotCheatcodes: SnapshotCheatcodesWithMetadataMap,
 ): Promise<void> {
   for (const [snapshotGroup, snapshot] of snapshotCheatcodes) {
     const snapshotCheatcodesPath = getSnapshotCheatcodesPath(
       basePath,
       `${snapshotGroup}.json`,
     );
 
+    const snapshotWithoutMetadata: Record<string, string> = {};
+    for (const [name, entry] of Object.entries(snapshot)) {
+      snapshotWithoutMetadata[name] = entry.value;
+    }
+
     try {
-      await writeJsonFile(snapshotCheatcodesPath, snapshot);
+      await writeJsonFile(snapshotCheatcodesPath, snapshotWithoutMetadata);
     } catch (error) {
       ensureError(error);
       throw new HardhatError(
@@ -167,7 +201,7 @@ export function stringifySnapshotCheatcodes(
 
 export function compareSnapshotCheatcodes(
   previousSnapshotsMap: SnapshotCheatcodesMap,
-  currentSnapshotsMap: SnapshotCheatcodesMap,
+  currentSnapshotsMap: SnapshotCheatcodesWithMetadataMap,
 ): SnapshotCheatcodesComparison {
   const added: SnapshotCheatcode[] = [];
   const removed: SnapshotCheatcode[] = [];
@@ -177,23 +211,24 @@ export function compareSnapshotCheatcodes(
   for (const [group, currentSnapshots] of currentSnapshotsMap) {
     const previousSnapshots = previousSnapshotsMap.get(group);
 
-    for (const [name, currentValue] of Object.entries(currentSnapshots)) {
+    for (const [name, currentEntry] of Object.entries(currentSnapshots)) {
       const key = `${group}#${name}`;
 
       if (
         previousSnapshots === undefined ||
         !Object.hasOwn(previousSnapshots, name)
       ) {
-        added.push({ group, name, value: currentValue });
+        added.push({ group, name, value: currentEntry.value });
       } else {
         seenPreviousEntries.add(key);
         const previousValue = previousSnapshots[name];
-        if (previousValue !== currentValue) {
+        if (previousValue !== currentEntry.value) {
           changed.push({
             group,
             name,
             expected: Number(previousValue),
-            actual: Number(currentValue),
+            actual: Number(currentEntry.value),
+            source: currentEntry.metadata.source,
           });
         }
       }
@@ -345,6 +380,7 @@ export function printSnapshotCheatcodeChanges(
     const isLast = i === changes.length - 1;
 
     logger(`  ${change.group}#${change.name}`);
+    logger(chalk.grey(`    (in ${change.source})`));
 
     const diff = change.actual - change.expected;
     const formattedDiff = diff > 0 ? `Δ+${diff}` : `Δ${diff}`;