chore: add viem assertion to example project

To aid manual testing of assertions, add the viem assertion plugin to
the example project.

Author: kanej

pnpm-lock.yaml

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity ^0.8.0;
+pragma solidity *;
+
+contract FailingContract {
+  error CustomError();
+  error CustomErrorWithUintAndString(uint, string);
+
+  function fail() public pure {
+    innerRevert();
+  }
+
+  function innerRevert() internal pure {
+    revert("Revert Message");
+  }
+
+  function failByRevertWithCustomError() external pure {
+    revert CustomError();
+  }
+
+  function failByRevertWithCustomErrorWithUintAndString(
+    uint n,
+    string memory s
+  ) external pure {
+    revert CustomErrorWithUintAndString(n, s);
+  }
+}

v-next/example-project/contracts/FailingContract.sol

@@ -5,12 +5,18 @@ contract Rocket {
   string public name;
   string public status;
 
+  event LaunchWithoutArgs();
+  event LaunchWithTwoStringArgs(string u, string v);
+
   constructor(string memory _name) {
     name = _name;
     status = "ignition";
   }
 
   function launch() public {
     status = "lift-off";
+
+    emit LaunchWithoutArgs();
+    emit LaunchWithTwoStringArgs(name, status);
   }
 }

v-next/example-project/contracts/Rocket.sol

@@ -8,6 +8,7 @@ import HardhatNodeTestRunner from "@nomicfoundation/hardhat-node-test-runner";
 import HardhatMochaTestRunner from "@nomicfoundation/hardhat-mocha";
 import HardhatKeystore from "@nomicfoundation/hardhat-keystore";
 import HardhatViem from "@nomicfoundation/hardhat-viem";
+import HardhatViemMatchers from "@nomicfoundation/hardhat-viem-matchers";
 import hardhatNetworkHelpersPlugin from "@nomicfoundation/hardhat-network-helpers";
 import hardhatEthersPlugin from "@nomicfoundation/hardhat-ethers";
 import hardhatChaiMatchersPlugin from "@nomicfoundation/hardhat-ethers-chai-matchers";
