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

package/src/internal/matchers/withArgs.ts

@@ -0,0 +1,139 @@
+import { HardhatError } from "@nomicfoundation/hardhat-errors";
+import { toBigInt } from "@nomicfoundation/hardhat-utils/bigint";
+import { AssertionError } from "chai";
+import { isAddressable } from "ethers/address";
+
+import { ASSERTION_ABORTED } from "../constants.js";
+import { isBigInt } from "../utils/bigint.js";
+
+import { emitWithArgs, EMIT_CALLED } from "./emit.js";
+import {
+  revertedWithCustomErrorWithArgs,
+  REVERTED_WITH_CUSTOM_ERROR_CALLED,
+} from "./reverted/revertedWithCustomError.js";
+
+/**
+ * A predicate for use with .withArgs(...), to induce chai to accept any value
+ * as a positive match with the argument.
+ *
+ * Example: expect(contract.emitInt()).to.emit(contract, "Int").withArgs(anyValue)
+ */
+export function anyValue(): boolean {
+  return true;
+}
+
+/**
+ * A predicate for use with .withArgs(...), to induce chai to accept any
+ * unsigned integer as a positive match with the argument.
+ *
+ * Example: expect(contract.emitUint()).to.emit(contract, "Uint").withArgs(anyUint)
+ */
+export function anyUint(i: any): boolean {
+  if (typeof i === "number") {
+    if (i < 0) {
+      // eslint-disable-next-line no-restricted-syntax -- keep the original chai error structure
+      throw new AssertionError(
+        `anyUint expected its argument to be an unsigned integer, but it was negative, with value ${i}`,
+      );
+    }
+
+    return true;
+  } else if (isBigInt(i)) {
+    const bigInt = toBigInt(i);
+
+    if (bigInt < 0) {
+      // eslint-disable-next-line no-restricted-syntax -- keep the original chai error structure
+      throw new AssertionError(
+        `anyUint expected its argument to be an unsigned integer, but it was negative, with value ${bigInt}`,
+      );
+    }
+    return true;
+  }
+
+  // eslint-disable-next-line no-restricted-syntax -- keep the original chai error structure
+  throw new AssertionError(
+    `anyUint expected its argument to be an integer, but its type was '${typeof i}'`,
+  );
+}
+
+export function supportWithArgs(
+  Assertion: Chai.AssertionStatic,
+  chaiUtils: Chai.ChaiUtils,
+): void {
+  Assertion.addMethod("withArgs", function (this: any, ...expectedArgs: any[]) {
+    const { emitCalled } = validateInput.call(this, chaiUtils);
+
+    // Resolve arguments to their canonical form:
+    // - Addressable → address
+    const resolveArgument = (arg: any) =>
+      isAddressable(arg) ? arg.getAddress() : arg;
+
+    const onSuccess = (resolvedExpectedArgs: any[]) => {
+      if (emitCalled) {
+        return emitWithArgs(
+          this,
+          Assertion,
+          chaiUtils,
+          resolvedExpectedArgs,
+          onSuccess,
+        );
+      } else {
+        return revertedWithCustomErrorWithArgs(
+          this,
+          Assertion,
+          chaiUtils,
+          resolvedExpectedArgs,
+          onSuccess,
+        );
+      }
+    };
+
+    const promise = (this.then === undefined ? Promise.resolve() : this)
+      .then(() => Promise.all(expectedArgs.map(resolveArgument)))
+      .then(onSuccess);
+
+    this.then = promise.then.bind(promise);
+    this.catch = promise.catch.bind(promise);
+    return this;
+  });
+}
+
+function validateInput(
+  this: any,
+  chaiUtils: Chai.ChaiUtils,
+): { emitCalled: boolean } {
+  try {
+    if (Boolean(this.__flags.negate)) {
+      throw new HardhatError(
+        HardhatError.ERRORS.CHAI_MATCHERS.WITH_ARGS_CANNOT_BE_COMBINED_WITH_NOT,
+      );
+    }
+
+    const emitCalled = chaiUtils.flag(this, EMIT_CALLED) === true;
+
+    const revertedWithCustomErrorCalled =
+      chaiUtils.flag(this, REVERTED_WITH_CUSTOM_ERROR_CALLED) === true;
+
+    if (!emitCalled && !revertedWithCustomErrorCalled) {
+      throw new HardhatError(
+        HardhatError.ERRORS.CHAI_MATCHERS.WITH_ARGS_WRONG_COMBINATION,
+      );
+    }
+
+    if (emitCalled && revertedWithCustomErrorCalled) {
+      throw new HardhatError(
+        HardhatError.ERRORS.CHAI_MATCHERS.WITH_ARGS_COMBINED_WITH_INCOMPATIBLE_ASSERTIONS,
+      );
+    }
+
+    return { emitCalled };
+  } catch (e) {
+    // signal that validation failed to allow the matchers to finish early
+    chaiUtils.flag(this, ASSERTION_ABORTED, true);
+
+    // discard subject since it could potentially be a rejected promise
+    Promise.resolve(this._obj).catch(() => {});
+
+    throw e;
+  }
+}

