hardhat 3.3.0 → 3.4.0

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

@@ -17,13 +17,6 @@ import { getGlobalEdrContext } from "../../edr/context.js";
 
 import { formatArtifactId } from "./formatters.js";
 
-export interface RunOptions {
-  /**
-   * The maximum time in milliseconds to wait for all the test suites to finish.
-   */
-  timeout?: number;
-}
-
 /**
  * Run all the given solidity tests and returns the stream of results.
  *
@@ -38,7 +31,7 @@ export interface RunOptions {
  * Despite the changes, the signature of the function should still be considered
  * a draft that may change in the future.
  *
- * TODO: Once the signature is finalized, give feedback to the EDR team.
+ * Important TODO: Transform this into an AsyncGenerator<SuiteResult, SolidityTestResult, void>
  */
 export function run(
   chainType: ChainType,
@@ -47,88 +40,76 @@ export function run(
   testRunnerConfig: SolidityTestRunnerConfigArgs,
   tracingConfig: TracingConfigWithBuffers,
   sourceNameToUserSourceName: Map<string, string>,
-  options?: RunOptions,
 ): TestsStream {
-  const stream = new ReadableStream<TestEvent>({
-    async start(controller) {
-      if (testSuiteIds.length === 0) {
-        controller.close();
-        return;
-      }
-      let runCompleted = false;
+  const stream = new Readable({
+    objectMode: true,
+    read() {},
+  });
 
-      const remainingSuites = new Set(
-        testSuiteIds.map((id) =>
-          formatArtifactId(id, sourceNameToUserSourceName),
-        ),
-      );
+  if (testSuiteIds.length === 0) {
+    stream.push(null);
+    return stream;
+  }
 
-      let timeout: NodeJS.Timeout | undefined;
-      if (options?.timeout !== undefined) {
-        timeout = setTimeout(() => {
-          controller.error(
-            new HardhatError(
-              HardhatError.ERRORS.CORE.SOLIDITY_TESTS.RUNNER_TIMEOUT,
-              {
-                duration: options.timeout,
-                suites: Array.from(remainingSuites).join(", "),
-              },
-            ),
-          );
-        }, options.timeout);
-      }
+  let runCompleted = false;
 
-      // TODO: Add support for predeploys once EDR supports them.
-      try {
-        const edrContext = await getGlobalEdrContext();
-        const solidityTestResult = await edrContext.runSolidityTests(
-          hardhatChainTypeToEdrChainType(chainType),
-          artifacts,
-          testSuiteIds,
-          testRunnerConfig,
-          tracingConfig,
-          (suiteResult) => {
-            controller.enqueue({
-              type: "suite:done",
-              data: suiteResult,
-            });
-            remainingSuites.delete(
-              formatArtifactId(suiteResult.id, sourceNameToUserSourceName),
-            );
-            if (remainingSuites.size === 0) {
-              clearTimeout(timeout);
+  const remainingSuites = new Set(
+    testSuiteIds.map((id) => formatArtifactId(id, sourceNameToUserSourceName)),
+  );
 
-              if (runCompleted) {
-                controller.close();
-              }
+  // Start the async work immediately. The read() callback is a no-op
+  // because we push data proactively from the EDR suite-completion
+  // callback. Using a native Readable (instead of a web ReadableStream
+  // wrapped with Readable.from) avoids a race where Node.js stream
+  // cleanup cancels the web reader while the async start callback still
+  // has pending work — push() on a destroyed Readable is a safe no-op.
+  // TODO: Add support for predeploys once EDR supports them.
+  void (async () => {
+    try {
+      const edrContext = await getGlobalEdrContext();
+      const solidityTestResult = await edrContext.runSolidityTests(
+        hardhatChainTypeToEdrChainType(chainType),
+        artifacts,
+        testSuiteIds,
+        testRunnerConfig,
+        tracingConfig,
+        (suiteResult) => {
+          stream.push({
+            type: "suite:done",
+            data: suiteResult,
+          } satisfies TestEvent);
+          remainingSuites.delete(
+            formatArtifactId(suiteResult.id, sourceNameToUserSourceName),
+          );
+          if (remainingSuites.size === 0) {
+            if (runCompleted) {
+              stream.push(null);
             }
-          },
-        );
-        controller.enqueue({
-          type: "run:done",
-          data: solidityTestResult,
-        });
-        runCompleted = true;
-
-        if (remainingSuites.size === 0) {
-          controller.close();
-        }
-      } catch (error) {
-        ensureError(error);
-
-        clearTimeout(timeout);
+          }
+        },
+      );
+      stream.push({
+        type: "run:done",
+        data: solidityTestResult,
+      } satisfies TestEvent);
+      runCompleted = true;
 
-        controller.error(
-          new HardhatError(
-            HardhatError.ERRORS.CORE.SOLIDITY_TESTS.UNHANDLED_EDR_ERROR_SOLIDITY_TESTS,
-            {
-              error: error.message,
-            },
-          ),
-        );
+      if (remainingSuites.size === 0) {
+        stream.push(null);
       }
-    },
-  });
+    } catch (error) {
+      ensureError(error);
+
+      stream.destroy(
+        new HardhatError(
+          HardhatError.ERRORS.CORE.SOLIDITY_TESTS.UNHANDLED_EDR_ERROR_SOLIDITY_TESTS,
+          {
+            error: error.message,
+          },
+        ),
+      );
+    }
+  })();
 
-  return Readable.from(stream);
+  return stream;
 }

package/src/internal/builtin-plugins/solidity-test/stack-trace-solidity-errors.ts

@@ -2,7 +2,10 @@ import type { SolidityStackTraceEntry } from "../network-manager/edr/stack-trace
 
 import { panicErrorCodeToMessage } from "@nomicfoundation/hardhat-utils/panic-errors";
 
-import { StackTraceEntryType } from "../network-manager/edr/stack-traces/solidity-stack-trace.js";
+import {
+  StackTraceEntryType,
+  CheatcodeErrorCode,
+} from "../network-manager/edr/stack-traces/solidity-stack-trace.js";
 
 export function getMessageFromLastStackTraceEntry(
   stackTraceEntry: SolidityStackTraceEntry,
@@ -64,8 +67,18 @@ export function getMessageFromLastStackTraceEntry(
     case StackTraceEntryType.CUSTOM_ERROR:
       return stackTraceEntry.message;
 
-    case StackTraceEntryType.CHEATCODE_ERROR:
+    case StackTraceEntryType.CHEATCODE_ERROR: {
+      if (stackTraceEntry.details !== undefined) {
+        switch (stackTraceEntry.details.code) {
+          case CheatcodeErrorCode.UnsupportedCheatcode:
+            return `Cheatcode '${stackTraceEntry.details.cheatcode}' is not supported by Hardhat.`;
+          case CheatcodeErrorCode.MissingCheatcode:
+            return `Cheatcode '${stackTraceEntry.details.cheatcode}' is not yet available in this version of Hardhat.`;
+        }
+      }
+
       return stackTraceEntry.message;
+    }
 
     case StackTraceEntryType.CONTRACT_TOO_LARGE_ERROR:
       return "Trying to deploy a contract whose code is too large";

package/src/internal/builtin-plugins/solidity-test/task-action.ts

@@ -3,6 +3,10 @@ import type {
   EdrArtifactWithMetadata,
 } from "./edr-artifacts.js";
 import type { TestEvent } from "./types.js";
+import type {
+  BuildScope,
+  SolidityBuildSystem,
+} from "../../../types/solidity.js";
 import type { NewTaskActionFunction } from "../../../types/tasks.js";
 import type { TestRunResult } from "../../../types/test.js";
 import type { Result } from "../../../types/utils.js";
@@ -15,6 +19,7 @@ import type {
 import { finished } from "node:stream/promises";
 
 import { HardhatError } from "@nomicfoundation/hardhat-errors";
+import { exists } from "@nomicfoundation/hardhat-utils/fs";
 import { resolveFromRoot } from "@nomicfoundation/hardhat-utils/path";
 import { createNonClosingWriter } from "@nomicfoundation/hardhat-utils/stream";
 
@@ -23,7 +28,7 @@ import { errorResult, successfulResult } from "../../../utils/result.js";
 import { isSupportedChainType } from "../../edr/chain-type.js";
 import { ArtifactManagerImplementation } from "../artifacts/artifact-manager.js";
 import { getCoverageManager } from "../coverage/helpers.js";
-import { getGasAnalyticsManager } from "../gas-analytics/helpers.js";
+import { getGasAnalyticsManager } from "../gas-analytics/helpers/accessors.js";
 import { edrGasReportToHardhatGasMeasurements } from "../network-manager/edr/utils/convert-to-edr.js";
 
 import {
@@ -33,7 +38,6 @@ import {
 import {
   isTestSuiteArtifact,
   warnDeprecatedTestFail,
-  solidityTestConfigToRunOptions,
   solidityTestConfigToSolidityTestRunnerConfigArgs,
 } from "./helpers.js";
 import { getTestFunctionOverrides } from "./inline-config/index.js";
@@ -61,6 +65,18 @@ const runSolidityTests: NewTaskActionFunction<TestActionArguments> = async (
 
   const verbosity = hre.globalOptions.verbosity;
 
+  // NOTE: The resolution from CWD mimics what `build` does. It's important for
+  // both tasks to be aligned.
+  const resolvedTestFilesArgument = testFiles.map((f) =>
+    resolveFromRoot(process.cwd(), f),
+  );
+
+  await validateThatProvidedFilesAreTests(
+    hre.solidity,
+    testFiles,
+    resolvedTestFilesArgument,
+  );
+
   // Sets the NODE_ENV environment variable to "test" so the code can detect that tests are running
   // This is done by other JS/TS test frameworks like vitest
   process.env.NODE_ENV ??= "test";
@@ -76,34 +92,79 @@ const runSolidityTests: NewTaskActionFunction<TestActionArguments> = async (
     );
   }
 
-  // Run the build task for contract files if needed
-  if (noCompile !== true) {
-    await hre.tasks.getTask("build").run({
-      noTests: true,
-    });
-  }
+  let testRootPathsToRun: string[];
+  let edrArtifactsWithMetadata: EdrArtifactWithMetadata[];
+  let allBuildInfosAndOutputs: BuildInfoAndOutput[];
 
-  // Run the build task for test files
-  const { testRootPaths }: { testRootPaths: string[] } = await hre.tasks
-    .getTask("build")
-    .run({
-      files: testFiles,
-      noContracts: true,
-    });
-  console.log();
+  if (hre.config.solidity.splitTestsCompilation) {
+    if (noCompile !== true) {
+      await hre.tasks.getTask("build").run({
+        noTests: true,
+      });
+    }
 
-  // EDR needs all artifacts (contracts + tests)
-  const edrArtifactsWithMetadata: EdrArtifactWithMetadata[] = [];
-  const allBuildInfosAndOutputs: BuildInfoAndOutput[] = [];
-  for (const scope of ["contracts", "tests"] as const) {
-    const artifactsDir = await hre.solidity.getArtifactsDirectory(scope);
-    const artifactManager = new ArtifactManagerImplementation(artifactsDir);
-    edrArtifactsWithMetadata.push(
-      ...(await buildEdrArtifactsWithMetadata(artifactManager)),
-    );
-    allBuildInfosAndOutputs.push(
-      ...(await getBuildInfosAndOutputs(artifactManager)),
-    );
+    ({ testRootPaths: testRootPathsToRun } = await hre.tasks
+      .getTask("build")
+      .run({
+        files: testFiles,
+        noContracts: true,
+      }));
+    console.log();
+
+    ({ edrArtifactsWithMetadata, allBuildInfosAndOutputs } =
+      await loadArtifacts(hre.solidity, ["contracts", "tests"]));
+  } else {
+    if (noCompile !== true) {
+      ({ testRootPaths: testRootPathsToRun } = await hre.tasks
+        .getTask("build")
+        .run({
+          files: testFiles,
+        }));
+    } else {
+      if (resolvedTestFilesArgument.length > 0) {
+        testRootPathsToRun = resolvedTestFilesArgument;
+      } else {
+        testRootPathsToRun = [];
+        const allRoots = await hre.solidity.getRootFilePaths({
+          scope: "contracts",
+        });
+
+        for (const root of allRoots) {
+          if ((await hre.solidity.getScope(root)) === "tests") {
+            testRootPathsToRun.push(root);
+          }
+        }
+      }
+    }
+    console.log();
+
+    ({ edrArtifactsWithMetadata, allBuildInfosAndOutputs } =
+      await loadArtifacts(hre.solidity, ["contracts"]));
+
+    // When noCompile, validate selected test roots have compiled artifacts
+    if (noCompile === true) {
+      const compiledSources = new Set(
+        edrArtifactsWithMetadata.map(({ userSourceName }) =>
+          resolveFromRoot(hre.config.paths.root, userSourceName),
+        ),
+      );
+
+      const notCompiledFiles: string[] = [];
+      for (const root of testRootPathsToRun) {
+        if (!compiledSources.has(root)) {
+          notCompiledFiles.push(root);
+        }
+      }
+
+      if (notCompiledFiles.length > 0) {
+        throw new HardhatError(
+          HardhatError.ERRORS.CORE.SOLIDITY_TESTS.SELECTED_TEST_FILES_NOT_COMPILED,
+          {
+            files: notCompiledFiles.map((f) => `- ${f}`).join("\n"),
+          },
+        );
+      }
+    }
   }
 
   const sourceNameToUserSourceName = new Map(
@@ -113,25 +174,19 @@ const runSolidityTests: NewTaskActionFunction<TestActionArguments> = async (
     ]),
   );
 
-  edrArtifactsWithMetadata.forEach(({ userSourceName, edrArtifact }) => {
-    if (
-      testRootPaths.includes(
-        resolveFromRoot(hre.config.paths.root, userSourceName),
-      ) &&
-      isTestSuiteArtifact(edrArtifact)
-    ) {
-      warnDeprecatedTestFail(edrArtifact, sourceNameToUserSourceName);
-    }
-  });
-
+  const testRootPathsSet = new Set(testRootPathsToRun);
   const testSuiteArtifacts = edrArtifactsWithMetadata
     .filter(({ userSourceName }) =>
-      testRootPaths.includes(
+      testRootPathsSet.has(
         resolveFromRoot(hre.config.paths.root, userSourceName),
       ),
     )
     .filter(({ edrArtifact }) => isTestSuiteArtifact(edrArtifact));
 
+  for (const { edrArtifact } of testSuiteArtifacts) {
+    warnDeprecatedTestFail(edrArtifact, sourceNameToUserSourceName);
+  }
+
   const testSuiteIds = testSuiteArtifacts.map(
     ({ edrArtifact }) => edrArtifact.id,
   );
@@ -195,8 +250,6 @@ const runSolidityTests: NewTaskActionFunction<TestActionArguments> = async (
     })),
     ignoreContracts: false,
   };
-  const runOptions = solidityTestConfigToRunOptions(solidityTestConfig);
-
   await hre.hooks.runHandlerChain(
     "test",
     "onTestRunStart",
@@ -211,7 +264,6 @@ const runSolidityTests: NewTaskActionFunction<TestActionArguments> = async (
     testRunnerConfig,
     tracingConfig,
     sourceNameToUserSourceName,
-    runOptions,
   );
 
   let failed = 0;
@@ -314,4 +366,70 @@ const runSolidityTests: NewTaskActionFunction<TestActionArguments> = async (
     : successfulResult(result);
 };
 
+/**
+ * Validates that the test files provided by the user, resolved in this case,
+ * are actually test files.
+ *
+ * @param solidity The solidity build system
+ * @param testFiles The test files, as provided by the user
+ * @param resolvedTestFilesArgument The resolved testFiles
+ */
+async function validateThatProvidedFilesAreTests(
+  solidity: SolidityBuildSystem,
+  testFiles: string[],
+  resolvedTestFilesArgument: string[],
+) {
+  const existsResults = await Promise.all(
+    resolvedTestFilesArgument.map((rootPath) => exists(rootPath)),
+  );
+
+  const missing: string[] = testFiles.filter((_, i) => !existsResults[i]);
+
+  if (missing.length > 0) {
+    throw new HardhatError(
+      HardhatError.ERRORS.CORE.SOLIDITY_TESTS.SELECTED_TEST_FILES_DO_NOT_EXIST,
+      {
+        files: missing.map((f) => `- ${f}`).join("\n"),
+      },
+    );
+  }
+
+  const scopes = await Promise.all(
+    resolvedTestFilesArgument.map((rootPath) => solidity.getScope(rootPath)),
+  );
+
+  const nonTests: string[] = testFiles.filter((_, i) => scopes[i] !== "tests");
+
+  if (nonTests.length > 0) {
+    throw new HardhatError(
+      HardhatError.ERRORS.CORE.SOLIDITY_TESTS.SELECTED_FILES_ARE_NOT_SOLIDITY_TESTS,
+      {
+        files: nonTests.map((f) => `- ${f}`).join("\n"),
+      },
+    );
+  }
+}
+
+async function loadArtifacts(
+  solidity: SolidityBuildSystem,
+  scopes: BuildScope[],
+): Promise<{
+  edrArtifactsWithMetadata: EdrArtifactWithMetadata[];
+  allBuildInfosAndOutputs: BuildInfoAndOutput[];
+}> {
+  const edrArtifactsWithMetadata: EdrArtifactWithMetadata[] = [];
+  const allBuildInfosAndOutputs: BuildInfoAndOutput[] = [];
+  for (const scope of scopes) {
+    const artifactsDir = await solidity.getArtifactsDirectory(scope);
+    const artifactManager = new ArtifactManagerImplementation(artifactsDir);
+    edrArtifactsWithMetadata.push(
+      ...(await buildEdrArtifactsWithMetadata(artifactManager)),
+    );
+    allBuildInfosAndOutputs.push(
+      ...(await getBuildInfosAndOutputs(artifactManager)),
+    );
+  }
+  return { edrArtifactsWithMetadata, allBuildInfosAndOutputs };
+}
+
 export default runSolidityTests;

package/src/internal/builtin-plugins/solidity-test/type-extensions.ts

@@ -31,7 +31,6 @@ declare module "../../../types/test.js" {
   }
 
   export interface SolidityTestConfigBase {
-    timeout?: number;
     fsPermissions?: {
       readWriteFile?: string[];
       readFile?: string[];
@@ -69,7 +68,7 @@ declare module "../../../types/test.js" {
 
   export interface SolidityTestForkingUserConfig {
     url?: SensitiveString;
-    blockNumber?: bigint;
+    blockNumber?: number | bigint;
     rpcEndpoints?: Record<string, SensitiveString>;
   }
 

package/src/internal/builtin-plugins/test/task-action.ts

@@ -17,7 +17,7 @@ import {
   successfulResult,
 } from "../../../utils/result.js";
 import { getCoverageManager } from "../coverage/helpers.js";
-import { getGasAnalyticsManager } from "../gas-analytics/helpers.js";
+import { getGasAnalyticsManager } from "../gas-analytics/helpers/accessors.js";
 
 interface TestActionArguments {
   testFiles: string[];
@@ -64,9 +64,8 @@ const runAllTests: NewTaskActionFunction<TestActionArguments> = async (
   const thisTask = hre.tasks.getTask("test");
 
   if (!noCompile) {
-    await hre.tasks.getTask("build").run({
-      noTests: true,
-    });
+    const noTests = hre.config.solidity.splitTestsCompilation;
+    await hre.tasks.getTask("build").run({ noTests });
   }
 
   if (hre.globalOptions.coverage === true) {

package/src/internal/cli/main.ts

@@ -236,6 +236,20 @@ export async function main(
         log("Error showing banner", bannerError);
       }
     }
+
+    const deprecatedConnectWasCalled = Boolean(
+      "wasConnectCalled" in hre.network &&
+        hre.network.wasConnectCalled !== undefined &&
+        typeof hre.network.wasConnectCalled === "function" &&
+        hre.network.wasConnectCalled(),
+    );
+
+    if (deprecatedConnectWasCalled) {
+      console.warn(
+        "WARNING: hre.network.connect() is deprecated and will be removed in a future version. " +
+          "Use hre.network.create() or hre.network.getOrCreate() instead.",
+      );
+    }
   } catch (error) {
     ensureError(error);
     printErrorMessages(error, builtinGlobalOptions?.showStackTraces);

package/src/types/artifacts.ts

@@ -89,11 +89,11 @@ export interface ArtifactManager {
   /**
    * Returns true if an artifact exists.
    *
-   * This function doesn't throw if the name is not unique.
+   * This function doesn't throw if the name is not unique, this means that
+   * this method may return `true`, and a successive call to `readArtifact` can
+   * throw because of a duplicated name.
    *
    * @param contractNameOrFullyQualifiedName Contract or fully qualified name.
-   * @throws Throws an error if a non-unique contract name is used,
-   *   indicating which fully qualified names can be used instead.
    */
   artifactExists(contractNameOrFullyQualifiedName: string): Promise<boolean>;
 
@@ -120,7 +120,8 @@ export interface ArtifactManager {
    * If it does return an id, it's not guaranteed that the build info is
    * present.
    *
-   * @param contractNameOrFullyQualifiedName Contract or fully qualified name, whose artifact must exist.
+   * @param contractNameOrFullyQualifiedName Contract or fully qualified name,
+   *  whose artifact must exist.
    * @throws Throws an error if a non-unique contract name is used,
    *   indicating which fully qualified names can be used instead.
    * @throws Throws an error if the artifact doesn't exist.

package/src/types/network.ts

@@ -48,11 +48,59 @@ export interface NetworkConnectionParams<
   override?: NetworkConfigOverride;
 }
 
+export interface CachedNetworkConnectionParams<
+  ChainTypeT extends ChainType | string = DefaultChainType,
+> extends NetworkConnectionParams<ChainTypeT> {
+  override?: never;
+}
+
 export interface NetworkManager {
+  /**
+   * Creates a new network connection based on the provided parameters.
+   *
+   * @param networkOrParams The network name or connection parameters. When
+   * omitted, the default network is used.
+   *
+   * @returns A new {@link NetworkConnection} for the specified network.
+   */
+  create<ChainTypeT extends ChainType | string = DefaultChainType>(
+    networkOrParams?: NetworkConnectionParams<ChainTypeT> | string,
+  ): Promise<NetworkConnection<ChainTypeT>>;
+
+  /**
+   * Creates a new network connection based on the provided parameters.
+   *
+   * @deprecated Use {@link NetworkManager.create} or
+   * {@link NetworkManager.getOrCreate} instead.
+   *
+   * - {@link NetworkManager.create} always creates a new network instance.
+   * - {@link NetworkManager.getOrCreate} returns an existing instance if one exists.
+   *
+   * `connect` will be removed in a future version of Hardhat.
+   *
+   * @param networkOrParams The network name or connection parameters. When
+   * omitted, the default network is used.
+   *
+   * @returns A new {@link NetworkConnection} for the specified network.
+   */
   connect<ChainTypeT extends ChainType | string = DefaultChainType>(
     networkOrParams?: NetworkConnectionParams<ChainTypeT> | string,
   ): Promise<NetworkConnection<ChainTypeT>>;
 
+  /**
+   * Returns an existing network connection if one was previously created
+   * with the same network name and chain type. Creates a new one otherwise.
+   *
+   * @param networkOrParams The network name or connection parameters. When
+   * omitted, the default network is used. Overrides are not supported.
+   *
+   * @returns A {@link NetworkConnection} for the specified network, cached
+   * by network name and chain type.
+   */
+  getOrCreate<ChainTypeT extends ChainType | string = DefaultChainType>(
+    networkOrParams?: CachedNetworkConnectionParams<ChainTypeT> | string,
+  ): Promise<NetworkConnection<ChainTypeT>>;
+
   /**
    * Spawns an Ethereum JSON-RPC server listening on HTTP and Websocket.
    *