@nomicfoundation/hardhat-ethers-chai-matchers 3.0.0-next.0

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@nomicfoundation/hardhat-ethers-chai-matchers",
+  "version": "3.0.0-next.0",
+  "description": "Hardhat utils for testing",
+  "homepage": "https://github.com/nomicfoundation/hardhat/tree/v-next/v-next/hardhat-ethers-chai-matchers",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NomicFoundation/hardhat",
+    "directory": "v-next/hardhat-ethers-chai-matchers"
+  },
+  "author": "Nomic Foundation",
+  "license": "MIT",
+  "type": "module",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./panic": "./dist/src/panic.js",
+    "./withArgs": "./dist/src/withArgs.js"
+  },
+  "keywords": [
+    "ethereum",
+    "smart-contracts",
+    "hardhat",
+    "testing"
+  ],
+  "files": [
+    "dist/src/",
+    "src/",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@eslint-community/eslint-plugin-eslint-comments": "^4.3.0",
+    "@nomicfoundation/hardhat-mocha": "^3.0.0-next.0",
+    "@nomicfoundation/hardhat-node-test-reporter": "^3.0.0-next.0",
+    "@types/chai": "^4.2.0",
+    "@types/debug": "^4.1.7",
+    "@types/deep-eql": "^4.0.2",
+    "@types/mocha": ">=9.1.0",
+    "@types/node": "^20.14.9",
+    "@typescript-eslint/eslint-plugin": "^7.7.1",
+    "@typescript-eslint/parser": "^7.7.1",
+    "c8": "^9.1.0",
+    "eslint": "8.57.0",
+    "eslint-config-prettier": "9.1.0",
+    "eslint-import-resolver-typescript": "^3.6.1",
+    "eslint-plugin-import": "2.29.1",
+    "eslint-plugin-no-only-tests": "3.1.0",
+    "expect-type": "^0.19.0",
+    "mocha": "^10.0.0",
+    "prettier": "3.2.5",
+    "rimraf": "^5.0.5",
+    "tsx": "^4.19.3",
+    "typescript": "~5.5.0",
+    "typescript-eslint": "7.7.1",
+    "@nomicfoundation/hardhat-test-utils": "^3.0.0-next.0"
+  },
+  "dependencies": {
+    "@nomicfoundation/hardhat-errors": "^3.0.0-next.0",
+    "@nomicfoundation/hardhat-utils": "^3.0.0-next.0",
+    "@types/chai-as-promised": "^8.0.1",
+    "chai-as-promised": "^8.0.0",
+    "deep-eql": "^5.0.1"
+  },
+  "peerDependencies": {
+    "hardhat": "^3.0.0-next.0",
+    "@nomicfoundation/hardhat-ethers": "^4.0.0-next.0",
+    "chai": "^5.1.2",
+    "ethers": "^6.13.4"
+  },
+  "scripts": {
+    "lint": "pnpm prettier --check && pnpm eslint",
+    "lint:fix": "pnpm prettier --write && pnpm eslint --fix",
+    "eslint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
+    "prettier": "prettier \"**/*.{ts,js,md,json}\"",
+    "test": "node --import tsx/esm --test --test-reporter=@nomicfoundation/hardhat-node-test-reporter \"test/*.ts\" \"test/!(fixture-projects|helpers)/**/*.ts\"",
+    "test:only": "node --import tsx/esm --test --test-only --test-reporter=@nomicfoundation/hardhat-node-test-reporter \"test/*.ts\" \"test/!(fixture-projects|helpers)/**/*.ts\"",
+    "test:coverage": "c8 --reporter html --reporter text --all --exclude test --exclude src/internal/types.ts --exclude src/internal/ui/direct-user-interruption-manager.ts --src src node --import tsx/esm --test --test-reporter=@nomicfoundation/hardhat-node-test-reporter \"test/!(fixture-projects|helpers)/**/*.ts\"",
+    "pretest": "pnpm build && node --import tsx/esm ./test/helpers/pretest.ts",
+    "pretest:only": "pnpm build",
+    "build": "tsc --build .",
+    "clean": "rimraf dist"
+  }
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+import type { HardhatPlugin } from "hardhat/types/plugins";
+
+import "./type-extensions.js";
+
+const hardhatChaiMatchersPlugin: HardhatPlugin = {
+  id: "hardhat-ethers-chai-matchers",
+  hookHandlers: {
+    network: import.meta.resolve("./internal/hook-handlers/network.js"),
+  },
+  npmPackage: "@nomicfoundation/hardhat-ethers-chai-matchers",
+  dependencies: [
+    async () => {
+      const { default: hardhatEthersPlugin } = await import(
+        "@nomicfoundation/hardhat-ethers"
+      );
+      return hardhatEthersPlugin;
+    },
+  ],
+};
+
+export default hardhatChaiMatchersPlugin;