package/src/internal/utils/account.ts

@@ -0,0 +1,24 @@
+import type { Addressable } from "ethers/address";
+
+import { HardhatError } from "@nomicfoundation/hardhat-errors";
+import { isAddress } from "@nomicfoundation/hardhat-utils/eth";
+import { isAddressable } from "ethers/address";
+
+export async function getAddressOf(
+  account: Addressable | string,
+): Promise<string> {
+  if (isAddress(account)) {
+    return account;
+  }
+
+  if (isAddressable(account)) {
+    return account.getAddress();
+  }
+
+  throw new HardhatError(
+    HardhatError.ERRORS.CHAI_MATCHERS.EXPECTED_STRING_OR_ADDRESSABLE,
+    {
+      account,
+    },
+  );
+}

package/src/internal/utils/asserts.ts

@@ -0,0 +1,156 @@
+import type { AssertWithSsfi, Ssfi } from "./ssfi.js";
+
+import {
+  assertHardhatInvariant,
+  HardhatError,
+} from "@nomicfoundation/hardhat-errors";
+import { ensureError } from "@nomicfoundation/hardhat-utils/error";
+import { keccak256 } from "ethers/crypto";
+import { getBytes, hexlify, isHexString, toUtf8Bytes } from "ethers/utils";
+
+import { ordinal } from "./ordinal.js";
+
+export function assertIsNotNull<T>(
+  value: T,
+  valueName: string,
+): asserts value is Exclude<T, null> {
+  assertHardhatInvariant(value !== null, `${valueName} should not be null`);
+}
+
+export function assertArgsArraysEqual(
+  Assertion: Chai.AssertionStatic,
+  expectedArgs: any[],
+  actualArgs: any[],
+  tag: string,
+  assertionType: "event" | "error",
+  assert: AssertWithSsfi,
+  ssfi: Ssfi,
+): void {
+  try {
+    innerAssertArgsArraysEqual(
+      Assertion,
+      expectedArgs,
+      actualArgs,
+      assertionType,
+      assert,
+      ssfi,
+    );
+  } catch (err) {
+    ensureError(err);
+    err.message = `Error in ${tag}: ${err.message}`;
+    throw err;
+  }
+}
+
+function innerAssertArgsArraysEqual(
+  Assertion: Chai.AssertionStatic,
+  expectedArgs: any[],
+  actualArgs: any[],
+  assertionType: "event" | "error",
+  assert: AssertWithSsfi,
+  ssfi: Ssfi,
+) {
+  assert(
+    actualArgs.length === expectedArgs.length,
+    `Expected arguments array to have length ${expectedArgs.length}, but it has ${actualArgs.length}`,
+  );
+  for (const [index, expectedArg] of expectedArgs.entries()) {
+    try {
+      innerAssertArgEqual(
+        Assertion,
+        expectedArg,
+        actualArgs[index],
+        assertionType,
+        assert,
+        ssfi,
+      );
+    } catch (err) {
+      ensureError(err);
+      err.message = `Error in the ${ordinal(index + 1)} argument assertion: ${
+        err.message
+      }`;
+      throw err;
+    }
+  }
+}
+
+function innerAssertArgEqual(
+  Assertion: Chai.AssertionStatic,
+  expectedArg: any,
+  actualArg: any,
+  assertionType: "event" | "error",
+  assert: AssertWithSsfi,
+  ssfi: Ssfi,
+) {
+  if (typeof expectedArg === "function") {
+    try {
+      if (expectedArg(actualArg) === true) return;
+    } catch (e) {
+      ensureError(e);
+
+      assert(
+        false,
+        `The predicate threw when called: ${e.message}`,
+        // no need for a negated message, since we disallow mixing .not. with
+        // .withArgs
+      );
+    }
+    assert(
+      false,
+      `The predicate did not return true`,
+      // no need for a negated message, since we disallow mixing .not. with
+      // .withArgs
+    );
+  } else if (expectedArg instanceof Uint8Array) {
+    new Assertion(actualArg, undefined, ssfi, true).equal(hexlify(expectedArg));
+  } else if (
+    expectedArg?.length !== undefined &&
+    typeof expectedArg !== "string"
+  ) {
+    innerAssertArgsArraysEqual(
+      Assertion,
+      expectedArg,
+      actualArg,
+      assertionType,
+      assert,
+      ssfi,
+    );
+  } else {
+    if (actualArg.hash !== undefined && actualArg._isIndexed === true) {
+      if (assertionType !== "event") {
+        throw new HardhatError(
+          HardhatError.ERRORS.CHAI_MATCHERS.INDEXED_EVENT_FORBIDDEN,
+        );
+      }
+
+      new Assertion(actualArg.hash, undefined, ssfi, true).to.not.equal(
+        expectedArg,
+        "The actual value was an indexed and hashed value of the event argument. The expected value provided to the assertion should be the actual event argument (the pre-image of the hash). You provided the hash itself. Please supply the actual event argument (the pre-image of the hash) instead.",
+      );
+
+      const expectedArgBytes = isHexString(expectedArg)
+        ? getBytes(expectedArg)
+        : toUtf8Bytes(expectedArg);
+
+      const expectedHash = keccak256(expectedArgBytes);
+
+      new Assertion(actualArg.hash, undefined, ssfi, true).to.equal(
+        expectedHash,
+        `The actual value was an indexed and hashed value of the event argument. The expected value provided to the assertion was hashed to produce ${expectedHash}. The actual hash and the expected hash ${actualArg.hash} did not match`,
+      );
+    } else {
+      new Assertion(actualArg, undefined, ssfi, true).equal(expectedArg);
+    }
+  }
+}
+
+export function assertCanBeConvertedToBigint(
+  value: unknown,
+): asserts value is string | number | bigint {
+  assertHardhatInvariant(
+    typeof value === "string" ||
+      typeof value === "number" ||
+      typeof value === "bigint",
+    "value should be of type string, number or bigint",
+  );
+}

