Merge pull request #5938 from NomicFoundation/update-nodetest-template

Update the `node:test`+`viem` template

v-next/example-project/package.json

@@ -34,7 +34,7 @@
     "prettier": "3.2.5",
     "rimraf": "^5.0.5",
     "typescript": "~5.5.0",
-    "viem": "^2.21.37",
+    "viem": "^2.21.42",
     "forge-std": "foundry-rs/forge-std#v1.9.4"
   }
 }

v-next/hardhat-viem/package.json

@@ -60,14 +60,14 @@
     "tsx": "^4.11.0",
     "typescript": "~5.5.0",
     "typescript-eslint": "7.7.1",
-    "viem": "^2.21.37"
+    "viem": "^2.21.42"
   },
   "dependencies": {
     "@ignored/hardhat-vnext-errors": "workspace:^3.0.0-next.14",
     "@ignored/hardhat-vnext-utils": "workspace:^3.0.0-next.14"
   },
   "peerDependencies": {
     "@ignored/hardhat-vnext": "workspace:^3.0.0-next.15",
-    "viem": "^2.21.37"
+    "viem": "^2.21.42"
   }
 }

v-next/hardhat/templates/node-test-runner-viem/README.md

@@ -1,62 +1,76 @@
-# A TypeScript Hardhat project using Node Test Runner and Viem
+# Hardhat 3 Alpha: `node:test` and `viem` example project
 
-> WARNING: This demonstration project is still in development. It is part of the Hardhat v3 upgrade. It is not for production use.
+> **WARNING**: This demonstration project is still in development. It is part of the Hardhat 3 upgrade and is not intended for production use.
 
-> NOTE: There are several plugins from the Hardhat toolbox that have not been ported to Hardhat v3 yet.
+Welcome to the Hardhat 3 alpha testing effort! This project showcases some of the changes and new features coming in Hardhat 3.
 
