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

package/src/internal/matchers/emit.ts

@@ -0,0 +1,232 @@
+import type { AssertWithSsfi, Ssfi } from "../utils/ssfi.js";
+import type { EventFragment } from "ethers/abi";
+import type { Contract } from "ethers/contract";
+import type { Provider, TransactionReceipt } from "ethers/providers";
+import type { Transaction } from "ethers/transaction";
+
+import util from "node:util";
+
+import { HardhatError } from "@nomicfoundation/hardhat-errors";
+import { AssertionError } from "chai";
+
+import { ASSERTION_ABORTED, EMIT_MATCHER } from "../constants.js";
+import { assertArgsArraysEqual, assertIsNotNull } from "../utils/asserts.js";
+import { buildAssert } from "../utils/build-assert.js";
+import { preventAsyncMatcherChaining } from "../utils/prevent-chaining.js";
+
+export const EMIT_CALLED = "emitAssertionCalled";
+
+async function waitForPendingTransaction(
+  tx: Promise<Transaction> | Transaction | string,
+  provider: Provider,
+) {
+  let hash: string | null;
+  if (tx instanceof Promise) {
+    ({ hash } = await tx);
+  } else if (typeof tx === "string") {
+    hash = tx;
+  } else {
+    ({ hash } = tx);
+  }
+
+  if (hash === null) {
+    throw new HardhatError(
+      HardhatError.ERRORS.CHAI_MATCHERS.INVALID_TRANSACTION,
+      { transaction: JSON.stringify(tx) },
+    );
+  }
+
+  return provider.getTransactionReceipt(hash);
+}
+
+export function supportEmit(
+  Assertion: Chai.AssertionStatic,
+  chaiUtils: Chai.ChaiUtils,
+): void {
+  Assertion.addMethod(
+    EMIT_MATCHER,
+    function (
+      this: any,
+      contract: Contract,
+      eventName: string,
+      ...args: any[]
+    ) {
+      // capture negated flag before async code executes; see buildAssert's jsdoc
+      const negated = this.__flags.negate;
+      const tx = this._obj;
+
+      preventAsyncMatcherChaining(this, EMIT_MATCHER, chaiUtils, true);
+
+      const promise = this.then === undefined ? Promise.resolve() : this;
+
+      const onSuccess = (receipt: TransactionReceipt) => {
+        // abort if the assertion chain was aborted, for example because
+        // a `.not` was combined with a `.withArgs`
+        if (chaiUtils.flag(this, ASSERTION_ABORTED) === true) {
+          return;
+        }
+
+        const assert = buildAssert(negated, onSuccess);
+
+        let eventFragment: EventFragment | null = null;
+        try {
+          eventFragment = contract.interface.getEvent(eventName, []);
+        } catch (e) {
+          if (e instanceof TypeError) {
+            const errorMessage = e.message.split(" (argument=")[0];
+            // eslint-disable-next-line no-restricted-syntax -- keep the original chai error structure
+            throw new AssertionError(errorMessage);
+          }
+        }
+
+        if (eventFragment === null) {
+          // eslint-disable-next-line no-restricted-syntax -- keep the original chai error structure
+          throw new AssertionError(
+            `Event "${eventName}" doesn't exist in the contract`,
+          );
+        }
+
+        const topic = eventFragment.topicHash;
+        const contractAddress = contract.target;
+        if (typeof contractAddress !== "string") {
+          throw new HardhatError(
+            HardhatError.ERRORS.CHAI_MATCHERS.CONTRACT_TARGET_MUST_BE_A_STRING,
+          );
+        }
+
+        if (args.length > 0) {
+          throw new HardhatError(
+            HardhatError.ERRORS.CHAI_MATCHERS.EMIT_EXPECTS_TWO_ARGUMENTS,
+          );
+        }
+
+        this.logs = receipt.logs
+          .filter((log) => log.topics.includes(topic))
+          .filter(
+            (log) =>
+              log.address.toLowerCase() === contractAddress.toLowerCase(),
+          );
+
+        assert(
+          this.logs.length > 0,
+          `Expected event "${eventName}" to be emitted, but it wasn't`,
+          `Expected event "${eventName}" NOT to be emitted, but it was`,
+        );
+        chaiUtils.flag(this, "eventName", eventName);
+        chaiUtils.flag(this, "contract", contract);
+      };
+
+      const derivedPromise = promise.then(() => {
+        // abort if the assertion chain was aborted, for example because
+        // a `.not` was combined with a `.withArgs`
+        if (chaiUtils.flag(this, ASSERTION_ABORTED) === true) {
+          return;
+        }
+
+        if (contract.runner === null || contract.runner.provider === null) {
+          throw new HardhatError(
+            HardhatError.ERRORS.CHAI_MATCHERS.CONTRACT_RUNNER_PROVIDER_NOT_NULL,
+          );
+        }
+
+        return waitForPendingTransaction(tx, contract.runner.provider).then(
+          (receipt) => {
+            assertIsNotNull(receipt, "receipt");
+            return onSuccess(receipt);
+          },
+        );
+      });
+
+      chaiUtils.flag(this, EMIT_CALLED, true);
+
+      this.then = derivedPromise.then.bind(derivedPromise);
+      this.catch = derivedPromise.catch.bind(derivedPromise);
+      this.promise = derivedPromise;
+      return this;
+    },
+  );
+}
+
+export async function emitWithArgs(
+  context: any,
+  Assertion: Chai.AssertionStatic,
+  chaiUtils: Chai.ChaiUtils,
+  expectedArgs: any[],
+  ssfi: Ssfi,
+): Promise<void> {
+  const negated = false; // .withArgs cannot be negated
+  const assert = buildAssert(negated, ssfi);
+
+  tryAssertArgsArraysEqual(
+    context,
+    Assertion,
+    chaiUtils,
+    expectedArgs,
+    context.logs,
+    assert,
+    ssfi,
+  );
+}
+
+const tryAssertArgsArraysEqual = (
+  context: any,
+  Assertion: Chai.AssertionStatic,
+  chaiUtils: Chai.ChaiUtils,
+  expectedArgs: any[],
+  logs: any[],
+  assert: AssertWithSsfi,
+  ssfi: Ssfi,
+) => {
+  const eventName = chaiUtils.flag(context, "eventName");
+
+  if (logs.length === 1) {
+    const parsedLog = chaiUtils
+      .flag(context, "contract")
+      .interface.parseLog(logs[0]);
+    assertIsNotNull(parsedLog, "parsedLog");
+
+    return assertArgsArraysEqual(
+      Assertion,
+      expectedArgs,
+      parsedLog.args,
+      `"${eventName}" event`,
+      "event",
+      assert,
+      ssfi,
+    );
+  }
+
+  for (const index in logs) {
+    if (index === undefined) {
+      break;
+    } else {
+      try {
+        const parsedLog = chaiUtils
+          .flag(context, "contract")
+          .interface.parseLog(logs[index]);
+        assertIsNotNull(parsedLog, "parsedLog");
+
+        assertArgsArraysEqual(
+          Assertion,
+          expectedArgs,
+          parsedLog.args,
+          `"${eventName}" event`,
+          "event",
+          assert,
+          ssfi,
+        );
+
+        return;
+      } catch {}
+    }
+  }
+
+  assert(
+    false,
+    `The specified arguments (${util.inspect(
+      expectedArgs,
+    )}) were not included in any of the ${
+      context.logs.length
+    } emitted "${eventName}" events`,
+  );
+};