package/src/internal/utils/balance.ts

@@ -0,0 +1,39 @@
+import type { Addressable } from "ethers";
+import type { EthereumProvider } from "hardhat/types/providers";
+
+import { toBigInt } from "@nomicfoundation/hardhat-utils/bigint";
+import { numberToHexString } from "@nomicfoundation/hardhat-utils/hex";
+
+import { getAddressOf } from "./account.js";
+import { assertCanBeConvertedToBigint } from "./asserts.js";
+
+export interface BalanceChangeOptions {
+  includeFee?: boolean;
+}
+
+export function getAddresses(
+  accounts: Array<Addressable | string>,
+): Promise<string[]> {
+  return Promise.all(accounts.map((account) => getAddressOf(account)));
+}
+
+export async function getBalances(
+  provider: EthereumProvider,
+  accounts: Array<Addressable | string>,
+  blockNumber?: number,
+): Promise<bigint[]> {
+  return Promise.all(
+    accounts.map(async (account) => {
+      const address = await getAddressOf(account);
+
+      const result = await provider.request({
+        method: "eth_getBalance",
+        params: [address, numberToHexString(blockNumber ?? 0)],
+      });
+
+      assertCanBeConvertedToBigint(result);
+
+      return toBigInt(result);
+    }),
+  );
+}

package/src/internal/utils/bigint.ts

