hardhat 3.1.10 → 3.1.12

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

@@ -4,13 +4,21 @@ import type {
   Task,
   TaskArguments,
 } from "../../../types/tasks.js";
+import type { TestSummary } from "../../../types/test.js";
+import type { Result } from "../../../types/utils.js";
 
 import {
   assertHardhatInvariant,
   HardhatError,
 } from "@nomicfoundation/hardhat-errors";
+import { isObject } from "@nomicfoundation/hardhat-utils/lang";
 import chalk, { type ChalkInstance } from "chalk";
 
+import {
+  errorResult,
+  isResult,
+  successfulResult,
+} from "../../../utils/result.js";
 import { HardhatRuntimeEnvironmentImplementation } from "../../core/hre.js";
 
 interface TestActionArguments {
@@ -21,10 +29,33 @@ interface TestActionArguments {
   verbosity: number;
 }
 
+// Old plugins may only return { failed, passed } without skipped/todo,
+// so we accept a partial shape and fill defaults in the coordinator.
+interface PartialTestSummary extends Omit<TestSummary, "skipped" | "todo"> {
+  skipped?: number;
+  todo?: number;
+}
+
+function isTestSummary(value: unknown): value is PartialTestSummary {
+  return (
+    isObject(value) &&
+    typeof value.failed === "number" &&
+    typeof value.passed === "number" &&
+    (value.skipped === undefined || typeof value.skipped === "number") &&
+    (value.todo === undefined || typeof value.todo === "number")
+  );
+}
+
+function isTestRunResult(
+  value: unknown,
+): value is { summary: PartialTestSummary } {
+  return isObject(value) && "summary" in value && isTestSummary(value.summary);
+}
+
 const runAllTests: NewTaskActionFunction<TestActionArguments> = async (
-  { testFiles, chainType, grep, noCompile, verbosity },
+  { testFiles, chainType, grep, noCompile, verbosity, ...otherArgs },
   hre,
-) => {
+): Promise<Result<void, void>> => {
   // If this code is executed, it means the user has not specified a test runner.
   // If file paths are specified, we need to determine which test runner applies to each test file.
   // If no file paths are specified, each test runner will execute all tests located under its configured path in the Hardhat configuration.
@@ -49,18 +80,10 @@ const runAllTests: NewTaskActionFunction<TestActionArguments> = async (
     hre._coverage.disableReport();
   }
 
-  const testSummaries: Record<
-    string,
-    {
-      failed?: number;
-      passed?: number;
-      skipped?: number;
-      todo?: number;
-      failureOutput?: string;
-    }
-  > = {};
+  const testSummaries: Record<string, TestSummary> = {};
 
   let failureIndex = 1;
+  let hasFailures = false;
   for (const subtask of thisTask.subtasks.values()) {
     const files = getTestFilesForSubtask(subtask, testFiles, subtasksToFiles);
 
@@ -84,18 +107,57 @@ const runAllTests: NewTaskActionFunction<TestActionArguments> = async (
       args.verbosity = verbosity;
     }
 
-    const summaryId = subtask.id[subtask.id.length - 1];
+    for (const [key, value] of Object.entries(otherArgs)) {
+      if (subtask.options.has(key)) {
+        args[key] = value;
+      }
+    }
 
     if (subtask.options.has("testSummaryIndex")) {
       args.testSummaryIndex = failureIndex;
+    }
 
-      testSummaries[summaryId] = await subtask.run(args);
-      failureIndex += testSummaries[summaryId].failed ?? 0;
-    } else if (summaryId === "mocha") {
-      // mocha doesn't use the testSummaryIndex, but it does return failure & success counts
-      testSummaries[summaryId] = await subtask.run(args);
+    const subtaskResult = await subtask.run(args);
+
+    let summary: PartialTestSummary | undefined;
+    let subtaskFailed = false;
+
+    if (isResult(subtaskResult, isTestRunResult, isTestRunResult)) {
+      const testRunResult = subtaskResult.success
+        ? subtaskResult.value
+        : subtaskResult.error;
+      summary = testRunResult.summary;
+      subtaskFailed = !subtaskResult.success;
+    } else if (isResult(subtaskResult, isTestSummary, isTestSummary)) {
+      // Support plugins that return Result<TestSummary, TestSummary>
+      summary = subtaskResult.success
+        ? subtaskResult.value
+        : subtaskResult.error;
+      subtaskFailed = !subtaskResult.success;
+    } else if (isTestSummary(subtaskResult)) {
+      // Support plugins that return TestSummary directly
+      summary = subtaskResult;
+      subtaskFailed = process.exitCode !== undefined && process.exitCode !== 0;
     } else {
-      await subtask.run(args);
+      // Fallback for plugins that don't return a summary at all
+      subtaskFailed = process.exitCode !== undefined && process.exitCode !== 0;
+    }
+
+    if (summary !== undefined) {
+      const summaryId = subtask.id[subtask.id.length - 1];
+      testSummaries[summaryId] = {
+        skipped: 0,
+        todo: 0,
+        ...summary,
+      };
+
+      if (subtask.options.has("testSummaryIndex")) {
+        failureIndex += summary.failed;
+      }
+    }
+
+    if (subtaskFailed) {
+      hasFailures = true;
     }
   }
 
@@ -106,19 +168,19 @@ const runAllTests: NewTaskActionFunction<TestActionArguments> = async (
   const outputLines: string[] = [];
 
   for (const [subtaskName, results] of Object.entries(testSummaries)) {
-    if (results.passed !== undefined && results.passed > 0) {
+    if (results.passed > 0) {
       passed.push([subtaskName, results.passed]);
     }
 
-    if (results.failed !== undefined && results.failed > 0) {
+    if (results.failed > 0) {
       failed.push([subtaskName, results.failed]);
     }
 
-    if (results.skipped !== undefined && results.skipped > 0) {
+    if (results.skipped > 0) {
       skipped.push([subtaskName, results.skipped]);
     }
 
-    if (results.todo !== undefined && results.todo > 0) {
+    if (results.todo > 0) {
       todo.push([subtaskName, results.todo]);
     }
 
@@ -176,9 +238,11 @@ const runAllTests: NewTaskActionFunction<TestActionArguments> = async (
     console.log();
   }
 
-  if (process.exitCode !== undefined && process.exitCode !== 0) {
+  if (hasFailures) {
     console.error("Test run failed");
   }
+
+  return hasFailures ? errorResult() : successfulResult();
 };
 
 function logSummaryLine(

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

@@ -39,5 +39,47 @@ declare module "../../../types/hooks.js" {
         filePath: string,
       ) => Promise<string | undefined>,
     ) => Promise<string | undefined>;
+
+    /**
+     * This hook is triggered at the start of a test run, before tests execute.
+     *
+     * @param context The hook context.
+     * @param id A string identifier for the test runner (e.g., "solidity", "nodejs", "mocha").
+     * @param next A function to call the next handler for this hook, or the
+     * default implementation if no more handlers exist.
+     */
+    onTestRunStart: (
+      context: HookContext,
+      id: string,
+      next: (nextContext: HookContext, id: string) => Promise<void>,
+    ) => Promise<void>;
+
+    /**
+     * This hook is triggered when a test worker has finished executing.
+     *
+     * @param context The hook context.
+     * @param id A string identifier for the test runner (e.g., "solidity", "nodejs", "mocha").
+     * @param next A function to call the next handler for this hook, or the
+     * default implementation if no more handlers exist.
+     */
+    onTestWorkerDone: (
+      context: HookContext,
+      id: string,
+      next: (nextContext: HookContext, id: string) => Promise<void>,
+    ) => Promise<void>;
+
+    /**
+     * This hook is triggered at the end of a test run, after all tests have completed.
+     *
+     * @param context The hook context.
+     * @param id A string identifier for the test runner (e.g., "solidity", "nodejs", "mocha").
+     * @param next A function to call the next handler for this hook, or the
+     * default implementation if no more handlers exist.
+     */
+    onTestRunDone: (
+      context: HookContext,
+      id: string,
+      next: (nextContext: HookContext, id: string) => Promise<void>,
+    ) => Promise<void>;
   }
 }

package/src/internal/cli/banner-manager.ts

@@ -0,0 +1,234 @@
+import type { Dispatcher } from "@nomicfoundation/hardhat-utils/request";
+
+import path from "node:path";
+
+import {
+  readJsonFile,
+  writeJsonFile,
+  FileNotFoundError,
+} from "@nomicfoundation/hardhat-utils/fs";
+import { getCacheDir } from "@nomicfoundation/hardhat-utils/global-dir";
+import { isObject } from "@nomicfoundation/hardhat-utils/lang";
+import { getRequest } from "@nomicfoundation/hardhat-utils/request";
+import debug from "debug";
+
+const log = debug("hardhat:util:banner-manager");
+
+interface BannerConfig {
+  enabled: boolean;
+  formattedMessages: string[];
+  minSecondsBetweenDisplays: number;
+  minSecondsBetweenRequests: number;
+}
+
+export const BANNER_CONFIG_URL =
+  "https://raw.githubusercontent.com/NomicFoundation/hardhat/refs/heads/main/banner-config-v3.json";
+
+export const BANNER_CACHE_FILE_NAME = "banner-config-v3.json";
+
+export class BannerManager {
+  static #instance: BannerManager | undefined;
+
+  #bannerConfig: BannerConfig | undefined;
+  #lastDisplayTime: number;
+  #lastRequestTime: number;
+  readonly #dispatcher: Dispatcher | undefined;
+  readonly #print: (message: string) => void;
+
+  private constructor(
+    bannerConfig: BannerConfig | undefined,
+    lastDisplayTime: number,
+    lastRequestTime: number,
+    dispatcher: Dispatcher | undefined,
+    print: (message: string) => void,
+  ) {
+    this.#bannerConfig = bannerConfig;
+    this.#lastDisplayTime = lastDisplayTime;
+    this.#lastRequestTime = lastRequestTime;
+    this.#dispatcher = dispatcher;
+    this.#print = print;
+  }
+
+  /**
+   * Returns a global instance of BannerManager.
+   *
+   * @param options Options used for testing purposes. Only used in the first
+   * invocation of this function, or after calling `resetInstance`.
+   * @returns The current global instance of BannerManager.
+   */
+  public static async getInstance(options?: {
+    testDispatcher?: Dispatcher;
+    print?: (message: string) => void;
+  }): Promise<BannerManager> {
+    if (this.#instance === undefined) {
+      log("Initializing BannerManager");
+      const { bannerConfig, lastDisplayTime, lastRequestTime } =
+        await readCache();
+      this.#instance = new BannerManager(
+        bannerConfig,
+        lastDisplayTime,
+        lastRequestTime,
+        options?.testDispatcher,
+        options?.print ?? console.log,
+      );
+    }
+
+    return this.#instance;
+  }
+
+  public static resetInstance(): void {
+    this.#instance = undefined;
+  }
+
+  /**
+   * Displays a banner message, if any.
+   *
+   * @param timeout The timeout in milliseconds to wait for the banner display.
+   */
+  public async showBanner(timeout?: number): Promise<void> {
+    await this.#requestBannerConfig(timeout);
+
+    if (
+      this.#bannerConfig === undefined ||
+      !this.#bannerConfig.enabled ||
+      this.#bannerConfig.formattedMessages.length === 0
+    ) {
+      log("Banner is disabled or no messages available.");
+      return;
+    }
+
+    const { formattedMessages, minSecondsBetweenDisplays } = this.#bannerConfig;
+
+    const timeSinceLastDisplay = Date.now() - this.#lastDisplayTime;
+    if (timeSinceLastDisplay < minSecondsBetweenDisplays * 1000) {
+      log(
+        `Skipping banner display. Time since last display: ${timeSinceLastDisplay}ms`,
+      );
+      return;
+    }
+
+    // select a random message from the formattedMessages array
+    const randomIndex = Math.floor(Math.random() * formattedMessages.length);
+    const message = formattedMessages[randomIndex];
+
+    this.#print(message);
+    this.#lastDisplayTime = Date.now();
+    await writeCache({
+      bannerConfig: this.#bannerConfig,
+      lastDisplayTime: this.#lastDisplayTime,
+      lastRequestTime: this.#lastRequestTime,
+    });
+  }
+
+  async #requestBannerConfig(timeout?: number): Promise<void> {
+    if (this.#bannerConfig !== undefined) {
+      const timeSinceLastRequest = Date.now() - this.#lastRequestTime;
+      if (
+        timeSinceLastRequest <
+        this.#bannerConfig.minSecondsBetweenRequests * 1000
+      ) {
+        log(
+          `Skipping banner config request. Time since last request: ${timeSinceLastRequest}ms`,
+        );
+        return;
+      }
+    }
+
+    try {
+      const response = await getRequest(
+        BANNER_CONFIG_URL,
+        undefined,
+        this.#dispatcher ?? { timeout },
+      );
+
+      const bannerConfig: unknown = await response.body.json();
+
+      if (!this.#isBannerConfig(bannerConfig)) {
+        log(`Invalid banner config received:`, bannerConfig);
+        return;
+      }
+
+      this.#bannerConfig = bannerConfig;
+      this.#lastRequestTime = Date.now();
+
+      await writeCache({
+        bannerConfig: this.#bannerConfig,
+        lastDisplayTime: this.#lastDisplayTime,
+        lastRequestTime: this.#lastRequestTime,
+      });
+    } catch (error) {
+      log(
+        `Error requesting banner config: ${
+          error instanceof Error ? error.message : JSON.stringify(error)
+        }`,
+      );
+    }
+  }
+
+  #isBannerConfig(value: unknown): value is BannerConfig {
+    if (!isObject(value)) {
+      return false;
+    }
+
+    return (
+      Object.getOwnPropertyNames(value).length === 4 &&
+      "enabled" in value &&
+      typeof value.enabled === "boolean" &&
+      "formattedMessages" in value &&
+      Array.isArray(value.formattedMessages) &&
+      value.formattedMessages.every(
+        (message: unknown) => typeof message === "string",
+      ) &&
+      "minSecondsBetweenDisplays" in value &&
+      typeof value.minSecondsBetweenDisplays === "number" &&
+      "minSecondsBetweenRequests" in value &&
+      typeof value.minSecondsBetweenRequests === "number"
+    );
+  }
+}
+
+interface BannerCache {
+  bannerConfig: BannerConfig | undefined;
+  lastDisplayTime: number;
+  lastRequestTime: number;
+}
+
+async function readCache(): Promise<BannerCache> {
+  const cacheDir = await getCacheDir();
+  const bannerCacheFilePath = path.join(cacheDir, BANNER_CACHE_FILE_NAME);
+
+  try {
+    return await readJsonFile<BannerCache>(bannerCacheFilePath);
+  } catch (error) {
+    if (error instanceof FileNotFoundError) {
+      log("No banner cache file found, using defaults");
+    } else {
+      log(
+        `Error reading cache file: ${
+          error instanceof Error ? error.message : JSON.stringify(error)
+        }`,
+      );
+    }
+
+    return {
+      bannerConfig: undefined,
+      lastDisplayTime: 0,
+      lastRequestTime: 0,
+    };
+  }
+}
+
+async function writeCache(cache: BannerCache): Promise<void> {
+  const cacheDir = await getCacheDir();
+  const bannerCacheFilePath = path.join(cacheDir, BANNER_CACHE_FILE_NAME);
+
+  try {
+    await writeJsonFile(bannerCacheFilePath, cache);
+  } catch (error) {
+    log(
+      `Error writing cache file: ${
+        error instanceof Error ? error.message : JSON.stringify(error)
+      }`,
+    );
+  }
+}

package/src/internal/cli/init/init.ts

@@ -131,6 +131,14 @@ export async function initHardhat(options?: InitHardhatOptions): Promise<void> {
     ]);
 
     showStarOnGitHubMessage();
+
+    try {
+      const { BannerManager } = await import("../banner-manager.js");
+      const bannerManager = await BannerManager.getInstance();
+      await bannerManager.showBanner();
+    } catch (bannerError) {
+      log("Error showing banner", bannerError);
+    }
   } catch (e) {
     if (e === "") {
       // If the user cancels any prompt, we quit silently

package/src/internal/cli/main.ts

@@ -28,6 +28,7 @@ import {
   type OptionDefinition,
   type PositionalArgumentDefinition,
 } from "../../types/arguments.js";
+import { isResult } from "../../utils/result.js";
 import { BUILTIN_GLOBAL_OPTIONS_DEFINITIONS } from "../builtin-global-options.js";
 import { builtinPlugins } from "../builtin-plugins/index.js";
 import {
@@ -217,7 +218,24 @@ export async function main(
 
     log(`Running task "${task.id.join(" ")}"`);
 
-    await Promise.all([task.run(taskArguments), sendTaskAnalytics(task.id)]);
+    const [taskResult] = await Promise.all([
+      task.run(taskArguments),
+      sendTaskAnalytics(task.id),
+    ]);
+
+    if (isResult(taskResult) && !taskResult.success) {
+      process.exitCode = 1;
+    }
+
+    if (!isCi() && process.stdout.isTTY === true) {
+      try {
+        const { BannerManager } = await import("./banner-manager.js");
+        const bannerManager = await BannerManager.getInstance();
+        await bannerManager.showBanner(200);
+      } catch (bannerError) {
+        log("Error showing banner", bannerError);
+      }
+    }
   } catch (error) {
     ensureError(error);
     printErrorMessages(error, builtinGlobalOptions?.showStackTraces);

package/src/internal/cli/telemetry/analytics/subprocess.ts

@@ -5,7 +5,9 @@ import { postJsonRequest } from "@nomicfoundation/hardhat-utils/request";
 
 // These keys are expected to be public
 const ANALYTICS_URL = "https://www.google-analytics.com/mp/collect";
+/* cspell:disable-next-line */
 // const API_SECRET = "iXzTRik5RhahYpgiatSv1w"; // DEV
+/* cspell:disable-next-line */
 // const MEASUREMENT_ID = "G-ZFZWHGZ64H"; // DEV
 const API_SECRET = "fQ5joCsDRTOp55wX8a2cVw"; // PROD
 const MEASUREMENT_ID = "G-8LQ007N2QJ"; // PROD

package/src/internal/cli/telemetry/sentry/anonymize-paths.ts

@@ -107,7 +107,7 @@ function anonymizeSinglePath(path: string): string {
     return normalizedPath;
   }
 
-  // We first get the index of the first /node_modules to desambiguate some
+  // We first get the index of the first /node_modules to disambiguate some
   // special cases below
   const nodeModulesIndex = normalizedPath.indexOf("/node_modules");