package/src/internal/matchers/hexEqual.ts

@@ -0,0 +1,29 @@
+export function supportHexEqual(Assertion: Chai.AssertionStatic): void {
+  Assertion.addMethod("hexEqual", function (this: any, other: string) {
+    const subject = this._obj;
+    const isNegated = this.__flags.negate === true;
+
+    // check that both values are proper hex strings
+    const isHex = (a: string) => /^0x[0-9a-fA-F]*$/.test(a);
+    for (const element of [subject, other]) {
+      if (!isHex(element)) {
+        this.assert(
+          isNegated, // trick to make this assertion always fail
+          `Expected "${subject}" to be a hex string equal to "${other}", but "${element}" is not a valid hex string`,
+          `Expected "${subject}" not to be a hex string equal to "${other}", but "${element}" is not a valid hex string`,
+        );
+      }
+    }
+
+    // compare values
+    const extractNumeric = (hex: string) => hex.replace(/^0x0*/, "");
+    this.assert(
+      extractNumeric(subject.toLowerCase()) ===
+        extractNumeric(other.toLowerCase()),
+      `Expected "${subject}" to be a hex string equal to "${other}"`,
+      `Expected "${subject}" NOT to be a hex string equal to "${other}", but it was`,
+      `Hex string representing the same number as ${other}`,
+      subject,
+    );
+  });
+}

package/src/internal/matchers/properAddress.ts

