hardhat 3.2.0 → 3.4.0

package/src/internal/builtin-plugins/solidity-test/inline-config/index.ts

@@ -0,0 +1,272 @@
+import type { SolidityBuildInfoOutput } from "../../../../types/solidity/solidity-artifacts.js";
+import type {
+  BuildInfoAndOutput,
+  EdrArtifactWithMetadata,
+} from "../edr-artifacts.js";
+import type { RawInlineOverride } from "./types.js";
+import type { ArtifactId, TestFunctionOverride } from "@nomicfoundation/edr";
+
+import {
+  HardhatError,
+  assertHardhatInvariant,
+} from "@nomicfoundation/hardhat-errors";
+import { bytesToUtf8String } from "@nomicfoundation/hardhat-utils/bytes";
+
+import { getFullyQualifiedName } from "../../../../utils/contract-names.js";
+
+import {
+  buildInfoContainsInlineConfig,
+  resolveFunctionSelector,
+  buildConfigOverride,
+  getFunctionFqn,
+} from "./helpers.js";
+import { extractInlineConfigFromAst } from "./parsing.js";
+import { validateInlineOverrides } from "./validation.js";
+
+export type { RawInlineOverride } from "./types.js";
+export {
+  buildInfoContainsInlineConfig,
+  resolveFunctionSelector,
+  buildConfigOverride,
+  getFunctionFqn,
+} from "./helpers.js";
+export {
+  extractInlineConfigFromAst,
+  extractDocText,
+  parseInlineConfigLine,
+} from "./parsing.js";
+export { validateInlineOverrides } from "./validation.js";
+
+interface CollectedOverrides {
+  overrides: RawInlineOverride[];
+  artifactIdsByFqn: Map<string, ArtifactId>;
+  methodIdentifiersByContract: Map<string, Record<string, string>>;
+}
+
+/**
+ * Extracts per-test inline configuration overrides from the NatSpec comments
+ * in the solc AST. It only extracts them from the build info where each
+ * test artifact's file was compiled as a root file.
+ */
+export function getTestFunctionOverrides(
+  testSuiteArtifacts: EdrArtifactWithMetadata[],
+  buildInfosAndOutputs: BuildInfoAndOutput[],
+): TestFunctionOverride[] {
+  const allRawOverrides = collectRawOverrides(
+    testSuiteArtifacts,
+    buildInfosAndOutputs,
+  );
+
+  validateInlineOverrides(allRawOverrides.overrides);
+
+  return buildTestFunctionOverrides(allRawOverrides);
+}
+
+function collectRawOverrides(
+  testSuiteArtifacts: EdrArtifactWithMetadata[],
+  buildInfosAndOutputs: BuildInfoAndOutput[],
+): CollectedOverrides {
+  const overrides: RawInlineOverride[] = [];
+  const methodIdentifiersByContract = new Map<string, Record<string, string>>();
+
+  // Note: We group the artifacts by their build info, so that we only process
+  // the relevant build infos, and only the root files of each of them.
+  //
+  // The last part is important, as a test file can be present in multiple build
+  // infos in the presence of partial recompilations
+  //
+  // At the same time, the same root file could have produced multiple test
+  // artifacts, so we need a two-level map to avoid processing the root files
+  // multiple times.
+
+  // Build lookup structures for fast access
+  const artifactsGroupedByBuildInfo = new Map<
+    /* buildInfoId */ string,
+    Map</* inputSourceName */ string, EdrArtifactWithMetadata[]>
+  >();
+
+  const artifactIdsByFqn = new Map<string, ArtifactId>();
+  const buildInfoAndOutputById: Map<string, BuildInfoAndOutput> = new Map(
+    buildInfosAndOutputs.map((bio) => [bio.buildInfoId, bio]),
+  );
+
+  for (const edrArtifactWithMetadata of testSuiteArtifacts) {
+    const fqn = getFullyQualifiedName(
+      edrArtifactWithMetadata.edrArtifact.id.source,
+      edrArtifactWithMetadata.edrArtifact.id.name,
+    );
+
+    const buildInfoId = edrArtifactWithMetadata.buildInfoId;
+    let artifactsBySource = artifactsGroupedByBuildInfo.get(buildInfoId);
+
+    if (artifactsBySource === undefined) {
+      artifactsBySource = new Map();
+      artifactsGroupedByBuildInfo.set(buildInfoId, artifactsBySource);
+    }
+
+    let artifacts = artifactsBySource.get(
+      edrArtifactWithMetadata.edrArtifact.id.source,
+    );
+    if (artifacts === undefined) {
+      artifacts = [];
+      artifactsBySource.set(
+        edrArtifactWithMetadata.edrArtifact.id.source,
+        artifacts,
+      );
+    }
+
+    artifacts.push(edrArtifactWithMetadata);
+    artifactIdsByFqn.set(fqn, edrArtifactWithMetadata.edrArtifact.id);
+  }
+
+  for (const [
+    buildInfoId,
+    artifactsBySource,
+  ] of artifactsGroupedByBuildInfo.entries()) {
+    const buildInfoAndOutput = buildInfoAndOutputById.get(buildInfoId);
+    if (buildInfoAndOutput === undefined) {
+      // We can throw for this error for the first artifact with this build info
+      // as all of them have the same problem.
+      const artifacts = artifactsBySource.values().next().value;
+
+      assertHardhatInvariant(
+        artifacts !== undefined && artifacts.length > 0,
+        "An artifact must be present for the build info",
+      );
+
+      const anyArtifact = artifacts[0];
+
+      const fqn = getFullyQualifiedName(
+        anyArtifact.userSourceName,
+        anyArtifact.edrArtifact.id.name,
+      );
+
+      throw new HardhatError(
+        HardhatError.ERRORS.CORE.SOLIDITY_TESTS.BUILD_INFO_NOT_FOUND_FOR_CONTRACT,
+        {
+          fqn,
+        },
+      );
+    }
+
+    if (!buildInfoContainsInlineConfig(buildInfoAndOutput.buildInfo)) {
+      continue;
+    }
+
+    const buildInfoOutput: SolidityBuildInfoOutput = JSON.parse(
+      bytesToUtf8String(buildInfoAndOutput.output),
+    );
+
+    for (const [
+      inputSourceName,
+      sourceArtifacts,
+    ] of artifactsBySource.entries()) {
+      const contractNames = new Set(
+        sourceArtifacts.map((a) => a.edrArtifact.id.name),
+      );
+
+      const source = buildInfoOutput.output.sources[inputSourceName];
+      const extracted = extractInlineConfigFromAst(
+        source.ast,
+        inputSourceName,
+        contractNames,
+      );
+      overrides.push(...extracted);
+
+      for (const artifact of sourceArtifacts) {
+        const contractName = artifact.edrArtifact.id.name;
+        const fqn = getFullyQualifiedName(inputSourceName, contractName);
+
+        const methodIdentifiers =
+          buildInfoOutput.output.contracts?.[inputSourceName][contractName]?.evm
+            ?.methodIdentifiers;
+
+        methodIdentifiersByContract.set(fqn, methodIdentifiers ?? {});
+      }
+    }
+  }
+
+  return { overrides, artifactIdsByFqn, methodIdentifiersByContract };
+}
+
+function buildTestFunctionOverrides(
+  collected: CollectedOverrides,
+): TestFunctionOverride[] {
+  const { overrides, artifactIdsByFqn, methodIdentifiersByContract } =
+    collected;
+
+  // Group overrides by function. When the AST provides a functionSelector
+  // (public/external functions in solc >= 0.6.0), use it to distinguish
+  // overloaded functions. Otherwise fall back to function name only.
+  const overridesByFunction = new Map<string, RawInlineOverride[]>();
+  for (const override of overrides) {
+    const functionFqn = getFunctionFqn(
+      override.inputSourceName,
+      override.contractName,
+      override.functionName,
+    );
+    const groupKey =
+      override.functionSelector !== undefined
+        ? `${functionFqn}#${override.functionSelector}`
+        : functionFqn;
+    const existing = overridesByFunction.get(groupKey);
+    if (existing === undefined) {
+      overridesByFunction.set(groupKey, [override]);
+    } else {
+      existing.push(override);
+    }
+  }
+
+  // Build TestFunctionOverride objects
+  const testFunctionOverrides: TestFunctionOverride[] = [];
+  for (const [_groupKey, groupOverrides] of overridesByFunction.entries()) {
+    const firstOverride = groupOverrides[0];
+    const functionFqn = getFunctionFqn(
+      firstOverride.inputSourceName,
+      firstOverride.contractName,
+      firstOverride.functionName,
+    );
+    const contractFqn = `${firstOverride.inputSourceName}:${firstOverride.contractName}`;
+
+    const artifactId = artifactIdsByFqn.get(contractFqn);
+    assertHardhatInvariant(
+      artifactId !== undefined,
+      `Missing artifact id for "${contractFqn}"`,
+    );
+
+    // Use the AST-provided selector when available, otherwise fall back to
+    // resolving via methodIdentifiers.
+    let selector: string | undefined;
+    if (firstOverride.functionSelector !== undefined) {
+      selector = `0x${firstOverride.functionSelector}`;
+    } else {
+      const methodIdentifiers = methodIdentifiersByContract.get(contractFqn);
+      assertHardhatInvariant(
+        methodIdentifiers !== undefined,
+        `Missing method identifiers for "${contractFqn}"`,
+      );
+
+      selector = resolveFunctionSelector(
+        methodIdentifiers,
+        firstOverride.functionName,
+      );
+    }
+
+    if (selector === undefined) {
+      throw new HardhatError(
+        HardhatError.ERRORS.CORE.SOLIDITY_TESTS.INLINE_CONFIG_UNRESOLVED_SELECTOR,
+        { functionFqn },
+      );
+    }
+
+    testFunctionOverrides.push({
+      identifier: {
+        contractArtifact: artifactId,
+        functionSelector: selector,
+      },
+      config: buildConfigOverride(groupOverrides),
+    });
+  }
+
+  return testFunctionOverrides;
+}