package/src/internal/add-chai-matchers.ts

@@ -0,0 +1,46 @@
+import { use } from "chai";
+import chaiAsPromised from "chai-as-promised";
+
+import { supportAddressable } from "./matchers/addressable.js";
+import { supportBigNumber } from "./matchers/big-number.js";
+import { supportChangeEtherBalance } from "./matchers/changeEtherBalance.js";
+import { supportChangeEtherBalances } from "./matchers/changeEtherBalances.js";
+import { supportChangeTokenBalance } from "./matchers/changeTokenBalance.js";
+import { supportEmit } from "./matchers/emit.js";
+import { supportHexEqual } from "./matchers/hexEqual.js";
+import { supportProperAddress } from "./matchers/properAddress.js";
+import { supportProperHex } from "./matchers/properHex.js";
+import { supportProperPrivateKey } from "./matchers/properPrivateKey.js";
+import { supportReverted } from "./matchers/reverted/reverted.js";
+import { supportRevertedWith } from "./matchers/reverted/revertedWith.js";
+import { supportRevertedWithCustomError } from "./matchers/reverted/revertedWithCustomError.js";
+import { supportRevertedWithPanic } from "./matchers/reverted/revertedWithPanic.js";
+import { supportRevertedWithoutReason } from "./matchers/reverted/revertedWithoutReason.js";
+import { supportWithArgs } from "./matchers/withArgs.js";
+
+export function addChaiMatchers(): void {
+  use(hardhatChaiMatchers);
+  use(chaiAsPromised);
+}
+
+function hardhatChaiMatchers(
+  chai: Chai.ChaiStatic,
+  chaiUtils: Chai.ChaiUtils,
+): void {
+  supportAddressable(chai.Assertion, chaiUtils);
+  supportBigNumber(chai.Assertion, chaiUtils);
+  supportEmit(chai.Assertion, chaiUtils);
+  supportHexEqual(chai.Assertion);
+  supportProperAddress(chai.Assertion);
+  supportProperHex(chai.Assertion);
+  supportProperPrivateKey(chai.Assertion);
+  supportChangeEtherBalance(chai.Assertion, chaiUtils);
+  supportChangeEtherBalances(chai.Assertion, chaiUtils);
+  supportChangeTokenBalance(chai.Assertion, chaiUtils);
+  supportReverted(chai.Assertion, chaiUtils);
+  supportRevertedWith(chai.Assertion, chaiUtils);
+  supportRevertedWithCustomError(chai.Assertion, chaiUtils);
+  supportRevertedWithPanic(chai.Assertion, chaiUtils);
+  supportRevertedWithoutReason(chai.Assertion, chaiUtils);
+  supportWithArgs(chai.Assertion, chaiUtils);
+}

package/src/internal/constants.ts

@@ -0,0 +1,13 @@
+export const ASSERTION_ABORTED = "hh-ethers-chai-matchers-assertion-aborted";
+export const PREVIOUS_MATCHER_NAME = "previousMatcherName";
+
+export const CHANGE_ETHER_BALANCE_MATCHER = "changeEtherBalance";
+export const CHANGE_ETHER_BALANCES_MATCHER = "changeEtherBalances";
+export const CHANGE_TOKEN_BALANCE_MATCHER = "changeTokenBalance";
+export const CHANGE_TOKEN_BALANCES_MATCHER = "changeTokenBalances";
+export const EMIT_MATCHER = "emit";
+export const REVERTED_MATCHER = "reverted";
+export const REVERTED_WITH_MATCHER = "revertedWith";
+export const REVERTED_WITH_CUSTOM_ERROR_MATCHER = "revertedWithCustomError";
+export const REVERTED_WITH_PANIC_MATCHER = "revertedWithPanic";
+export const REVERTED_WITHOUT_REASON_MATCHER = "revertedWithoutReason";

package/src/internal/hook-handlers/network.ts

@@ -0,0 +1,24 @@
+import type { HookContext, NetworkHooks } from "hardhat/types/hooks";
+import type { ChainType, NetworkConnection } from "hardhat/types/network";
+
+import { addChaiMatchers } from "../add-chai-matchers.js";
+
+let isInitialized = false;
+
+export default async (): Promise<Partial<NetworkHooks>> => {
+  const handlers: Partial<NetworkHooks> = {
+    async newConnection<ChainTypeT extends ChainType | string>(
+      context: HookContext,
+      next: (context: HookContext) => Promise<NetworkConnection<ChainTypeT>>,
+    ) {
+      if (!isInitialized) {
+        addChaiMatchers();
+        isInitialized = true;
+      }
+
+      return next(context);
+    },
+  };
+
+  return handlers;
+};