@@ -0,0 +1,12 @@
+export function supportProperAddress(Assertion: Chai.AssertionStatic): void {
+  Assertion.addProperty("properAddress", function (this: any) {
+    const subject = this._obj;
+    this.assert(
+      /^0x[0-9a-fA-F]{40}$/.test(subject),
+      `Expected "${subject}" to be a proper address`,
+      `Expected "${subject}" NOT to be a proper address`,
+      "proper address (eg.: 0x1234567890123456789012345678901234567890)",
+      subject,
+    );
+  });
+}

package/src/internal/matchers/properHex.ts

@@ -0,0 +1,29 @@
+export function supportProperHex(Assertion: Chai.AssertionStatic): void {
+  Assertion.addMethod("properHex", function (this: any, length: number) {
+    const subject = this._obj;
+    const isNegated = this.__flags.negate === true;
+
+    const isHex = (a: string) => /^0x[0-9a-fA-F]*$/.test(a);
+    if (!isHex(subject)) {
+      this.assert(
+        isNegated, // trick to make this assertion always fail
+        `Expected "${subject}" to be a proper hex string, but it contains invalid (non-hex) characters`,
+        `Expected "${subject}" NOT to be a proper hex string, but it contains only valid hex characters`,
+      );
+    }
+
+    this.assert(
+      subject.length === length + 2,
+      `Expected "${subject}" to be a hex string of length ${
+        length + 2
+      } (the provided ${length} plus 2 more for the "0x" prefix), but its length is ${
+        subject.length
+      }`,
+      `Expected "${subject}" NOT to be a hex string of length ${
+        length + 2
+      } (the provided ${length} plus 2 more for the "0x" prefix), but its length is ${
+        subject.length
+      }`,
+    );
+  });
+}

package/src/internal/matchers/properPrivateKey.ts

@@ -0,0 +1,12 @@
+export function supportProperPrivateKey(Assertion: Chai.AssertionStatic): void {
+  Assertion.addProperty("properPrivateKey", function (this: any) {
+    const subject = this._obj;
+    this.assert(
+      /^0x[0-9a-fA-F]{64}$/.test(subject),
+      `Expected "${subject}" to be a proper private key`,
+      `Expected "${subject}" NOT to be a proper private key`,
+      "proper private key (eg.: 0x1010101010101010101010101010101010101010101010101010101010101010)",
+      subject,
+    );
+  });
+}

package/src/internal/matchers/reverted/panic.ts

@@ -0,0 +1,36 @@
+export const PANIC_CODES = {
+  ASSERTION_ERROR: 0x1,
+  ARITHMETIC_OVERFLOW: 0x11,
+  DIVISION_BY_ZERO: 0x12,
+  ENUM_CONVERSION_OUT_OF_BOUNDS: 0x21,
+  INCORRECTLY_ENCODED_STORAGE_BYTE_ARRAY: 0x22,
+  POP_ON_EMPTY_ARRAY: 0x31,
+  ARRAY_ACCESS_OUT_OF_BOUNDS: 0x32,
+  TOO_MUCH_MEMORY_ALLOCATED: 0x41,
+  ZERO_INITIALIZED_VARIABLE: 0x51,
+};
+
+export function panicErrorCodeToReason(errorCode: bigint): string | undefined {
+  switch (errorCode) {
+    case 0x1n:
+      return "Assertion error";
+    case 0x11n:
+      return "Arithmetic operation overflowed outside of an unchecked block";
+    case 0x12n:
+      return "Division or modulo division by zero";
+    case 0x21n:
+      return "Tried to convert a value into an enum, but the value was too big or negative";
+    case 0x22n:
+      return "Incorrectly encoded storage byte array";
+    case 0x31n:
+      return ".pop() was called on an empty array";
+    case 0x32n:
+      return "Array accessed at an out-of-bounds or negative index";
+    case 0x41n:
+      return "Too much memory was allocated, or an array was created that is too large";
+    case 0x51n:
+      return "Called a zero-initialized variable of internal function type";
+    default:
+      return undefined;
+  }
+}

package/src/internal/matchers/reverted/reverted.ts

