NomicFoundation · fvictorio · Feb 23, 2022 · Feb 9, 2022 · Feb 9, 2022 · Feb 9, 2022
diff --git a/.changeset/hip-planes-invent.md b/.changeset/hip-planes-invent.md
@@ -0,0 +1,7 @@
+---
+"hardhat": minor
+---
+
+The `test` task now supports a `--parallel` flag to run tests in parallel. There are also two other new flags: `--bail`, to stop the execution after the first test failure, and `--grep`, to filter which tests should be run.
+
+To support running tests in parallel, the version of `mocha` used by Hardhat was upgraded to its latest version. This should be a mostly backward-compatible change, but there could be some edge cases where this breaks existing tests.
diff --git a/docs/guides/waffle-testing.md b/docs/guides/waffle-testing.md
@@ -125,6 +125,23 @@ expect(await greeter.greet()).to.equal("Hola, mundo!");
 
 We can modify the state of a contract in the same way we read from it. Calling `setGreeting` will set a new greeting message. After the `Promise` is resolved, we perform another assertion to verify that the greeting change took effect.
 
+### Running tests in parallel
+
+You can run your tests in parallel by using the `--parallel` flag:
+
+```
+$ npx hardhat test --parallel
+```
+
+Most of the time, running your tests serially or in parallel should produce the same results, but there are some scenarios where tests run in parallel will behave differently:
+
+- In serial mode, all the test files share the same instance of the [Hardhat Runtime Environment](/advanced/hardhat-runtime-environment.html), but in parallel mode each test file will have its own fresh instance. For example, if one test file deploys a contract, then that contract won't exist in the other test files.
+- The `.only` modifier doesn't work in parallel mode. You can use [`--grep`](https://mochajs.org/#-grep-regexp-g-regexp) to run specific tests.
+- The duration of individual tests might be different, because parallel mode uses more system resources. There's a chance that some tests start timing out for that reason. You can increase the tests timeout if you run into this problem.
+- The order in which tests are executed is non-deterministic.
+
+There are some other limitations related to parallel mode. You can read more about them in [Mocha's docs](https://mochajs.org/#parallel-tests). And if you are running into some issue when using parallel mode, you can check their [Troubleshooting parallel mode](https://mochajs.org/#troubleshooting-parallel-mode) section.
+
 ### Testing from a different account
 
 If you need to send a transaction from an account other than the default one, you can use the `connect()` method provided by Ethers.js.

diff --git a/packages/e2e/package.json b/packages/e2e/package.json
@@ -21,7 +21,7 @@
   "dependencies": {
     "@types/chai": "^4.2.0",
     "@types/fs-extra": "^5.1.0",
-    "@types/mocha": "^9.0.0",
+    "@types/mocha": "^9.1.0",
     "@types/node": "^12.0.0",
     "@types/shelljs": "^0.8.6",
     "@typescript-eslint/eslint-plugin": "4.29.2",
@@ -32,7 +32,7 @@
     "eslint-plugin-import": "2.24.1",
     "eslint-plugin-prettier": "3.4.0",
     "fs-extra": "^7.0.1",
-    "mocha": "^7.2.0",
+    "mocha": "^9.2.0",
     "prettier": "2.4.1",
     "rimraf": "^3.0.2",
     "shelljs": "^0.8.5",

diff --git a/packages/e2e/test/fixture-projects/basic-project/test/another-test.js b/packages/e2e/test/fixture-projects/basic-project/test/another-test.js
@@ -0,0 +1,3 @@
+describe("simple", () => {
+  it("should pass", () => {});
+});
diff --git a/packages/e2e/test/index.ts b/packages/e2e/test/index.ts
@@ -54,7 +54,7 @@ describe("e2e tests", function () {
       // check stdout
 
       // check we get passing runs
-      assert.match(stdout, /1 passing/);
+      assert.match(stdout, /2 passing/);
       // check we get no runs without tests
       assert.notMatch(
         stdout,
@@ -66,6 +66,25 @@ describe("e2e tests", function () {
       const { code: hhCleanCode2 } = shell.exec(`${hardhatBinary} clean`);
       assert.equal(hhCleanCode2, 0);
     });
+
+    it("should run tests in parallel", function () {
+      // hh clean
+      const { code: hhCleanCode1 } = shell.exec(`${hardhatBinary} clean`);
+      assert.equal(hhCleanCode1, 0);
+
+      // hh test --parallel
+      const { code: hhCompileCode, stdout } = shell.exec(
+        `${hardhatBinary} test --parallel`
+      );
+      assert.equal(hhCompileCode, 0);
+
+      // check we get passing runs
+      assert.match(stdout, /2 passing/);
+
+      // hh clean
+      const { code: hhCleanCode2 } = shell.exec(`${hardhatBinary} clean`);
+      assert.equal(hhCleanCode2, 0);
+    });
   });
 
   describe("sample projects", function () {

diff --git a/packages/hardhat-core/package.json b/packages/hardhat-core/package.json
@@ -63,7 +63,7 @@
     "@types/fs-extra": "^5.1.0",
     "@types/glob": "^7.1.1",
     "@types/lodash": "^4.14.123",
-    "@types/mocha": "^9.0.0",
+    "@types/mocha": "^9.1.0",
     "@types/node": "^12.0.0",
     "@types/node-fetch": "^2.3.7",
     "@types/qs": "^6.5.3",
@@ -81,7 +81,7 @@
     "eslint-plugin-import": "2.24.1",
     "eslint-plugin-prettier": "3.4.0",
     "ethers": "^5.0.0",
-    "mocha": "^7.2.0",
+    "mocha": "^9.2.0",
     "prettier": "2.4.1",
     "proxy": "^1.0.2",
     "rimraf": "^3.0.2",
@@ -124,7 +124,7 @@
     "lodash": "^4.17.11",
     "merkle-patricia-tree": "^4.2.2",
     "mnemonist": "^0.38.0",
-    "mocha": "^7.2.0",
+    "mocha": "^9.2.0",
     "node-fetch": "^2.6.0",
     "qs": "^6.7.0",
     "raw-body": "^2.4.1",

diff --git a/packages/hardhat-core/src/builtin-tasks/test.ts b/packages/hardhat-core/src/builtin-tasks/test.ts
@@ -1,4 +1,5 @@
 import chalk from "chalk";
+import type { MochaOptions } from "mocha";
 import path from "path";
 
 import { HARDHAT_NETWORK_NAME } from "../internal/constants";
@@ -43,24 +44,59 @@ subtask(TASK_TEST_GET_TEST_FILES)
 subtask(TASK_TEST_SETUP_TEST_ENVIRONMENT, async () => {});
 
 subtask(TASK_TEST_RUN_MOCHA_TESTS)
+  .addFlag("parallel", "Run tests in parallel")
+  .addFlag("bail", "Stop running tests after the first test failure")
+  .addOptionalParam("grep", "Only run tests matching the given regexp")
   .addOptionalVariadicPositionalParam(
     "testFiles",
     "An optional list of files to test",
     []
   )
-  .setAction(async ({ testFiles }: { testFiles: string[] }, { config }) => {
-    const { default: Mocha } = await import("mocha");
-    const mocha = new Mocha(config.mocha);
-    testFiles.forEach((file) => mocha.addFile(file));
+  .setAction(
+    async (
+      {
+        bail,
+        parallel,
+        testFiles,
+        grep,
+      }: {
+        bail: boolean;
+        parallel: boolean;
+        testFiles: string[];
+        grep?: string;
+      },
+      { config }
+    ) => {
+      const { default: Mocha } = await import("mocha");
 
-    const testFailures = await new Promise<number>((resolve) => {
-      mocha.run(resolve);
-    });
+      const mochaConfig: MochaOptions = {
+        ...config.mocha,
+        bail,
+        grep,
+      };
 
-    mocha.dispose();
+      if (parallel) {
+        mochaConfig.parallel = true;
 
-    return testFailures;
-  });
+        const mochaRequire = mochaConfig.require ?? [];
+        if (!mochaRequire.includes("hardhat/register")) {
+          mochaRequire.push("hardhat/register");
+        }
+        mochaConfig.require = mochaRequire;
+      }
+
+      const mocha = new Mocha(mochaConfig);
+      testFiles.forEach((file) => mocha.addFile(file));
+
+      const testFailures = await new Promise<number>((resolve) => {
+        mocha.run(resolve);
+      });
+
+      mocha.dispose();
+
+      return testFailures;
+    }
+  );
 
 subtask(TASK_TEST_RUN_SHOW_FORK_RECOMMENDATIONS).setAction(
   async (_, { config, network }) => {
@@ -80,14 +116,23 @@ task(TASK_TEST, "Runs mocha tests")
     []
   )
   .addFlag("noCompile", "Don't compile before running this task")
+  .addFlag("parallel", "Run tests in parallel")
+  .addFlag("bail", "Stop running tests after the first test failure")
+  .addOptionalParam("grep", "Only run tests matching the given regexp")
   .setAction(
     async (
       {
         testFiles,
         noCompile,
+        parallel,
+        bail,
+        grep,
       }: {
         testFiles: string[];
         noCompile: boolean;
+        parallel: boolean;
+        bail: boolean;
+        grep?: string;
       },
       { run, network }
     ) => {
@@ -103,6 +148,9 @@ task(TASK_TEST, "Runs mocha tests")
 
       const testFailures = await run(TASK_TEST_RUN_MOCHA_TESTS, {
         testFiles: files,
+        parallel,
+        bail,
+        grep,
       });
 
       if (network.name === HARDHAT_NETWORK_NAME) {

diff --git a/packages/hardhat-core/test/internal/cli/autocomplete.ts b/packages/hardhat-core/test/internal/cli/autocomplete.ts
@@ -244,6 +244,18 @@ describe("autocomplete", function () {
           description: "Don't compile before running this task",
           name: "--no-compile",
         },
+        {
+          description: "Run tests in parallel",
+          name: "--parallel",
+        },
+        {
+          description: "Stop running tests after the first test failure",
+          name: "--bail",
+        },
+        {
+          description: "Only run tests matching the given regexp",
+          name: "--grep",
+        },
       ]);
     });
 

diff --git a/packages/hardhat-docker/package.json b/packages/hardhat-docker/package.json
@@ -31,26 +31,26 @@
     "@types/chai": "^4.2.0",
     "@types/dockerode": "^2.5.19",
     "@types/fs-extra": "^5.1.0",
-    "@types/mocha": "^9.0.0",
-    "@types/node-fetch": "^2.3.7",
+    "@types/mocha": "^9.1.0",
     "@types/node": "^12.0.0",
+    "@types/node-fetch": "^2.3.7",
     "@typescript-eslint/eslint-plugin": "4.29.2",
     "@typescript-eslint/parser": "4.29.2",
     "chai": "^4.2.0",
     "eslint": "^7.29.0",
     "eslint-config-prettier": "8.3.0",
     "eslint-plugin-import": "2.24.1",
     "eslint-plugin-prettier": "3.4.0",
-    "mocha": "^7.2.0",
+    "mocha": "^9.2.0",
     "prettier": "2.4.1",
     "rimraf": "^3.0.2",
     "ts-node": "^8.1.0",
     "typescript": "~4.5.2"
   },
   "peerDependencies": {},
   "dependencies": {
-    "fs-extra": "^7.0.1",
     "dockerode": "^2.5.8",
+    "fs-extra": "^7.0.1",
     "node-fetch": "^2.6.0"
   }
 }
diff --git a/packages/hardhat-ethers/package.json b/packages/hardhat-ethers/package.json
@@ -38,7 +38,7 @@
   ],
   "devDependencies": {
     "@types/chai": "^4.2.0",
-    "@types/mocha": "^9.0.0",
+    "@types/mocha": "^9.1.0",
     "@types/node": "^12.0.0",
     "@typescript-eslint/eslint-plugin": "4.29.2",
     "@typescript-eslint/parser": "4.29.2",
@@ -49,7 +49,7 @@
     "eslint-plugin-prettier": "3.4.0",
     "ethers": "^5.0.0",
     "hardhat": "^2.0.0",
-    "mocha": "^7.2.0",
+    "mocha": "^9.2.0",
     "prettier": "2.4.1",
     "rimraf": "^3.0.2",
     "ts-node": "^8.1.0",

diff --git a/packages/hardhat-etherscan/package.json b/packages/hardhat-etherscan/package.json
@@ -48,9 +48,9 @@
     "@types/cbor": "^5.0.1",
     "@types/chai": "^4.2.0",
     "@types/fs-extra": "^5.1.0",
-    "@types/mocha": "^9.0.0",
-    "@types/node-fetch": "^2.3.7",
+    "@types/mocha": "^9.1.0",
     "@types/node": "^12.0.0",
+    "@types/node-fetch": "^2.3.7",
     "@types/semver": "^6.0.2",
     "@typescript-eslint/eslint-plugin": "4.29.2",
     "@typescript-eslint/parser": "4.29.2",
@@ -61,7 +61,7 @@
     "eslint-plugin-prettier": "3.4.0",
     "ethers": "^5.0.8",
     "hardhat": "^2.0.4",
-    "mocha": "^7.2.0",
+    "mocha": "^9.2.0",
     "nock": "^13.0.5",
     "prettier": "2.4.1",
     "rimraf": "^3.0.2",

diff --git a/packages/hardhat-ganache/package.json b/packages/hardhat-ganache/package.json
@@ -40,7 +40,7 @@
     "@types/chai": "^4.2.0",
     "@types/debug": "^4.1.4",
     "@types/fs-extra": "^5.1.0",
-    "@types/mocha": "^9.0.0",
+    "@types/mocha": "^9.1.0",
     "@types/node": "^12.0.0",
     "@typescript-eslint/eslint-plugin": "4.29.2",
     "@typescript-eslint/parser": "4.29.2",
@@ -50,7 +50,7 @@
     "eslint-plugin-import": "2.24.1",
     "eslint-plugin-prettier": "3.4.0",
     "hardhat": "^2.0.0",
-    "mocha": "^7.2.0",
+    "mocha": "^9.2.0",
     "prettier": "2.4.1",
     "rimraf": "^3.0.2",
     "ts-interface-builder": "^0.2.0",

diff --git a/packages/hardhat-shorthand/package.json b/packages/hardhat-shorthand/package.json
@@ -34,7 +34,7 @@
   "devDependencies": {
     "@types/chai": "^4.2.0",
     "@types/fs-extra": "^5.1.0",
-    "@types/mocha": "^9.0.0",
+    "@types/mocha": "^9.1.0",
     "@types/node": "^12.0.0",
     "@typescript-eslint/eslint-plugin": "4.29.2",
     "@typescript-eslint/parser": "4.29.2",
@@ -44,7 +44,7 @@
     "eslint-plugin-import": "2.24.1",
     "eslint-plugin-prettier": "3.4.0",
     "hardhat": "^2.0.0",
-    "mocha": "^7.2.0",
+    "mocha": "^9.2.0",
     "prettier": "2.4.1",
     "rimraf": "^3.0.2",
     "ts-node": "^8.1.0",

diff --git a/packages/hardhat-solhint/package.json b/packages/hardhat-solhint/package.json
@@ -38,7 +38,7 @@
   "devDependencies": {
     "@types/chai": "^4.2.0",
     "@types/fs-extra": "^5.1.0",
-    "@types/mocha": "^9.0.0",
+    "@types/mocha": "^9.1.0",
     "@types/node": "^12.0.0",
     "@typescript-eslint/eslint-plugin": "4.29.2",
     "@typescript-eslint/parser": "4.29.2",
@@ -49,7 +49,7 @@
     "eslint-plugin-prettier": "3.4.0",
     "fs-extra": "^7.0.1",
     "hardhat": "^2.0.0",
-    "mocha": "^7.2.0",
+    "mocha": "^9.2.0",
     "prettier": "2.4.1",
     "rimraf": "^3.0.2",
     "ts-node": "^8.1.0",

diff --git a/packages/hardhat-solpp/package.json b/packages/hardhat-solpp/package.json
@@ -39,7 +39,7 @@
   "devDependencies": {
     "@types/chai": "^4.2.0",
     "@types/fs-extra": "^5.1.0",
-    "@types/mocha": "^9.0.0",
+    "@types/mocha": "^9.1.0",
     "@types/node": "^12.0.0",
     "@typescript-eslint/eslint-plugin": "4.29.2",
     "@typescript-eslint/parser": "4.29.2",
@@ -49,7 +49,7 @@
     "eslint-plugin-import": "2.24.1",
     "eslint-plugin-prettier": "3.4.0",
     "hardhat": "^2.0.0",
-    "mocha": "^7.2.0",
+    "mocha": "^9.2.0",
     "prettier": "2.4.1",
     "rimraf": "^3.0.2",
     "ts-node": "^8.1.0",