@@ -0,0 +1,3 @@
+export function isBigInt(source: any): boolean {
+  return typeof source === "bigint";
+}

package/src/internal/utils/build-assert.ts

@@ -0,0 +1,54 @@
+import type { Ssfi } from "./ssfi.js";
+
+import { HardhatError } from "@nomicfoundation/hardhat-errors";
+import { AssertionError } from "chai";
+
+/**
+ * This function is used by the matchers to obtain an `assert` function, which
+ * should be used instead of `this.assert`.
+ *
+ * The first parameter is the value of the `negated` flag. Keep in mind that
+ * this value should be captured at the beginning of the matcher's
+ * implementation, before any async code is executed. Otherwise things like
+ * `.to.emit().and.not.to.emit()` won't work, because by the time the async part
+ * of the first emit is executed, the `.not` (executed synchronously) has already
+ * modified the flag.
+ *
+ * The second parameter is what Chai calls the "start stack function indicator",
+ * a function that is used to build the stack trace. It's unclear to us what's
+ * the best way to use this value, so this needs some trial-and-error. Use the
+ * existing matchers for a reference of something that works well enough.
+ */
+export function buildAssert(negated: boolean, ssfi: Ssfi) {
+  return function (
+    condition: boolean,
+    messageFalse?: string | (() => string),
+    messageTrue?: string | (() => string),
+  ): void {
+    if (!negated && !condition) {
+      if (messageFalse === undefined) {
+        throw new HardhatError(
+          HardhatError.ERRORS.CHAI_MATCHERS.ASSERTION_WITHOUT_ERROR_MESSAGE,
+        );
+      }
+
+      const message =
+        typeof messageFalse === "function" ? messageFalse() : messageFalse;
+      // eslint-disable-next-line no-restricted-syntax -- keep the original chai error structure
+      throw new AssertionError(message, undefined, ssfi);
+    }
+
+    if (negated && condition) {
+      if (messageTrue === undefined) {
+        throw new HardhatError(
+          HardhatError.ERRORS.CHAI_MATCHERS.ASSERTION_WITHOUT_ERROR_MESSAGE,
+        );
+      }
+
+      const message =
+        typeof messageTrue === "function" ? messageTrue() : messageTrue;
+      // eslint-disable-next-line no-restricted-syntax -- keep the original chai error structure
+      throw new AssertionError(message, undefined, ssfi);
+    }
+  };
+}

package/src/internal/utils/ordinal.ts

@@ -0,0 +1,24 @@
+/**
+ * Appends the appropriate ordinal suffix ("st", "nd", "rd", "th") to a given number.
+ *
+ * This function correctly handles special cases such as numbers ending in 11, 12, and 13,
+ * which always use the "th" suffix, and ensures the correct suffix for all other numbers.
+ */
+export function ordinal(n: number): string {
+  const s = ["th", "st", "nd", "rd"];
+  const v = n % 100;
+
+  const suffixIndex = (v - 20) % 10;
+  let suffix = s[suffixIndex];
+
+  if (suffixIndex >= 1 && suffixIndex <= 3) {
+    return n + suffix;
+  }
+
+  suffix = s[v];
+  if (v >= 1 && v <= 3) {
+    return n + suffix;
+  }
+
+  return n + s[0];
+}

package/src/internal/utils/prevent-chaining.ts

@@ -0,0 +1,33 @@
+import { HardhatError } from "@nomicfoundation/hardhat-errors";
+
+import { PREVIOUS_MATCHER_NAME } from "../constants.js";
+
+export function preventAsyncMatcherChaining(
+  context: object,
+  matcherName: string,
+  chaiUtils: Chai.ChaiUtils,
+  allowSelfChaining: boolean = false,
+): void {
+  const previousMatcherName: string | undefined = chaiUtils.flag(
+    context,
+    PREVIOUS_MATCHER_NAME,
+  );
+
+  if (previousMatcherName === undefined) {
+    chaiUtils.flag(context, PREVIOUS_MATCHER_NAME, matcherName);
+
+    return;
+  }
+
+  if (previousMatcherName === matcherName && allowSelfChaining) {
+    return;
+  }
+
+  throw new HardhatError(
+    HardhatError.ERRORS.CHAI_MATCHERS.MATCHER_CANNOT_BE_CHAINED_AFTER,
+    {
+      matcher: matcherName,
+      previousMatcher: previousMatcherName,
+    },
+  );
+}