-This project demonstrates basic Hardhat usecases within a TypeScript project. It comes with:
+To learn more about the Hardhat 3 alpha, please visit the [Hardhat 3 alpha: Docs Hub](https://www.notion.so/nomicfoundation/Hardhat-3-alpha-Docs-Hub-131578cdeaf580e89e8dca57b0d036c3).
 
-- a minimal Hardhat configuration file
-- JS/TS integration tests
-- Solidity Tests
-- A script demonstrating how to deploy a contract to an in-memory Hardhat node simulating Base (an Optimism l2 chain)
+## Project Overview
 
-## Usage
+This example project includes:
+
+- A simple Hardhat configuration file
+- TypeScript integration tests using [`node:test`](nodejs.org/api/test.html), the new Node.js native test runner, and `viem`
+- Foundry-compatible Solidity tests, including the usage of `forge-std`
+- Examples demonstrating how to connect to different types of networks, including simulating an Optimism network
+- A script that sends a transaction to Optimism Sepolia using Hardhat's new keystore capabilities
+
+## Navigating the Project
+
+To get the most out of this example project, we recommend exploring the files in the following order:
 
-### Testing
+1. Read the `hardhat.config.ts` file, which contains the project configuration and explains multiple changes.
+2. Review the "Running Tests" section and explore the files in the `contracts/` and `test/` directories.
+3. Read the "Sending a Transaction to Optimism Sepolia" section, follow the instructions, and examine the `scripts/send-op-tx.ts` file.
 
-For integration testing it uses the Node Test Runner and the Viem library for interacting with Ethereum nodes.
+Each file includes inline explanations of its purpose and highlights the changes and new features introduced in Hardhat 3.
 
-Try running the following commands to see Hardhat's testing in action:
+## Usage
+
+### Running Tests
+
+To run all the tests in the project, execute the following command:
 
 ```shell
-# Run the both the Node Test Runner integration test suite
-# and the Solidity Test suite
 npx hardhat3 test
 ```
 
-### Multi-chain support
-
-Hardhat network now supports simulating Optimism L2 chains. You can see an example of a local Hardhat network configured to run as an Optimism L2 in the `./hardhat.config.ts` file for the `edrOp` network:
+You can also selectively run the Solidity or `node:test` tests:
 
-```js
-edrOp: {
-  type: "edr",
-  chainId: 10,
-  chainType: "optimism",
-  forkConfig: {
-    jsonRpcUrl: "https://mainnet.optimism.io",
-  },
-},
+```shell
+npx hardhat3 test solidity
+npx hardhat3 test node
 ```
 
-A script demonstrating the sending of an L2 transaction is included as `./scripts/send-op-tx.ts`, to run it against the local `edrOp` Optimism network, run:
+### Sending a Transaction to Optimism Sepolia
+
+This project includes an example script that sends a simple transaction to Optimism Sepolia. You can run the script using either the actual Optimism Sepolia network or a simulated version that behaves exactly like the real network.
+
+To run the script with EDR in Optimism mode:
 
 ```shell
-npx hardhat3 run scripts/send-op-tx.ts --network edrOp
+npx hardhat3 run scripts/send-op-tx.ts --network edrOpSepolia
 ```
 
-To run the same script against the Optimism mainnet, first set the `OPTIMISM_PRIVATE_KEY` config variable, with the private key of the account you want to use to send the transaction:
+To run the script with Optimism Sepolia, you need an account with funds to send the transaction. The provided Hardhat configuration includes a Configuration Variable called `OPTIMISM_SEPOLIA_PRIVATE_KEY`, which you can use to set the private key of the account you want to use.
+
+You can set the `OPTIMISM_SEPOLIA_PRIVATE_KEY` variable using the `hardhat-keystore` plugin or by setting it as an environment variable.
 
-> WARNING: the private key is stored unencrypted to file. Full encryption will be included in a future release.
+> **WARNING**: The private key is currently stored unencrypted. Full encryption will be included before the beta release.
+
+To set the `OPTIMISM_SEPOLIA_PRIVATE_KEY` config variable using `hardhat-keystore`:
 
 ```shell
-npx hardhat3 keystore set OPTIMISM_PRIVATE_KEY
-# Enter secret to store: ****************************************************************
+npx hardhat3 keystore set OPTIMISM_SEPOLIA_PRIVATE_KEY
 ```
 
-Run the script with the Optimism mainnet network:
+After setting the variable, you can run the script with the Optimism Sepolia network:
 
 ```shell
-npx hardhat3 run scripts/send-op-tx.ts --network op
+npx hardhat3 run scripts/send-op-tx.ts --network opSepolia
 ```
+
+---
+
+Feel free to explore the project and provide feedback on your experience with Hardhat 3 alpha!

v-next/hardhat/templates/node-test-runner-viem/contracts/Counter.sol

@@ -1,6 +1,9 @@
 // SPDX-License-Identifier: UNLICENSED
 pragma solidity ^0.8.24;
 
+// This is a simple smart contract used to demonstrate
+// a Solidity test in `Counter.t.sol`.
+
 contract Counter {
   uint public x;
 

v-next/hardhat/templates/node-test-runner-viem/contracts/Counter.t.sol

@@ -3,18 +3,21 @@ pragma solidity ^0.8.24;
 
 import "./Counter.sol";
 
+// Solidity tests are compatible with foundry, so they
+// use the same syntax and offer the same functionality.
+
 contract CounterTest {
   Counter counter;
 
   function setUp() public {
     counter = new Counter();
   }
 
-  function testInitialValue() public view {
+  function test_InitialValue() public view {
     require(counter.x() == 0, "Initial value should be 0");
   }
 
-  function testFuzzInc(uint8 x) public {
+  function testFuzz_Inc(uint8 x) public {
     for (uint8 i = 0; i < x; i++) {
       counter.inc();
     }

v-next/hardhat/templates/node-test-runner-viem/contracts/Lock.sol

@@ -1,6 +1,10 @@
 // SPDX-License-Identifier: UNLICENSED
 pragma solidity ^0.8.24;
 
+// This is the same example of Hardhat 2. We use it here to
+// demostrate the TypeScript test cabapbilities and compatibility
+// with Hardhat 2.
+
 // Uncomment this line to use console.log
 // import "hardhat/console.sol";
 

v-next/hardhat/templates/node-test-runner-viem/contracts/TestWithForgeStd.t.sol

@@ -4,20 +4,20 @@ pragma solidity ^0.8.24;
 import "forge-std/Test.sol";
 
 contract TestContract is Test {
-  ErrorsTest test;
+  BrokenContract test;
 
   function setUp() public {
-    test = new ErrorsTest();
+    test = new BrokenContract();
   }
 
-  function testExpectArithmetic() public {
+  function test_ExpectArithmeticError() public {
     vm.expectRevert(stdError.arithmeticError);
-    test.arithmeticError(10);
+    test.forceArithmeticError(10);
   }
 }
 
-contract ErrorsTest {
-  function arithmeticError(uint256 a) public pure returns (uint256) {
+contract BrokenContract {
+  function forceArithmeticError(uint256 a) public pure returns (uint256) {
     return a - 100;
   }
 }

v-next/hardhat/templates/node-test-runner-viem/hardhat.config.ts

@@ -1,6 +1,6 @@
 import {
   configVariable,
-  type HardhatUserConfig,
+  HardhatUserConfig,
 } from "@ignored/hardhat-vnext/config";
 
 import HardhatNodeTestRunner from "@ignored/hardhat-vnext-node-test-runner";
@@ -9,33 +9,101 @@ import HardhatNetworkHelpers from "@ignored/hardhat-vnext-network-helpers";
 import HardhatKeystore from "@ignored/hardhat-vnext-keystore";
 
 const config: HardhatUserConfig = {
+  /*
+   * In Hardhat 3, plugins are defined as part of the Hardhat config instead of
+   * being based on the side-effect of imports.
+   *
+   * Note: A `hardhat-toolbox` like plugin for Hardhat 3 hasn't been defined yet,
+   * so this list is larger than what you would normally have.
+   */
   plugins: [
     HardhatNodeTestRunner,
     HardhatViem,
     HardhatNetworkHelpers,
     HardhatKeystore,
   ],
   solidity: {
-    version: "0.8.24",
+    /*
+     * Hardhat 3 supports different build profiles, allowing you to configure
+     * different versions of `solc` and its settings for various use cases.
+     *
+     * Note: Using profiles is optional, and any Hardhat 2 `solidity` config
+     * is still valid in Hardhat 3.
+     */
+    profiles: {
+      /*
+       * The default profile is used when no profile is defined or specified
+       * in the CLI or by the tasks you are running.
+       */
+      default: {
+        version: "0.8.24",
+      },
+      /*
+       * The production profile is meant to be used for deployments, providing
+       * more control over settings for production builds and taking some extra
+       * steps to simplify the process of verifying your contracts.
+       */
+      production: {
+        version: "0.8.24",
+        settings: {
+          optimizer: {
+            enabled: true,
+            runs: 200,
+          },
+        },
+      },
+    },
+    /*
+     * Hardhat 3 natively supports remappings and makes extensive use of them
+     * internally to fully support npm resolution rules (i.e., it supports
+     * transitive dependencies, multiple versions of the same package,
+     * monorepos, etc.).
+     */
     remappings: [
-      // This is necessary because most people import forge-std/Test.sol, and not forge-std/src/Test.sol.
-      // This will improve in the future to remove the need for a named version.
+      /*
+       * This remapping is added to the example because most people import
+       * forge-std/Test.sol, not forge-std/src/Test.sol.
+       *
+       * Note: The config currently leaks internal IDs, but this will be fixed
+       * in the future.
+       */
       "forge-std/=npm/[email protected]/src/",
     ],
   },
+  /*
+   * The `networks` configuration is mostly compatible with Hardhat 2.
+   * The key differences right now are:
+   *
+   * - You must set a `type` for each network, which is either `http` or `edr`,
+   *   allowing you to have multiple simulated networks.
+   *
+   * - You can set a `chainType` for each network, which is either `generic`,
+   *   `l1`, or `optimism`. This has two uses. It ensures that you always
+   *   connect to the network with the right Chain Type. And, on `edr`
+   *   networks, it makes sure that the simulated chain behaves exactly like the
+   *   real one. More information about this can be found in the test files.
+   *
+   * - Some config fields, like `forkConfig`, are different from Hardhat 2 and
+   *   will be fixed in the near future.
+   *
+   * - The `accounts` field of `http` networks can also receive Configuration
+   *   Variables, which are values that only get loaded when needed. This allows
+   *   Hardhat to still run despite some of its config not being available
+   *   (e.g., a missing private key or API key). More info about this can be
+   *   found in the "Sending a Transaction to Optimism Sepolia" of the README.
+   */
   networks: {
-    op: {
+    opSepolia: {
       type: "http",
       chainType: "optimism",
-      url: "https://mainnet.optimism.io/",
-      accounts: [configVariable("OPTIMISM_PRIVATE_KEY")],
+      url: "https://sepolia.optimism.io/",
+      accounts: [configVariable("OPTIMISM_SEPOLIA_PRIVATE_KEY")],
     },
-    edrOp: {
+    edrOpSepolia: {
       type: "edr",
-      chainId: 10,
       chainType: "optimism",
       forkConfig: {
-        jsonRpcUrl: "https://mainnet.optimism.io",
+        jsonRpcUrl: "https://sepolia.optimism.io",
       },
     },
   },

v-next/hardhat/templates/node-test-runner-viem/package.json

@@ -13,6 +13,6 @@
     "@types/node": "^22.8.5",
     "forge-std": "foundry-rs/forge-std#v1.9.4",
     "typescript": "~5.5.0",
-    "viem": "^2.21.37"
+    "viem": "^2.21.42"
   }
 }