hardhat 3.1.12 → 3.3.0

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

@@ -2,17 +2,18 @@ import type { RunOptions } from "./runner.js";
 import type { Abi } from "../../../types/artifacts.js";
 import type { ChainType } from "../../../types/network.js";
 import type { SolidityTestConfig } from "../../../types/test.js";
+import type { Colorizer } from "../../utils/colorizer.js";
 import type {
   SolidityTestRunnerConfigArgs,
   PathPermission,
   Artifact,
   ObservabilityConfig,
+  TestFunctionOverride,
 } from "@nomicfoundation/edr";
 
 import {
   opGenesisState,
   l1GenesisState,
-  IncludeTraces,
   FsAccessPermission,
   CollectStackTraces,
   opHardforkFromString,
@@ -24,8 +25,9 @@ import chalk from "chalk";
 import { DEFAULT_VERBOSITY, OPTIMISM_CHAIN_TYPE } from "../../constants.js";
 import { resolveHardfork } from "../network-manager/config-resolution.js";
 import { hardhatHardforkToEdrSpecId } from "../network-manager/edr/utils/convert-to-edr.js";
+import { verbosityToIncludeTraces } from "../network-manager/edr/utils/trace-formatters.js";
 
-import { type Colorizer, formatArtifactId } from "./formatters.js";
+import { formatArtifactId } from "./formatters.js";
 
 interface SolidityTestConfigParams {
   chainType: ChainType;
@@ -36,6 +38,7 @@ interface SolidityTestConfigParams {
   observability?: ObservabilityConfig;
   testPattern?: string;
   generateGasReport: boolean;
+  testFunctionOverrides?: TestFunctionOverride[];
 }
 
 export function solidityTestConfigToRunOptions(
@@ -53,6 +56,7 @@ export async function solidityTestConfigToSolidityTestRunnerConfigArgs({
   observability,
   testPattern,
   generateGasReport,
+  testFunctionOverrides,
 }: SolidityTestConfigParams): Promise<SolidityTestRunnerConfigArgs> {
   const fsPermissions: PathPermission[] | undefined = [
     config.fsPermissions?.readWriteFile?.map((p) => ({
@@ -98,12 +102,7 @@ export async function solidityTestConfigToSolidityTestRunnerConfigArgs({
       ? opGenesisState(opHardforkFromString(resolvedHardfork))
       : l1GenesisState(l1HardforkFromString(resolvedHardfork));
 
-  let includeTraces: IncludeTraces = IncludeTraces.None;
-  if (verbosity >= 5) {
-    includeTraces = IncludeTraces.All;
-  } else if (verbosity >= 3) {
-    includeTraces = IncludeTraces.Failing;
-  }
+  const includeTraces = verbosityToIncludeTraces(verbosity);
 
   const blockGasLimit =
     config.blockGasLimit === false ? undefined : config.blockGasLimit;
@@ -152,6 +151,7 @@ export async function solidityTestConfigToSolidityTestRunnerConfigArgs({
     collectStackTraces: shouldAlwaysCollectStackTraces
       ? CollectStackTraces.Always
       : CollectStackTraces.OnFailure,
+    testFunctionOverrides,
   };
 }
 

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

@@ -2,7 +2,6 @@ import type { HardhatPlugin } from "../../../types/plugins.js";
 
 import { ArgumentType } from "hardhat/types/arguments";
 
-import { DEFAULT_VERBOSITY } from "../../constants.js";
 import { task } from "../../core/config.js";
 
 import "./type-extensions.js";
@@ -35,12 +34,6 @@ const hardhatPlugin: HardhatPlugin = {
         name: "noCompile",
         description: "Don't compile the project before running the tests",
       })
-      .addLevel({
-        name: "verbosity",
-        shortName: "v",
-        description: "Verbosity level of the test output",
-        defaultValue: DEFAULT_VERBOSITY,
-      })
       .addOption({
         name: "testSummaryIndex",
         description:

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

@@ -0,0 +1,21 @@
+export const HARDHAT_CONFIG_PREFIX = "hardhat-config:";
+export const FORGE_CONFIG_PREFIX = "forge-config:";
+
+/** All supported inline config keys and their expected value types. */
+export const KEY_TYPES: Record<string, "number" | "boolean"> = {
+  "fuzz.runs": "number",
+  "fuzz.maxTestRejects": "number",
+  "fuzz.showLogs": "boolean",
+  "fuzz.timeout": "number",
+  "invariant.runs": "number",
+  "invariant.depth": "number",
+  "invariant.failOnRevert": "boolean",
+  "invariant.callOverride": "boolean",
+  "invariant.timeout": "number",
+  allowInternalExpectRevert: "boolean",
+};
+
+/** Top-level key categories (e.g. "fuzz", "invariant", "allowInternalExpectRevert"). */
+export const TOP_LEVEL_KEYS: string[] = [
+  ...new Set(Object.keys(KEY_TYPES).map((k) => k.split(".")[0])),
+];

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

@@ -0,0 +1,99 @@
+import type { RawInlineOverride } from "./types.js";
+import type { TestFunctionConfigOverride } from "@nomicfoundation/edr";
+
+import { bytesIncludesUtf8String } from "@nomicfoundation/hardhat-utils/bytes";
+
+import { getFullyQualifiedName } from "../../../../utils/contract-names.js";
+
+import {
+  HARDHAT_CONFIG_PREFIX,
+  FORGE_CONFIG_PREFIX,
+  KEY_TYPES,
+} from "./constants.js";
+
+/**
+ * Returns true if the build info bytes contain either of the inline config
+ * prefixes.
+ */
+export function buildInfoContainsInlineConfig(
+  buildInfoBytes: Uint8Array,
+): boolean {
+  return (
+    bytesIncludesUtf8String(buildInfoBytes, HARDHAT_CONFIG_PREFIX) ||
+    bytesIncludesUtf8String(buildInfoBytes, FORGE_CONFIG_PREFIX)
+  );
+}
+
+/**
+ * Finds the function selector for a given function name in the methodIdentifiers
+ * map. Matches the first entry whose signature starts with `functionName(`.
+ * Returns the selector prefixed with "0x".
+ */
+export function resolveFunctionSelector(
+  methodIdentifiers: Record<string, string>,
+  functionName: string,
+): string | undefined {
+  const prefix = `${functionName}(`;
+
+  for (const [signature, selector] of Object.entries(methodIdentifiers)) {
+    if (signature.startsWith(prefix)) {
+      return `0x${selector}`;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Converts a validated set of raw overrides into a TestFunctionConfigOverride
+ * object.
+ */
+export function buildConfigOverride(
+  overrides: RawInlineOverride[],
+): TestFunctionConfigOverride {
+  const config: Record<string, unknown> = {};
+  const fuzz: Record<string, unknown> = {};
+  const invariant: Record<string, unknown> = {};
+
+  for (const override of overrides) {
+    const expectedType = KEY_TYPES[override.key];
+    const parsed =
+      expectedType === "number"
+        ? Number(override.rawValue)
+        : override.rawValue.toLowerCase() === "true";
+
+    const dotIndex = override.key.indexOf(".");
+    if (dotIndex === -1) {
+      // Top-level key, like "allowInternalExpectRevert"
+      config[override.key] = parsed;
+    } else {
+      const section = override.key.slice(0, dotIndex);
+      const field = override.key.slice(dotIndex + 1);
+      const target = section === "fuzz" ? fuzz : invariant;
+      target[field] = field === "timeout" ? { time: parsed } : parsed;
+    }
+  }
+
+  if (Object.keys(fuzz).length > 0) {
+    config.fuzz = fuzz;
+  }
+  if (Object.keys(invariant).length > 0) {
+    config.invariant = invariant;
+  }
+
+  /* eslint-disable-next-line @typescript-eslint/consistent-type-assertions --
+  Cast is safe because we have validated all keys and value types in the previous step. */
+  return config as TestFunctionConfigOverride;
+}
+
+/**
+ * Constructs a fully qualified function name, in the format
+ * "source.sol:ContractName#functionName".
+ */
+export function getFunctionFqn(
+  inputSourceName: string,
+  contractName: string,
+  functionName: string,
+): string {
+  return `${getFullyQualifiedName(inputSourceName, contractName)}#${functionName}`;
+}

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;
+}