Hardhat Viem Matchers plugin

This plugin adds an Ethereum-specific matchers assertion library that integrate with viem, making your smart contract tests easy to write and read.

Installation

To install this plugin, run the following command:

1npm install --save-dev @nomicfoundation/hardhat-viem-matchers@next

and add the following statements to your hardhat.config.ts file:

1// ...
2import viemMatchersPlugin from "@nomicfoundation/hardhat-viem-matchers";
3
4// ...
5
6export default {
7  // ...
8  plugins: [
9    // ...
10    viemMatchersPlugin,
11  ],
12
13  // ...
14};

Usage

You don't need to do anything else to use this plugin. Whenever you run your tests with Hardhat, it will automatically add the matchers to the viem object.

Here is an example of using the balancesHaveChanged matcher:

1const { viem } = await hre.network.connect();
2
3const [bobWalletClient, aliceWalletClient] = await viem.getWalletClients();
4
5await viem.assertions.balancesHaveChanged(
6  bobWalletClient.sendTransaction({
7    to: aliceWalletClient.account.address,
8    value: 3333333333333333n,
9  }),
10  [
11    {
12      address: aliceWalletClient.account.address,
13      amount: 3333333333333333n,
14    },
15  ],
16);

Reference

Reverted transactions

Several matchers are included to assert that a transaction reverted, and the reason of the revert.

.revert

Assert that a transaction reverted for any reason, without checking the cause of the revert:

1await viem.assertions.revert(token.write.transfer([address, 0n]));

.revertWith

Assert that a transaction reverted with a specific reason string:

1await viem.assertions.revertWith(
2  token.write.transfer([address, 0n]),
3  "transfer value must be positive",
4);

.revertWithCustomError

Assert that a transaction reverted with a specific custom error:

1await viem.assertions.revertWithCustomError(
2  token.write.transfer([address, 0n]),
3  token,
4  "InvalidTransferValue",
5);

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:

1await viem.assertions.revertWithCustomErrorWithArgs(
2  token.write.transfer([address, 0n]),
3  token,
4  "InvalidTransferValue",
5  [0n],
6);

Events

.emit

Assert that a transaction emits a specific event:

1await viem.assertions.emit(
2  rocketContract.write.launch(),
3  rocketContract,
4  "LaunchEvent",
5);

.emitWithArgs

Assert that a transaction emits an event with specific arguments:

1await viem.assertions.emitWithArgs(
2  rocketContract.write.launch(),
3  rocketContract,
4  "LaunchEventWithArgs",
5  ["Apollo", "lift-off"],
6);

Balance change

These matchers can be used to assert how a given transaction affects the ether balance of a specific address.

.balancesHaveChanged

Assert that a transaction changes the balance of specific addresses:

1await viem.assertions.balancesHaveChanged(
2  bobWalletClient.sendTransaction({
3    to: aliceWalletClient.account.address,
4    value: 3333333333333333n,
5  }),
6  [
7    {
8      address: aliceWalletClient.account.address,
9      amount: 3333333333333333n,
10    },
11    {
12      address: bobWalletClient.account.address,
13      amount: -3333333333333333n,
14    },
15  ],
16);