Hardhat Viem Assertions plugin

This plugin adds an Ethereum-specific assertions 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-assertions@next

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

1// ...
2import hardhatViemAssertions from "@nomicfoundation/hardhat-viem-assertions";
3
4// ...
5
6export default {
7  // ...
8  plugins: [
9    // ...
10    hardhatViemAssertions,
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 assertions to the viem object.

Here is an example of using the balancesHaveChanged assertion:

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 assertions are included to check 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 assertion 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 assertions can be used to check 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);