@@ -0,0 +1,165 @@
+import type { HardhatEthers } from "@nomicfoundation/hardhat-ethers/types";
+
+import { HardhatError } from "@nomicfoundation/hardhat-errors";
+import { numberToHexString } from "@nomicfoundation/hardhat-utils/hex";
+
+import { REVERTED_MATCHER } from "../../constants.js";
+import { assertIsNotNull } from "../../utils/asserts.js";
+import { buildAssert } from "../../utils/build-assert.js";
+import { preventAsyncMatcherChaining } from "../../utils/prevent-chaining.js";
+
+import {
+  decodeReturnData,
+  getReturnDataFromError,
+  parseBytes32String,
+} from "./utils.js";
+
+export function supportReverted(
+  Assertion: Chai.AssertionStatic,
+  chaiUtils: Chai.ChaiUtils,
+): void {
+  Assertion.addMethod(
+    REVERTED_MATCHER,
+    function (this: any, ethers: HardhatEthers) {
+      // capture negated flag before async code executes; see buildAssert's jsdoc
+      const negated = this.__flags.negate;
+
+      const subject: unknown = this._obj;
+
+      preventAsyncMatcherChaining(this, REVERTED_MATCHER, chaiUtils);
+
+      // Check if the received value can be linked to a transaction, and then
+      // get the receipt of that transaction and check its status.
+      //
+      // If the value doesn't correspond to a transaction, then the `reverted`
+      // assertion is false.
+      const onSuccess = async (value: unknown) => {
+        const assert = buildAssert(negated, onSuccess);
+
+        if (isTransactionResponse(value) || typeof value === "string") {
+          const hash = typeof value === "string" ? value : value.hash;
+
+          if (!isValidTransactionHash(hash)) {
+            throw new HardhatError(
+              HardhatError.ERRORS.CHAI_MATCHERS.EXPECTED_VALID_TRANSACTION_HASH,
+              {
+                hash,
+              },
+            );
+          }
+
+          const receipt = await getTransactionReceipt(ethers, hash);
+
+          if (receipt === null) {
+            // If the receipt is null, maybe the string is a bytes32 string
+            if (isBytes32String(hash)) {
+              assert(false, "Expected transaction to be reverted");
+              return;
+            }
+          }
+
+          assertIsNotNull(receipt, "receipt");
+          assert(
+            receipt.status === 0,
+            "Expected transaction to be reverted",
+            "Expected transaction NOT to be reverted",
+          );
+        } else if (isTransactionReceipt(value)) {
+          const receipt = value;
+
+          assert(
+            receipt.status === 0,
+            "Expected transaction to be reverted",
+            "Expected transaction NOT to be reverted",
+          );
+        } else {
+          // If the subject of the assertion is not connected to a transaction
+          // (hash, receipt, etc.), then the assertion fails.
+          // Since we use `false` here, this means that `.not.to.be.reverted`
+          // assertions will pass instead of always throwing a validation error.
+          // This allows users to do things like:
+          //   `expect(c.callStatic.f()).to.not.be.reverted`
+          assert(false, "Expected transaction to be reverted");
+        }
+      };
+
+      const onError = (error: any) => {
+        const assert = buildAssert(negated, onError);
+        const returnData = getReturnDataFromError(error);
+        const decodedReturnData = decodeReturnData(returnData);
+
+        if (
+          decodedReturnData.kind === "Empty" ||
+          decodedReturnData.kind === "Custom"
+        ) {
+          // in the negated case, if we can't decode the reason, we just indicate
+          // that the transaction didn't revert
+          assert(true, undefined, `Expected transaction NOT to be reverted`);
+        } else if (decodedReturnData.kind === "Error") {
+          assert(
+            true,
+            undefined,
+            `Expected transaction NOT to be reverted, but it reverted with reason '${decodedReturnData.reason}'`,
+          );
+        } else if (decodedReturnData.kind === "Panic") {
+          assert(
+            true,
+            undefined,
+            `Expected transaction NOT to be reverted, but it reverted with panic code ${numberToHexString(
+              decodedReturnData.code,
+            )} (${decodedReturnData.description})`,
+          );
+        } else {
+          const _exhaustiveCheck: never = decodedReturnData;
+        }
+      };
+
+      // we use `Promise.resolve(subject)` so we can process both values and
+      // promises of values in the same way
+      const derivedPromise = Promise.resolve(subject).then(onSuccess, onError);
+
+      this.then = derivedPromise.then.bind(derivedPromise);
+      this.catch = derivedPromise.catch.bind(derivedPromise);
+
+      return this;
+    },
+  );
+}
+
+async function getTransactionReceipt(ethers: HardhatEthers, hash: string) {
+  return ethers.provider.getTransactionReceipt(hash);
+}
+
+function isTransactionResponse(x: unknown): x is { hash: string } {
+  if (typeof x === "object" && x !== null) {
+    return "hash" in x;
+  }
+
+  return false;
+}
+
+function isTransactionReceipt(x: unknown): x is { status: number } {
+  if (typeof x === "object" && x !== null && "status" in x) {
+    const status = x.status;
+
+    // this means we only support ethers's receipts for now; adding support for
+    // raw receipts, where the status is an hexadecimal string, should be easy
+    // and we can do it if there's demand for that
+    return typeof status === "number";
+  }
+
+  return false;
+}
+
+function isValidTransactionHash(x: string): boolean {
+  return /0x[0-9a-fA-F]{64}/.test(x);
+}
+
+function isBytes32String(v: string): boolean {
+  try {
+    parseBytes32String(v);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/internal/matchers/reverted/revertedWith.ts

@@ -0,0 +1,100 @@
+import { HardhatError } from "@nomicfoundation/hardhat-errors";
+import { numberToHexString } from "@nomicfoundation/hardhat-utils/hex";
+
+import { REVERTED_WITH_MATCHER } from "../../constants.js";
+import { buildAssert } from "../../utils/build-assert.js";
+import { preventAsyncMatcherChaining } from "../../utils/prevent-chaining.js";
+
+import { decodeReturnData, getReturnDataFromError } from "./utils.js";
+
+export function supportRevertedWith(
+  Assertion: Chai.AssertionStatic,
+  chaiUtils: Chai.ChaiUtils,
+): void {
+  Assertion.addMethod(
+    REVERTED_WITH_MATCHER,
+    function (this: any, expectedReason: string | RegExp) {
+      // capture negated flag before async code executes; see buildAssert's jsdoc
+      const negated = this.__flags.negate;
+
+      // validate expected reason
+      if (
+        !(expectedReason instanceof RegExp) &&
+        typeof expectedReason !== "string"
+      ) {
+        // if the input validation fails, we discard the subject since it could
+        // potentially be a rejected promise
+        Promise.resolve(this._obj).catch(() => {});
+
+        throw new HardhatError(
+          HardhatError.ERRORS.CHAI_MATCHERS.EXPECT_STRING_OR_REGEX_AS_REVERT_REASON,
+        );
+      }
+
+      const expectedReasonString =
+        expectedReason instanceof RegExp
+          ? expectedReason.source
+          : expectedReason;
+
+      preventAsyncMatcherChaining(this, REVERTED_WITH_MATCHER, chaiUtils);
+
+      const onSuccess = () => {
+        const assert = buildAssert(negated, onSuccess);
+
+        assert(
+          false,
+          `Expected transaction to be reverted with reason '${expectedReasonString}', but it didn't revert`,
+        );
+      };
+
+      const onError = (error: any) => {
+        const assert = buildAssert(negated, onError);
+
+        const returnData = getReturnDataFromError(error);
+        const decodedReturnData = decodeReturnData(returnData);
+
+        if (decodedReturnData.kind === "Empty") {
+          assert(
+            false,
+            `Expected transaction to be reverted with reason '${expectedReasonString}', but it reverted without a reason`,
+          );
+        } else if (decodedReturnData.kind === "Error") {
+          const matchesExpectedReason =
+            expectedReason instanceof RegExp
+              ? expectedReason.test(decodedReturnData.reason)
+              : decodedReturnData.reason === expectedReasonString;
+
+          assert(
+            matchesExpectedReason,
+            `Expected transaction to be reverted with reason '${expectedReasonString}', but it reverted with reason '${decodedReturnData.reason}'`,
+            `Expected transaction NOT to be reverted with reason '${expectedReasonString}', but it was`,
+          );
+        } else if (decodedReturnData.kind === "Panic") {
+          assert(
+            false,
+            `Expected transaction to be reverted with reason '${expectedReasonString}', but it reverted with panic code ${numberToHexString(
+              decodedReturnData.code,
+            )} (${decodedReturnData.description})`,
+          );
+        } else if (decodedReturnData.kind === "Custom") {
+          assert(
+            false,
+            `Expected transaction to be reverted with reason '${expectedReasonString}', but it reverted with a custom error`,
+          );
+        } else {
+          const _exhaustiveCheck: never = decodedReturnData;
+        }
+      };
+
+      const derivedPromise = Promise.resolve(this._obj).then(
+        onSuccess,
+        onError,
+      );
+
+      this.then = derivedPromise.then.bind(derivedPromise);
+      this.catch = derivedPromise.catch.bind(derivedPromise);
+
+      return this;
+    },
+  );
+}