TypeScript icon, indicating that this package has built-in type declarations

2.0.7 • Public • Published


Hardhat Chai Matchers

This plugin adds Ethereum-specific capabilities to the Chai assertion library, making your smart contract tests easy to write and read.

Check its documentation to learn more.


We recommend using npm 7 or later. If you do that, then you just need to install the plugin itself:

npm install --save-dev @nomicfoundation/hardhat-chai-matchers

If you are using an older version of npm, you'll also need to install all the packages used by the plugin.

npm install --save-dev @nomicfoundation/hardhat-chai-matchers chai@4 @nomicfoundation/hardhat-ethers ethers

That's also the case if you are using yarn:

yarn add --dev @nomicfoundation/hardhat-chai-matchers chai@4 @nomicfoundation/hardhat-ethers ethers


After installing it, add the plugin to your Hardhat config:


Then you'll be able to use the matchers in your tests:

expect(await token.totalSupply()).to.equal(1_000_000);

await expect(token.transfer(token, 1000)).to.be.revertedWith(
  "Cannot transfer to the contract itself"

await expect(token.transfer(recipient, 1000))
  .to.emit(token, "Transfer")
  .withArgs(owner, recipient, 1000);

Known issues

Chaining Async Matchers

Currently, the following matchers do not support chaining:

  • reverted
  • revertedWith
  • revertedWithCustomError
  • revertedWithoutReason
  • revertedWithPanic
  • changeEtherBalance
  • changeEtherBalances
  • changeTokenBalance
  • changeTokenBalances
  • emit (with the only exception of chaining multiple emit matchers)

Which means you can't do:

await expect(contract.f(...))

To work around this limitation, write separate assertions for each matcher:

const tx = contract.f(...);
await expect(tx).to.changeEtherBalance(...)
await expect(tx).to.changeTokenBalance(...)

If you are interested in seeing an implementation of chaining for async matchers, please visit the GitHub issue #4235 and leave an upvote or comment.

Package Sidebar


npm i @fvictorio/hardhat-chai-matchers

Weekly Downloads






Unpacked Size

227 kB

Total Files


Last publish


  • fvictorio