package/src/internal/matchers/addressable.ts

@@ -0,0 +1,86 @@
+import { assertHardhatInvariant } from "@nomicfoundation/hardhat-errors";
+import { isAddress, isAddressable } from "ethers";
+
+import { tryDereference } from "../utils/typed.js";
+
+export function supportAddressable(
+  Assertion: Chai.AssertionStatic,
+  chaiUtils: Chai.ChaiUtils,
+): void {
+  const equalsFunction = override("eq", "equal", "not equal", chaiUtils);
+  Assertion.overwriteMethod("equals", equalsFunction);
+  Assertion.overwriteMethod("equal", equalsFunction);
+  Assertion.overwriteMethod("eq", equalsFunction);
+}
+
+type Methods = "eq";
+
+function override(
+  method: Methods,
+  name: string,
+  negativeName: string,
+  chaiUtils: Chai.ChaiUtils,
+) {
+  return (_super: (...args: any[]) => any) =>
+    overwriteAddressableFunction(method, name, negativeName, _super, chaiUtils);
+}
+
+// ethers's Addressable have a .getAddress() that returns a Promise<string>. We don't want to deal with async here,
+// so we are looking for a sync way of getting the address. If an address was recovered, it is returned as a string,
+// otherwise undefined is returned.
+function tryGetAddressSync(value: any): string | undefined {
+  value = tryDereference(value, "address");
+
+  if (isAddressable(value)) {
+    if ("address" in value) {
+      value = value.address;
+    } else {
+      assertHardhatInvariant(
+        "target" in value,
+        "target property should exist in value",
+      );
+      value = value.target;
+    }
+  }
+
+  if (isAddress(value)) {
+    return value;
+  } else {
+    return undefined;
+  }
+}
+
+function overwriteAddressableFunction(
+  functionName: Methods,
+  readableName: string,
+  readableNegativeName: string,
+  _super: (...args: any[]) => any,
+  chaiUtils: Chai.ChaiUtils,
+) {
+  return function (this: Chai.AssertionStatic, ...args: any[]) {
+    const [actualArg, message] = args;
+    const expectedFlag = chaiUtils.flag(this, "object");
+
+    if (message !== undefined) {
+      chaiUtils.flag(this, "message", message);
+    }
+
+    const actual = tryGetAddressSync(actualArg);
+    const expected = tryGetAddressSync(expectedFlag);
+    if (
+      functionName === "eq" &&
+      expected !== undefined &&
+      actual !== undefined
+    ) {
+      this.assert(
+        expected === actual,
+        `expected '${expected}' to ${readableName} '${actual}'.`,
+        `expected '${expected}' to ${readableNegativeName} '${actual}'.`,
+        actual.toString(),
+        expected.toString(),
+      );
+    } else {
+      _super.apply(this, args);
+    }
+  };
+}

package/src/internal/matchers/big-number.ts