package/src/internal/builtin-plugins/solidity-test/inline-config/parsing.ts

@@ -0,0 +1,186 @@
+import type { RawInlineOverride } from "./types.js";
+
+import { HardhatError } from "@nomicfoundation/hardhat-errors";
+import { isObject } from "@nomicfoundation/hardhat-utils/lang";
+import {
+  kebabToCamelCase,
+  snakeToCamelCase,
+} from "@nomicfoundation/hardhat-utils/string";
+
+import {
+  HARDHAT_CONFIG_PREFIX,
+  FORGE_CONFIG_PREFIX,
+  TOP_LEVEL_KEYS,
+} from "./constants.js";
+import { getFunctionFqn } from "./helpers.js";
+
+/**
+ * Extracts raw inline config overrides from a solc AST for a single source
+ * file.
+ */
+export function extractInlineConfigFromAst(
+  ast: unknown,
+  inputSourceName: string,
+  contractNames: Set<string>,
+): RawInlineOverride[] {
+  if (!isObject(ast) || ast.nodeType !== "SourceUnit") {
+    return [];
+  }
+
+  const results: RawInlineOverride[] = [];
+  const nodes: unknown[] = Array.isArray(ast.nodes) ? ast.nodes : [];
+  for (const node of nodes) {
+    if (!isObject(node) || node.nodeType !== "ContractDefinition") {
+      continue;
+    }
+
+    const contractName = node.name;
+    if (typeof contractName !== "string") {
+      continue;
+    }
+
+    if (!contractNames.has(contractName)) {
+      continue;
+    }
+
+    const members: unknown[] = Array.isArray(node.nodes) ? node.nodes : [];
+    for (const member of members) {
+      if (!isObject(member) || member.nodeType !== "FunctionDefinition") {
+        continue;
+      }
+
+      const fnName = member.name;
+      if (
+        typeof fnName !== "string" ||
+        (!fnName.startsWith("test") && !fnName.startsWith("invariant"))
+      ) {
+        continue;
+      }
+
+      const fnSelector =
+        typeof member.functionSelector === "string"
+          ? member.functionSelector
+          : undefined;
+
+      const docText = extractDocText(member.documentation);
+      if (docText === undefined) {
+        continue;
+      }
+
+      for (const line of docText.split("\n")) {
+        const parsed = parseInlineConfigLine(
+          line,
+          inputSourceName,
+          contractName,
+          fnName,
+        );
+        if (parsed !== undefined) {
+          parsed.functionSelector = fnSelector;
+          results.push(parsed);
+        }
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Extracts the documentation text from a FunctionDefinition's documentation
+ * field, which can be a StructuredDocumentation node, a plain string, or null.
+ */
+export function extractDocText(doc: unknown): string | undefined {
+  if (
+    isObject(doc) &&
+    doc.nodeType === "StructuredDocumentation" &&
+    typeof doc.text === "string"
+  ) {
+    return doc.text;
+  } else if (typeof doc === "string") {
+    return doc;
+  } else {
+    return undefined;
+  }
+}
+
+/**
+ * Parses a single line from a NatSpec comment and returns a RawInlineOverride
+ * if the line contains a valid inline config directive. The line must start
+ * with either "hardhat-config:" or "forge-config:", followed by a key=value pair.
+ * Returns undefined if the line does not contain an inline config directive.
+ */
+export function parseInlineConfigLine(
+  line: string,
+  inputSourceName: string,
+  contractName: string,
+  functionName: string,
+): RawInlineOverride | undefined {
+  // Strip leading whitespace and optional leading '*' from NatSpec text.
+  // Solc's StructuredDocumentation.text has delimiters (///, /**, */) removed.
+  // For /// comments, text has leading whitespace; for /** */ blocks, interior
+  // lines may start with " * ". The regex handles both styles.
+  const trimmedLine = line.replace(/^\s*\*?\s*/, "");
+  const functionFqn = getFunctionFqn(
+    inputSourceName,
+    contractName,
+    functionName,
+  );
+
+  let keyValueSegment: string;
+
+  if (trimmedLine.startsWith(HARDHAT_CONFIG_PREFIX)) {
+    keyValueSegment = trimmedLine.slice(HARDHAT_CONFIG_PREFIX.length).trim();
+  } else if (trimmedLine.startsWith(FORGE_CONFIG_PREFIX)) {
+    keyValueSegment = trimmedLine.slice(FORGE_CONFIG_PREFIX.length).trim();
+  } else {
+    return undefined;
+  }
+
+  const eqIndex = keyValueSegment.indexOf("=");
+  if (eqIndex === -1) {
+    throw new HardhatError(
+      HardhatError.ERRORS.CORE.SOLIDITY_TESTS.INLINE_CONFIG_INVALID_SYNTAX,
+      {
+        line: trimmedLine,
+        functionFqn,
+      },
+    );
+  }
+
+  const rawKey = keyValueSegment.slice(0, eqIndex).trim();
+  let parsedKey = rawKey;
+  const rawValue = keyValueSegment.slice(eqIndex + 1).trim();
+
+  // Detect profile prefix: if the first dot-segment is NOT a known top-level
+  // category, treat it as a profile name.
+  const firstDot = rawKey.indexOf(".");
+  if (firstDot !== -1) {
+    const firstSegment = rawKey.slice(0, firstDot);
+    if (!TOP_LEVEL_KEYS.includes(firstSegment)) {
+      // It's a profile. Validate it.
+      const profile = firstSegment;
+      if (profile !== "default") {
+        throw new HardhatError(
+          HardhatError.ERRORS.CORE.SOLIDITY_TESTS.INLINE_CONFIG_UNSUPPORTED_PROFILE,
+          {
+            profile,
+            functionFqn,
+          },
+        );
+      }
+      // Strip the "default." prefix
+      parsedKey = rawKey.slice(firstDot + 1);
+    }
+  }
+
+  parsedKey = snakeToCamelCase(kebabToCamelCase(parsedKey));
+
+  return {
+    inputSourceName,
+    contractName,
+    functionName,
+    key: parsedKey,
+    rawKey,
+    rawValue,
+  };
+}

package/src/internal/builtin-plugins/solidity-test/inline-config/types.ts

@@ -0,0 +1,9 @@
+export interface RawInlineOverride {
+  inputSourceName: string;
+  contractName: string;
+  functionName: string;
+  functionSelector?: string; // from AST, hex without 0x prefix
+  key: string; // parsed camelCase key, without profile prefix
+  rawKey: string; // original key as written by the user, for error messages
+  rawValue: string;
+}

package/src/internal/builtin-plugins/solidity-test/inline-config/validation.ts

@@ -0,0 +1,122 @@
+import type { RawInlineOverride } from "./types.js";
+
+import { HardhatError } from "@nomicfoundation/hardhat-errors";
+
+import { KEY_TYPES } from "./constants.js";
+import { getFunctionFqn } from "./helpers.js";
+
+/**
+ * Validates a list of raw inline overrides, checking for:
+ * - Valid keys
+ * - No duplicate keys for the same function
+ * - Values of the expected type (numbers must be non-negative integers, booleans
+ *   must be "true" or "false")
+ *
+ * Throws a HardhatError if any validation fails.
+ */
+export function validateInlineOverrides(overrides: RawInlineOverride[]): void {
+  const seen = new Set<string>();
+
+  for (const {
+    inputSourceName,
+    contractName,
+    functionName,
+    functionSelector,
+    rawKey,
+    rawValue,
+    key,
+  } of overrides) {
+    const functionFqn = getFunctionFqn(
+      inputSourceName,
+      contractName,
+      functionName,
+    );
+
+    // Validate key
+    if (!Object.hasOwn(KEY_TYPES, key)) {
+      throw new HardhatError(
+        HardhatError.ERRORS.CORE.SOLIDITY_TESTS.INLINE_CONFIG_INVALID_KEY,
+        {
+          key: rawKey,
+          validKeys: Object.keys(KEY_TYPES).join(", "),
+          functionFqn,
+        },
+      );
+    }
+
+    // Validate key matches test type
+    const dotIndex = key.indexOf(".");
+    if (dotIndex !== -1) {
+      const keyCategory = key.slice(0, dotIndex);
+      const isFuzzTest = functionName.startsWith("test");
+      const isInvariantTest = functionName.startsWith("invariant");
+
+      if (
+        (isFuzzTest && keyCategory === "invariant") ||
+        (isInvariantTest && keyCategory === "fuzz")
+      ) {
+        const testType = isFuzzTest ? "fuzz" : "invariant";
+        const validPrefix = isFuzzTest ? "fuzz." : "invariant.";
+        const validKeys = Object.keys(KEY_TYPES)
+          .filter((k) => k.startsWith(validPrefix) || !k.includes("."))
+          .join(", ");
+
+        throw new HardhatError(
+          HardhatError.ERRORS.CORE.SOLIDITY_TESTS.INLINE_CONFIG_INVALID_KEY_FOR_TEST_TYPE,
+          {
+            key: rawKey,
+            functionFqn,
+            testType,
+            validKeys,
+          },
+        );
+      }
+    }
+
+    // Check for duplicates (include selector to allow same key on overloaded functions)
+    const functionId =
+      functionSelector !== undefined
+        ? `${functionFqn}#${functionSelector}`
+        : functionFqn;
+    const dedupeKey = `${functionId}-${key}`;
+    if (seen.has(dedupeKey)) {
+      throw new HardhatError(
+        HardhatError.ERRORS.CORE.SOLIDITY_TESTS.INLINE_CONFIG_DUPLICATE_KEY,
+        { key: rawKey, functionFqn },
+      );
+    }
+    seen.add(dedupeKey);
+
+    // Validate value type
+    const expectedType = KEY_TYPES[key];
+    if (expectedType === "number") {
+      if (
+        !/^(0|[1-9]\d*)$/.test(rawValue) ||
+        !Number.isSafeInteger(Number(rawValue))
+      ) {
+        throw new HardhatError(
+          HardhatError.ERRORS.CORE.SOLIDITY_TESTS.INLINE_CONFIG_INVALID_VALUE,
+          {
+            value: rawValue,
+            key: rawKey,
+            expectedType: "non-negative integer",
+            functionFqn,
+          },
+        );
+      }
+    } else {
+      const lowerValue = rawValue.toLowerCase();
+      if (lowerValue !== "true" && lowerValue !== "false") {
+        throw new HardhatError(
+          HardhatError.ERRORS.CORE.SOLIDITY_TESTS.INLINE_CONFIG_INVALID_VALUE,
+          {
+            value: rawValue,
+            key: rawKey,
+            expectedType: "boolean",
+            functionFqn,
+          },
+        );
+      }
+    }
+  }
+}

package/src/internal/builtin-plugins/solidity-test/reporter.ts

@@ -3,6 +3,7 @@ import type {
   TestReporterResult,
   TestStatus,
 } from "./types.js";
+import type { Colorizer } from "../../utils/colorizer.js";
 import type { TestResult } from "@nomicfoundation/edr";
 
 import { bytesToHexString } from "@nomicfoundation/hardhat-utils/hex";
@@ -11,12 +12,9 @@ import chalk from "chalk";
 import { sendErrorTelemetry } from "../../cli/telemetry/sentry/reporter.js";
 import { SolidityTestStackTraceGenerationError } from "../network-manager/edr/stack-traces/stack-trace-generation-errors.js";
 import { encodeStackTraceEntry } from "../network-manager/edr/stack-traces/stack-trace-solidity-errors.js";
+import { formatTraces } from "../network-manager/edr/utils/trace-formatters.js";
 
-import {
-  type Colorizer,
-  formatArtifactId,
-  formatTraces,
-} from "./formatters.js";
+import { formatArtifactId } from "./formatters.js";
 import { getMessageFromLastStackTraceEntry } from "./stack-trace-solidity-errors.js";
 
 class Indenter {
@@ -147,6 +145,8 @@ export async function* testReporter(
               suiteSuccessCount++;
               if (verbosity >= 5) {
                 printSetUpTraces = true;
+              }
+              if (verbosity >= 4) {
                 printExecutionTraces = true;
               }
               break;
@@ -184,7 +184,7 @@ export async function* testReporter(
               if (printSetUpTraces && functionName === "setUp") {
                 return true;
               }
-              if (printExecutionTraces && functionName !== "setUp()") {
+              if (printExecutionTraces && functionName !== "setUp") {
                 return true;
               }
               return false;