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

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

@@ -0,0 +1,243 @@
+import type { Ssfi } from "../../utils/ssfi.js";
+import type { ErrorFragment, Interface } from "ethers/abi";
+import type { BaseContract } from "ethers/contract";
+
+import { HardhatError } from "@nomicfoundation/hardhat-errors";
+import { numberToHexString } from "@nomicfoundation/hardhat-utils/hex";
+
+import {
+  ASSERTION_ABORTED,
+  REVERTED_WITH_CUSTOM_ERROR_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";
+
+import {
+  decodeReturnData,
+  getReturnDataFromError,
+  resultToArray,
+} from "./utils.js";
+
+export const REVERTED_WITH_CUSTOM_ERROR_CALLED = "customErrorAssertionCalled";
+
+interface CustomErrorAssertionData {
+  contractInterface: Interface;
+  returnData: string;
+  customError: ErrorFragment;
+}
+
+export function supportRevertedWithCustomError(
+  Assertion: Chai.AssertionStatic,
+  chaiUtils: Chai.ChaiUtils,
+): void {
+  Assertion.addMethod(
+    REVERTED_WITH_CUSTOM_ERROR_MATCHER,
+    function (
+      this: any,
+      contract: BaseContract,
+      expectedCustomErrorName: string,
+      ...args: any[]
+    ) {
+      // capture negated flag before async code executes; see buildAssert's jsdoc
+      const negated = this.__flags.negate;
+
+      const { iface, expectedCustomError } = validateInput(
+        this._obj,
+        contract,
+        expectedCustomErrorName,
+        args,
+      );
+
+      preventAsyncMatcherChaining(
+        this,
+        REVERTED_WITH_CUSTOM_ERROR_MATCHER,
+        chaiUtils,
+      );
+
+      const onSuccess = () => {
+        if (chaiUtils.flag(this, ASSERTION_ABORTED) === true) {
+          return;
+        }
+
+        const assert = buildAssert(negated, onSuccess);
+
+        assert(
+          false,
+          `Expected transaction to be reverted with custom error '${expectedCustomErrorName}', but it didn't revert`,
+        );
+      };
+
+      const onError = (error: any) => {
+        if (chaiUtils.flag(this, ASSERTION_ABORTED) === true) {
+          return;
+        }
+
+        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 custom error '${expectedCustomErrorName}', but it reverted without a reason`,
+          );
+        } else if (decodedReturnData.kind === "Error") {
+          assert(
+            false,
+            `Expected transaction to be reverted with custom error '${expectedCustomErrorName}', but it reverted with reason '${decodedReturnData.reason}'`,
+          );
+        } else if (decodedReturnData.kind === "Panic") {
+          assert(
+            false,
+            `Expected transaction to be reverted with custom error '${expectedCustomErrorName}', but it reverted with panic code ${numberToHexString(
+              decodedReturnData.code,
+            )} (${decodedReturnData.description})`,
+          );
+        } else if (decodedReturnData.kind === "Custom") {
+          if (decodedReturnData.id === expectedCustomError.selector) {
+            // add flag with the data needed for .withArgs
+            const customErrorAssertionData: CustomErrorAssertionData = {
+              contractInterface: iface,
+              customError: expectedCustomError,
+              returnData,
+            };
+            this.customErrorData = customErrorAssertionData;
+
+            assert(
+              true,
+              undefined,
+              `Expected transaction NOT to be reverted with custom error '${expectedCustomErrorName}', but it was`,
+            );
+          } else {
+            // try to decode the actual custom error
+            // this will only work when the error comes from the given contract
+            const actualCustomError = iface.getError(decodedReturnData.id);
+
+            if (actualCustomError === null) {
+              assert(
+                false,
+                `Expected transaction to be reverted with custom error '${expectedCustomErrorName}', but it reverted with a different custom error`,
+              );
+            } else {
+              assert(
+                false,
+                `Expected transaction to be reverted with custom error '${expectedCustomErrorName}', but it reverted with custom error '${actualCustomError.name}'`,
+              );
+            }
+          }
+        } else {
+          const _exhaustiveCheck: never = decodedReturnData;
+        }
+      };
+
+      const derivedPromise = Promise.resolve(this._obj).then(
+        onSuccess,
+        onError,
+      );
+
+      // needed for .withArgs
+      chaiUtils.flag(this, REVERTED_WITH_CUSTOM_ERROR_CALLED, true);
+      this.promise = derivedPromise;
+
+      this.then = derivedPromise.then.bind(derivedPromise);
+      this.catch = derivedPromise.catch.bind(derivedPromise);
+
+      return this;
+    },
+  );
+}
+
+function validateInput(
+  obj: any,
+  contract: BaseContract,
+  expectedCustomErrorName: string,
+  args: any[],
+): { iface: Interface; expectedCustomError: ErrorFragment } {
+  try {
+    // check the case where users forget to pass the contract as the first
+    // argument
+    if (typeof contract === "string" || contract?.interface === undefined) {
+      // discard subject since it could potentially be a rejected promise
+      throw new HardhatError(
+        HardhatError.ERRORS.CHAI_MATCHERS.FIRST_ARGUMENT_MUST_BE_A_CONTRACT,
+      );
+    }
+
+    // validate custom error name
+    if (typeof expectedCustomErrorName !== "string") {
+      throw new HardhatError(
+        HardhatError.ERRORS.CHAI_MATCHERS.STRING_EXPECTED_AS_CUSTOM_ERROR_NAME,
+      );
+    }
+
+    const iface = contract.interface;
+    const expectedCustomError = iface.getError(expectedCustomErrorName);
+
+    // check that interface contains the given custom error
+    if (expectedCustomError === null) {
+      throw new HardhatError(
+        HardhatError.ERRORS.CHAI_MATCHERS.CONTRACT_DOES_NOT_HAVE_CUSTOM_ERROR,
+        {
+          customErrorName: expectedCustomErrorName,
+        },
+      );
+    }
+
+    if (args.length > 0) {
+      throw new HardhatError(
+        HardhatError.ERRORS.CHAI_MATCHERS.REVERT_INVALID_ARGUMENTS_LENGTH,
+      );
+    }
+
+    return { iface, expectedCustomError };
+  } catch (e) {
+    // if the input validation fails, we discard the subject since it could
+    // potentially be a rejected promise
+    Promise.resolve(obj).catch(() => {});
+    throw e;
+  }
+}
+
+export async function revertedWithCustomErrorWithArgs(
+  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);
+
+  const customErrorAssertionData: CustomErrorAssertionData =
+    context.customErrorData;
+
+  if (customErrorAssertionData === undefined) {
+    throw new HardhatError(
+      HardhatError.ERRORS.CHAI_MATCHERS.WITH_ARGS_FORBIDDEN,
+    );
+  }
+
+  const { contractInterface, customError, returnData } =
+    customErrorAssertionData;
+
+  const errorFragment = contractInterface.getError(customError.name);
+
+  assertIsNotNull(errorFragment, "errorFragment");
+
+  // We transform ether's Array-like object into an actual array as it's safer
+  const actualArgs = resultToArray(
+    contractInterface.decodeErrorResult(errorFragment, returnData),
+  );
+
+  assertArgsArraysEqual(
+    Assertion,
+    expectedArgs,
+    actualArgs,
+    `"${customError.name}" custom error`,
+    "error",
+    assert,
+    ssfi,
+  );
+}

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

@@ -0,0 +1,118 @@
+import { HardhatError } from "@nomicfoundation/hardhat-errors";
+import { toBigInt } from "@nomicfoundation/hardhat-utils/bigint";
+import { numberToHexString } from "@nomicfoundation/hardhat-utils/hex";
+
+import { REVERTED_WITH_PANIC_MATCHER } from "../../constants.js";
+import { buildAssert } from "../../utils/build-assert.js";
+import { preventAsyncMatcherChaining } from "../../utils/prevent-chaining.js";
+
+import { panicErrorCodeToReason } from "./panic.js";
+import { decodeReturnData, getReturnDataFromError } from "./utils.js";
+
+export function supportRevertedWithPanic(
+  Assertion: Chai.AssertionStatic,
+  chaiUtils: Chai.ChaiUtils,
+): void {
+  Assertion.addMethod(
+    REVERTED_WITH_PANIC_MATCHER,
+    function (this: any, expectedCodeArg: any) {
+      // capture negated flag before async code executes; see buildAssert's jsdoc
+      const negated = this.__flags.negate;
+
+      let expectedCode: bigint | undefined;
+      try {
+        if (expectedCodeArg !== undefined) {
+          expectedCode = toBigInt(expectedCodeArg);
+        }
+      } catch {
+        // 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.PANIC_CODE_EXPECTED,
+          {
+            panicCode: expectedCodeArg,
+          },
+        );
+      }
+
+      const code: bigint | undefined = expectedCode;
+
+      let description: string | undefined;
+      let formattedPanicCode: string;
+      if (code === undefined) {
+        formattedPanicCode = "some panic code";
+      } else {
+        const codeBN = toBigInt(code);
+        description = panicErrorCodeToReason(codeBN) ?? "unknown panic code";
+        formattedPanicCode = `panic code ${numberToHexString(codeBN)} (${description})`;
+      }
+
+      preventAsyncMatcherChaining(this, REVERTED_WITH_PANIC_MATCHER, chaiUtils);
+
+      const onSuccess = () => {
+        const assert = buildAssert(negated, onSuccess);
+
+        assert(
+          false,
+          `Expected transaction to be reverted with ${formattedPanicCode}, 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 ${formattedPanicCode}, but it reverted without a reason`,
+          );
+        } else if (decodedReturnData.kind === "Error") {
+          assert(
+            false,
+            `Expected transaction to be reverted with ${formattedPanicCode}, but it reverted with reason '${decodedReturnData.reason}'`,
+          );
+        } else if (decodedReturnData.kind === "Panic") {
+          if (code !== undefined) {
+            assert(
+              decodedReturnData.code === code,
+              `Expected transaction to be reverted with ${formattedPanicCode}, but it reverted with panic code ${numberToHexString(
+                decodedReturnData.code,
+              )} (${decodedReturnData.description})`,
+              `Expected transaction NOT to be reverted with ${formattedPanicCode}, but it was`,
+            );
+          } else {
+            assert(
+              true,
+              undefined,
+              `Expected transaction NOT to be reverted with ${formattedPanicCode}, but it reverted with panic code ${numberToHexString(
+                decodedReturnData.code,
+              )} (${decodedReturnData.description})`,
+            );
+          }
+        } else if (decodedReturnData.kind === "Custom") {
+          assert(
+            false,
+            `Expected transaction to be reverted with ${formattedPanicCode}, 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;
+    },
+  );
+}

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

@@ -0,0 +1,73 @@
+import { numberToHexString } from "@nomicfoundation/hardhat-utils/hex";
+
+import { REVERTED_WITHOUT_REASON_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 supportRevertedWithoutReason(
+  Assertion: Chai.AssertionStatic,
+  chaiUtils: Chai.ChaiUtils,
+): void {
+  Assertion.addMethod(REVERTED_WITHOUT_REASON_MATCHER, function (this: any) {
+    // capture negated flag before async code executes; see buildAssert's jsdoc
+    const negated = this.__flags.negate;
+
+    preventAsyncMatcherChaining(
+      this,
+      REVERTED_WITHOUT_REASON_MATCHER,
+      chaiUtils,
+    );
+
+    const onSuccess = () => {
+      const assert = buildAssert(negated, onSuccess);
+
+      assert(
+        false,
+        `Expected transaction to be reverted without a reason, 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 === "Error") {
+        assert(
+          false,
+          `Expected transaction to be reverted without a reason, but it reverted with reason '${decodedReturnData.reason}'`,
+        );
+      } else if (decodedReturnData.kind === "Empty") {
+        assert(
+          true,
+          undefined,
+          "Expected transaction NOT to be reverted without a reason, but it was",
+        );
+      } else if (decodedReturnData.kind === "Panic") {
+        assert(
+          false,
+          `Expected transaction to be reverted without a reason, but it reverted with panic code ${numberToHexString(
+            decodedReturnData.code,
+          )} (${decodedReturnData.description})`,
+        );
+      } else if (decodedReturnData.kind === "Custom") {
+        assert(
+          false,
+          `Expected transaction to be reverted without a reason, 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;
+  });
+}

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

@@ -0,0 +1,147 @@
+import type { Result } from "ethers/abi";
+
+import { HardhatError } from "@nomicfoundation/hardhat-errors";
+import { ensureError } from "@nomicfoundation/hardhat-utils/error";
+import { AssertionError } from "chai";
+import { AbiCoder, decodeBytes32String } from "ethers/abi";
+
+import { panicErrorCodeToReason } from "./panic.js";
+
+// method id of 'Error(string)'
+const ERROR_STRING_PREFIX = "0x08c379a0";
+
+// method id of 'Panic(uint256)'
+const PANIC_CODE_PREFIX = "0x4e487b71";
+
+/**
+ * Try to obtain the return data of a transaction from the given value.
+ *
+ * If the value is an error but it doesn't have data, we assume it's not related
+ * to a reverted transaction and we re-throw it.
+ */
+export function getReturnDataFromError(error: any): string {
+  if (!(error instanceof Error)) {
+    // eslint-disable-next-line no-restricted-syntax -- keep the original chai error structure
+    throw new AssertionError("Expected an Error object");
+  }
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- some properties do not exist in the default Error instance
+  const typedError = error as any;
+
+  const errorData = typedError.data ?? typedError.error?.data;
+
+  if (errorData === undefined) {
+    // eslint-disable-next-line no-restricted-syntax -- re-throw because the error is not related to a reverted transaction
+    throw error;
+  }
+
+  const returnData = typeof errorData === "string" ? errorData : errorData.data;
+
+  if (returnData === undefined || typeof returnData !== "string") {
+    // eslint-disable-next-line no-restricted-syntax -- re-throw because the error is not related to a reverted transaction
+    throw error;
+  }
+
+  return returnData;
+}
+
+type DecodedReturnData =
+  | {
+      kind: "Error";
+      reason: string;
+    }
+  | {
+      kind: "Empty";
+    }
+  | {
+      kind: "Panic";
+      code: bigint;
+      description: string;
+    }
+  | {
+      kind: "Custom";
+      id: string;
+      data: string;
+    };
+
+export function decodeReturnData(returnData: string): DecodedReturnData {
+  const abi = new AbiCoder();
+
+  if (returnData === "0x") {
+    return { kind: "Empty" };
+  } else if (returnData.startsWith(ERROR_STRING_PREFIX)) {
+    const encodedReason = returnData.slice(ERROR_STRING_PREFIX.length);
+    let reason: string;
+
+    try {
+      reason = abi.decode(["string"], `0x${encodedReason}`)[0];
+    } catch (e) {
+      ensureError(e);
+
+      throw new HardhatError(HardhatError.ERRORS.CHAI_MATCHERS.DECODING_ERROR, {
+        encodedData: encodedReason,
+        type: "string",
+        reason: e.message,
+      });
+    }
+
+    return {
+      kind: "Error",
+      reason,
+    };
+  } else if (returnData.startsWith(PANIC_CODE_PREFIX)) {
+    const encodedReason = returnData.slice(PANIC_CODE_PREFIX.length);
+    let code: bigint;
+    try {
+      code = abi.decode(["uint256"], `0x${encodedReason}`)[0];
+    } catch (e) {
+      ensureError(e);
+
+      throw new HardhatError(HardhatError.ERRORS.CHAI_MATCHERS.DECODING_ERROR, {
+        encodedData: encodedReason,
+        type: "uint256",
+        reason: e.message,
+      });
+    }
+
+    const description = panicErrorCodeToReason(code) ?? "unknown panic code";
+
+    return {
+      kind: "Panic",
+      code,
+      description,
+    };
+  }
+
+  return {
+    kind: "Custom",
+    id: returnData.slice(0, 10),
+    data: `0x${returnData.slice(10)}`,
+  };
+}
+
+/**
+ * Takes an ethers result object and converts it into a (potentially nested) array.
+ *
+ * For example, given this error:
+ *
+ *   struct Point(uint x, uint y)
+ *   error MyError(string, Point)
+ *
+ *   revert MyError("foo", Point(1, 2))
+ *
+ * The resulting array will be: ["foo", [1n, 2n]]
+ */
+export function resultToArray(result: Result): any[] {
+  return result
+    .toArray()
+    .map((x) =>
+      typeof x === "object" && x !== null && "toArray" in x
+        ? resultToArray(x)
+        : x,
+    );
+}
+
+export function parseBytes32String(v: string): string {
+  return decodeBytes32String(v);
+}