@@ -0,0 +1,279 @@
+import util from "node:util";
+
+import { HardhatError } from "@nomicfoundation/hardhat-errors";
+import { toBigInt } from "@nomicfoundation/hardhat-utils/bigint";
+import { AssertionError } from "chai";
+import deepEqual from "deep-eql";
+
+import { isBigInt } from "../utils/bigint.js";
+
+export function supportBigNumber(
+  Assertion: Chai.AssertionStatic,
+  chaiUtils: Chai.ChaiUtils,
+): void {
+  const equalsFunction = override("eq", "equal", "not equal", chaiUtils);
+  Assertion.overwriteMethod("equals", equalsFunction);
+  Assertion.overwriteMethod("equal", equalsFunction);
+  Assertion.overwriteMethod("eq", equalsFunction);
+
+  const gtFunction = override("gt", "be above", "be at most", chaiUtils);
+  Assertion.overwriteMethod("above", gtFunction);
+  Assertion.overwriteMethod("gt", gtFunction);
+  Assertion.overwriteMethod("greaterThan", gtFunction);
+
+  const ltFunction = override("lt", "be below", "be at least", chaiUtils);
+  Assertion.overwriteMethod("below", ltFunction);
+  Assertion.overwriteMethod("lt", ltFunction);
+  Assertion.overwriteMethod("lessThan", ltFunction);
+
+  const gteFunction = override("gte", "be at least", "be below", chaiUtils);
+  Assertion.overwriteMethod("least", gteFunction);
+  Assertion.overwriteMethod("gte", gteFunction);
+  Assertion.overwriteMethod("greaterThanOrEqual", gteFunction);
+
+  const lteFunction = override("lte", "be at most", "be above", chaiUtils);
+  Assertion.overwriteMethod("most", lteFunction);
+  Assertion.overwriteMethod("lte", lteFunction);
+  Assertion.overwriteMethod("lessThanOrEqual", lteFunction);
+
+  Assertion.overwriteChainableMethod(...createLengthOverride("length"));
+  Assertion.overwriteChainableMethod(...createLengthOverride("lengthOf"));
+
+  Assertion.overwriteMethod("within", overrideWithin(chaiUtils));
+
+  Assertion.overwriteMethod("closeTo", overrideCloseTo(chaiUtils));
+  Assertion.overwriteMethod("approximately", overrideCloseTo(chaiUtils));
+}
+
+function createLengthOverride(
+  method: string,
+): [string, (...args: any[]) => any, (...args: any[]) => any] {
+  return [
+    method,
+    function (_super: any) {
+      return function (this: Chai.AssertionPrototype, value: any) {
+        const actual = this._obj;
+
+        if (isBigInt(value)) {
+          const sizeOrLength =
+            actual instanceof Map || actual instanceof Set ? "size" : "length";
+
+          const actualLength = toBigInt(actual[sizeOrLength]);
+          const expectedLength = toBigInt(value);
+
+          this.assert(
+            actualLength === expectedLength,
+            `expected #{this} to have a ${sizeOrLength} of ${expectedLength.toString()} but got ${actualLength.toString()}`,
+            `expected #{this} not to have a ${sizeOrLength} of ${expectedLength.toString()} but got ${actualLength.toString()}`,
+            actualLength.toString(),
+            expectedLength.toString(),
+          );
+        } else {
+          _super.apply(this, arguments);
+        }
+      };
+    },
+    function (_super: any) {
+      return function (this: any) {
+        _super.apply(this, arguments);
+      };
+    },
+  ];
+}
+
+type Methods = "eq" | "gt" | "lt" | "gte" | "lte";
+
+function override(
+  method: Methods,
+  name: string,
+  negativeName: string,
+  chaiUtils: Chai.ChaiUtils,
+) {
+  return (_super: (...args: any[]) => any) =>
+    overwriteBigNumberFunction(method, name, negativeName, _super, chaiUtils);
+}
+
+function overwriteBigNumberFunction(
+  functionName: Methods,
+  readableName: string,
+  readableNegativeName: string,
+  _super: (...args: any[]) => any,
+  chaiUtils: Chai.ChaiUtils,
+) {
+  return function (this: Chai.AssertionStatic, ...args: any[]) {
+    const [actualArg, message] = args;
+    const expectedFlag = chaiUtils.flag(this, "object");
+
+    if (message !== undefined) {
+      chaiUtils.flag(this, "message", message);
+    }
+
+    function compare(method: Methods, lhs: bigint, rhs: bigint): boolean {
+      if (method === "eq") {
+        return lhs === rhs;
+      } else if (method === "gt") {
+        return lhs > rhs;
+      } else if (method === "lt") {
+        return lhs < rhs;
+      } else if (method === "gte") {
+        return lhs >= rhs;
+      } else if (method === "lte") {
+        return lhs <= rhs;
+      } else {
+        throw new HardhatError(
+          HardhatError.ERRORS.CHAI_MATCHERS.UNKNOWN_COMPARISON_OPERATION,
+          {
+            method,
+          },
+        );
+      }
+    }
+
+    if (Boolean(chaiUtils.flag(this, "doLength")) && isBigInt(actualArg)) {
+      const sizeOrLength =
+        expectedFlag instanceof Map || expectedFlag instanceof Set
+          ? "size"
+          : "length";
+
+      if (expectedFlag[sizeOrLength] === undefined) {
+        _super.apply(this, args);
+        return;
+      }
+
+      const expected = toBigInt(expectedFlag[sizeOrLength]);
+      const actual = toBigInt(actualArg);
+
+      this.assert(
+        compare(functionName, expected, actual),
+        `expected #{this} to have a ${sizeOrLength} ${readableName.replace(
+          "be ",
+          "",
+        )} ${actual.toString()} but got ${expected}`,
+        `expected #{this} to have a ${sizeOrLength} ${readableNegativeName} ${actual.toString()}`,
+        expected,
+        actual,
+      );
+    } else if (functionName === "eq" && Boolean(chaiUtils.flag(this, "deep"))) {
+      // "ssfi" stands for "start stack function indicator", it's a chai concept
+      // used to control which frames are included in the stack trace
+      // this pattern here was taken from chai's implementation of .deep.equal
+      const prevLockSsfi = chaiUtils.flag(this, "lockSsfi");
+
+      chaiUtils.flag(this, "lockSsfi", true);
+
+      this.assert(
+        deepEqual(actualArg, expectedFlag, { comparator: deepEqualComparator }),
+        `expected ${util.inspect(expectedFlag)} to deeply equal ${util.inspect(
+          actualArg,
+        )}`,
+        `expected ${util.inspect(
+          expectedFlag,
+        )} to not deeply equal ${util.inspect(actualArg)}`,
+        null,
+      );
+
+      chaiUtils.flag(this, "lockSsfi", prevLockSsfi);
+    } else if (isBigInt(expectedFlag) || isBigInt(actualArg)) {
+      const expected = toBigInt(expectedFlag);
+      const actual = toBigInt(actualArg);
+
+      this.assert(
+        compare(functionName, expected, actual),
+        `expected ${expected} to ${readableName} ${actual}.`,
+        `expected ${expected} to ${readableNegativeName} ${actual}.`,
+        actual.toString(),
+        expected.toString(),
+      );
+    } else {
+      _super.apply(this, args);
+    }
+  };
+}
+
+function overrideWithin(chaiUtils: Chai.ChaiUtils) {
+  return (_super: (...args: any[]) => any) =>
+    overwriteBigNumberWithin(_super, chaiUtils);
+}
+
+function overwriteBigNumberWithin(
+  _super: (...args: any[]) => any,
+  chaiUtils: Chai.ChaiUtils,
+) {
+  return function (this: Chai.AssertionStatic, ...args: any[]) {
+    const [startArg, finishArg] = args;
+    const expectedFlag = chaiUtils.flag(this, "object");
+
+    if (isBigInt(expectedFlag) || isBigInt(startArg) || isBigInt(finishArg)) {
+      const expected = toBigInt(expectedFlag);
+      const start = toBigInt(startArg);
+      const finish = toBigInt(finishArg);
+      this.assert(
+        start <= expected && expected <= finish,
+        `expected ${expected} to be within ${start}..${finish}`,
+        `expected ${expected} to not be within ${start}..${finish}`,
+        expected,
+        [start, finish],
+      );
+    } else {
+      _super.apply(this, args);
+    }
+  };
+}
+
+function overrideCloseTo(chaiUtils: Chai.ChaiUtils) {
+  return (_super: (...args: any[]) => any) =>
+    overwriteBigNumberCloseTo(_super, chaiUtils);
+}
+
+function overwriteBigNumberCloseTo(
+  _super: (...args: any[]) => any,
+  chaiUtils: Chai.ChaiUtils,
+) {
+  return function (this: Chai.AssertionStatic, ...args: any[]) {
+    const [actualArg, deltaArg] = args;
+    const expectedFlag = chaiUtils.flag(this, "object");
+
+    if (
+      isBigInt(expectedFlag) ||
+      isBigInt(actualArg) ||
+      isBigInt(deltaArg) ||
+      typeof actualArg === "number"
+    ) {
+      if (deltaArg === undefined) {
+        // eslint-disable-next-line no-restricted-syntax -- keep the original chai error structure
+        throw new AssertionError(
+          "the arguments to closeTo or approximately must be numbers, and a delta is required",
+        );
+      }
+
+      const expected = toBigInt(expectedFlag);
+      const actual = toBigInt(actualArg);
+      const delta = toBigInt(deltaArg);
+
+      function abs(i: bigint): bigint {
+        return i < 0 ? BigInt(-1) * i : i;
+      }
+
+      this.assert(
+        abs(expected - actual) <= delta,
+        `expected ${expected} to be close to ${actual} +/- ${delta}`,
+        `expected ${expected} not to be close to ${actual} +/- ${delta}`,
+        expected,
+        `A number between ${actual - delta} and ${actual + delta}`,
+      );
+    } else {
+      _super.apply(this, args);
+    }
+  };
+}
+
+function deepEqualComparator(a: any, b: any): boolean | null {
+  try {
+    const normalizedA = toBigInt(a);
+    const normalizedB = toBigInt(b);
+    return normalizedA === normalizedB;
+  } catch (e) {
+    // use default comparator
+    return null;
+  }
+}