package/src/internal/utils/ssfi.ts

@@ -0,0 +1,6 @@
+import type { buildAssert } from "./build-assert.js";
+
+// just a generic function type to avoid errors from the ban-types eslint rule
+export type Ssfi = (...args: any[]) => any;
+
+export type AssertWithSsfi = ReturnType<typeof buildAssert>;

package/src/internal/utils/typed.ts

@@ -0,0 +1,9 @@
+import { Typed } from "ethers";
+
+export function tryDereference(value: any, type: string): any | undefined {
+  try {
+    return Typed.dereference(value, type);
+  } catch {
+    return undefined;
+  }
+}

package/src/panic.ts

@@ -0,0 +1 @@
+export { PANIC_CODES } from "./internal/matchers/reverted/panic.js";

package/src/type-extensions.ts

@@ -0,0 +1,82 @@
+import type { HardhatEthers } from "@nomicfoundation/hardhat-ethers/types";
+import type { EthereumProvider } from "hardhat/types/providers";
+
+// We use declare global instead of declare module "chai", because that's what
+// @types/chai does.
+declare global {
+  /* eslint-disable-next-line @typescript-eslint/no-namespace -- We have to use
+  a namespace because @types/chai uses it. */
+  namespace Chai {
+    interface Assertion
+      extends LanguageChains,
+        NumericComparison,
+        TypeComparison {
+      emit(contract: any, eventName: string): EmitAssertion;
+      reverted(ethers: HardhatEthers): AsyncAssertion;
+      revertedWith(reason: string | RegExp): AsyncAssertion;
+      revertedWithoutReason(ethers: HardhatEthers): AsyncAssertion;
+      revertedWithPanic(code?: any): AsyncAssertion;
+      revertedWithCustomError(
+        contract: { interface: any },
+        customErrorName: string,
+      ): CustomErrorAssertion;
+      hexEqual(other: string): void;
+      properPrivateKey: void;
+      properAddress: void;
+      properHex(length: number): void;
+      changeEtherBalance(
+        provider: EthereumProvider,
+        account: any,
+        balance: any,
+        options?: any,
+      ): AsyncAssertion;
+      changeEtherBalances(
+        provider: EthereumProvider,
+        accounts: any[],
+        balances: any[] | ((changes: bigint[]) => boolean),
+        options?: any,
+      ): AsyncAssertion;
+      changeTokenBalance(
+        provider: EthereumProvider,
+        token: any,
+        account: any,
+        balance: any,
+      ): AsyncAssertion;
+      changeTokenBalances(
+        provider: EthereumProvider,
+        token: any,
+        account: any[],
+        balance: any[] | ((changes: bigint[]) => boolean),
+      ): AsyncAssertion;
+    }
+
+    interface NumericComparison {
+      within(start: any, finish: any, message?: string): Assertion;
+    }
+
+    interface NumberComparer {
+      // eslint-disable-next-line -- the interface must follow the original definition pattern
+      (value: any, message?: string): Assertion;
+    }
+
+    interface CloseTo {
+      // eslint-disable-next-line -- the interface must follow the original definition pattern
+      (expected: any, delta: any, message?: string): Assertion;
+    }
+
+    interface Length extends Assertion {
+      // eslint-disable-next-line -- the interface must follow the original definition pattern
+      (length: any, message?: string): Assertion;
+    }
+
+    interface AsyncAssertion extends Assertion, Promise<void> {}
+
+    interface EmitAssertion extends AsyncAssertion {
+      withArgs(...args: any[]): AsyncAssertion;
+    }
+
+    interface CustomErrorAssertion extends AsyncAssertion {
+      withArgs(...args: any[]): AsyncAssertion;
+    }
+  }
+}

package/src/withArgs.ts

@@ -0,0 +1 @@
+export { anyUint, anyValue } from "./internal/matchers/withArgs.js";