@@ -156,6 +157,7 @@ const config: HardhatUserConfig = {
     hardhatNetworkHelpersPlugin,
     HardhatNodeTestRunner,
     HardhatViem,
+    HardhatViemMatchers,
     hardhatChaiMatchersPlugin,
     hardhatTypechain,
     hardhatIgnitionViem,

v-next/example-project/hardhat.config.ts

@@ -36,6 +36,7 @@
     "@nomicfoundation/hardhat-node-test-runner": "workspace:^3.0.0-next.11",
     "@nomicfoundation/hardhat-typechain": "workspace:^3.0.0-next.11",
     "@nomicfoundation/hardhat-viem": "workspace:^3.0.0-next.11",
+    "@nomicfoundation/hardhat-viem-matchers": "workspace:^3.0.0-next.11",
     "@openzeppelin/contracts": "5.1.0",
     "@types/chai": "^4.2.0",
     "@types/mocha": ">=10.0.10",

v-next/example-project/package.json

@@ -0,0 +1,82 @@
+import { describe, it, before } from "node:test";
+import hre from "hardhat";
+import { ContractReturnType } from "@nomicfoundation/hardhat-viem/types";
+
+const { viem } = await hre.network.connect();
+
+describe("Example EDR based test", () => {
+  describe("revert", () => {
+    let failingContract: ContractReturnType<"FailingContract">;
+
+    before(async () => {
+      failingContract = await viem.deployContract("FailingContract");
+    });
+
+    it("should support checking that a transaction reverts", async () => {
+      await viem.assertions.revert(failingContract.read.fail());
+    });
+
+    it("should support checking that a transaction reverts with a specific message", async () => {
+      await viem.assertions.revertWith(
+        failingContract.read.fail(),
+        "Revert Message",
+      );
+    });
+
+    it("should support checking that a transaction reverts with a custom error and specific arguments", async () => {
+      await viem.assertions.revertWithCustomErrorWithArgs(
+        failingContract.read.failByRevertWithCustomErrorWithUintAndString([
+          10n,
+          "example",
+        ]),
+        failingContract,
+        "CustomErrorWithUintAndString",
+        [10n, "example"],
+      );
+    });
+  });
+
+  describe("Events", () => {
+    it("should support detecting an emitted event", async () => {
+      const rocketContract = await viem.deployContract("Rocket", ["Apollo"]);
+
+      await viem.assertions.emit(
+        rocketContract.write.launch(),
+        rocketContract,
+        "LaunchWithoutArgs",
+      );
+    });
+
+    it("should support detecting an emitted events arguments", async () => {
+      const rocketContract = await viem.deployContract("Rocket", ["Apollo"]);
+
+      await viem.assertions.emitWithArgs(
+        rocketContract.write.launch(),
+        rocketContract,
+        "LaunchWithTwoStringArgs",
+        ["Apollo", "lift-off"],
+      );
+    });
+  });
+
+  it("should support detecting a change of balance", async () => {
+    const [bobWalletClient, aliceWalletClient] = await viem.getWalletClients();
+
+    await viem.assertions.balancesHaveChanged(
+      bobWalletClient.sendTransaction({
+        to: aliceWalletClient.account.address,
+        value: 3333333333333333n,
+      }),
+      [
+        {
+          address: aliceWalletClient.account.address,
+          amount: 3333333333333333n,
+        },
+        {
+          address: bobWalletClient.account.address,
+          amount: -3333333333333333n,
+        },
+      ],
+    );
+  });
+});

v-next/example-project/test/node/example-test-of-assertions.ts

@@ -25,6 +25,9 @@
     {
       "path": "../hardhat-viem"
     },
+    {
+      "path": "../hardhat-viem-matchers"
+    },
     {
       "path": "../hardhat-ethers-chai-matchers"
     },

v-next/example-project/tsconfig.json

@@ -65,57 +65,45 @@ Several matchers are included to assert that a transaction reverted, and the rea
 Assert that a transaction reverted for any reason, without checking the cause of the revert:
 
 ```ts
-revert(
-  contractFn: Promise<ReadContractReturnType | WriteContractReturnType>,
-): Promise<void>;
+await viem.assertions.revert(token.write.transfer([address, 0n]));
 ```
 
 #### `.revertWith`
 
 Assert that a transaction reverted with a specific reason string:
 
 ```ts
-revertWith(
-  contractFn: Promise<ReadContractReturnType | WriteContractReturnType>,
-  expectedRevertReason: string,
-): Promise<void>;
-```
-
-You can also use regular expressions:
-
-```ts
-xxxx;
+await viem.assertions.revertWith(
+  token.write.transfer([address, 0n]),
+  "transfer value must be positive",
+);
 ```
 
 #### `.revertWithCustomError`
 
 Assert that a transaction reverted with a specific custom error:
 
 ```ts
-revertWithCustomError<ContractName extends CompiledContractName>(
-  contractFn: Promise<ReadContractReturnType | WriteContractReturnType>,
-  contract: ContractReturnType<ContractName>,
-  customErrorName: string,
-): Promise<void>;
+await viem.assertions.revertWithCustomError(
+  token.write.transfer([address, 0n]),
+  token,
+  "InvalidTransferValue",
+);
 ```
 
-The first argument must be the contract that defines the error. The contract is used to determine the full signature of the expected error. The matcher does not check whether the error was emitted by the contract.
-
-If the error has arguments, the .withArgs matcher can be added:
-
-xxx
+The second argument must be the contract that defines the error. The contract is used to determine the full signature of the expected error. The matcher does not check whether the error was emitted by the contract.
 
 #### `.revertWithCustomErrorWithArgs`
 
 Assert that a transaction reverted with a custom error and specific arguments:
 
 ```ts
-revertWithCustomErrorWithArgs<ContractName extends CompiledContractName>(
-  contractFn: Promise<ReadContractReturnType | WriteContractReturnType>,
-  contract: ContractReturnType<ContractName>,
-  customErrorName: string,
-  args: any[],
-): Promise<void>;
+await viem.assertions.revertWithCustomErrorWithArgs(
+  token.write.transfer([address, 0n]),
+  token,
+  "InvalidTransferValue",
+  [0n],
+);
 ```
 
 ### Events
@@ -125,34 +113,24 @@ revertWithCustomErrorWithArgs<ContractName extends CompiledContractName>(
 Assert that a transaction emits a specific event:
 
 ```ts
-emit<
-  ContractName extends CompiledContractName,
-  EventName extends ContractName extends keyof ContractAbis
-    ? ContractEventName<ContractAbis[ContractName]>
-    : string,
->(
-  contractFn: Promise<ReadContractReturnType | WriteContractReturnType>,
-  contract: ContractReturnType<ContractName>,
-  eventName: EventName,
-): Promise<void>;
+await viem.assertions.emit(
+  rocketContract.write.launch(),
+  rocketContract,
+  "LaunchEvent",
+);
 ```
 
 #### `.emitWithArgs`
 
 Assert that a transaction emits an event with specific arguments:
 
 ```ts
-emitWithArgs<
-  ContractName extends CompiledContractName,
-  EventName extends ContractName extends keyof ContractAbis
-    ? ContractEventName<ContractAbis[ContractName]>
-    : string,
->(
-  contractFn: Promise<ReadContractReturnType | WriteContractReturnType>,
-  contract: ContractReturnType<ContractName>,
-  eventName: EventName,
-  args: any[],
-): Promise<void>;
+await viem.assertions.emitWithArgs(
+  rocketContract.write.launch(),
+  rocketContract,
+  "LaunchEventWithArgs",
+  ["Apollo", "lift-off"],
+);
 ```
 
 ### Balance change
@@ -164,11 +142,20 @@ These matchers can be used to assert how a given transaction affects the ether b
 Assert that a transaction changes the balance of specific addresses:
 
 ```ts
-balancesHaveChanged: (
-  resolvedTxHash: Promise<Hash>,
-  changes: Array<{
-    address: Address;
-    amount: bigint;
-  }>,
-) => Promise<void>;
+await viem.assertions.balancesHaveChanged(
+  bobWalletClient.sendTransaction({
+    to: aliceWalletClient.account.address,
+    value: 3333333333333333n,
+  }),
+  [
+    {
+      address: aliceWalletClient.account.address,
+      amount: 3333333333333333n,
+    },
+    {
+      address: bobWalletClient.account.address,
+      amount: -3333333333333333n,
+    },
+  ],
+);
 ```