>
>
Join the Hardhat team! We are hiring
>
>

#Migrating from Waffle

This page explains how to migrate from Waffle to Hardhat Chai Matchers, and the advantages of doing it. Migrating should only take a few minutes.

# How to migrate

The @nomicfoundation/hardhat-chai-matchers plugin is meant to be a drop-in replacement for the @nomiclabs/hardhat-waffle plugin. To migrate, follow these instructions:

  1. Uninstall the @nomiclabs/hardhat-waffle and ethereum-waffle packages:

    npm 7+
    npm 6
    yarn
    npm uninstall @nomiclabs/hardhat-waffle ethereum-waffle

    npm uninstall @nomiclabs/hardhat-waffle ethereum-waffle

    yarn remove @nomiclabs/hardhat-waffle ethereum-waffle

  2. Then install the Hardhat Chai Matchers plugin:

    npm 7+
    npm 6
    yarn
    npm install --save-dev @nomicfoundation/hardhat-chai-matchers

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

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

  3. In your Hardhat config, import the Hardhat Chai Matchers plugin and remove the hardhat-waffle one:

    TypeScript
    JavaScript
    - import "@nomiclabs/hardhat-waffle";
+ import "@nomicfoundation/hardhat-chai-matchers";

    - require("@nomiclabs/hardhat-waffle");
+ require("@nomicfoundation/hardhat-chai-matchers");

  4. If you were not importing the @nomiclabs/hardhat-ethers plugin explicitly (because the Hardhat Waffle plugin already imported it), then add it to your config:

    TypeScript
    JavaScript
    import "@nomiclabs/hardhat-ethers";

    require("@nomiclabs/hardhat-ethers");

TIP

Looking for a replacement of Waffle's loadFixture? You can find our version of it in Hardhat Network Helpers.

# Why migrate?

The Hardhat Chai Matchers are compatible with Waffle's API and offer several advantages:

  • More features: the Hardhat Chai Matchers include new matchers, like .revertedWithCustomError and .revertedWithPanic, which let you perform better assertions of a transaction's revert reason.
  • Support for native BigInts: Besides numbers and ethers’s BigNumbers, you can also use JavaScript's native BigInts in your assertions, which means being able to do things like expect(await token.totalSupply()).to.equal(10n**18n) instead of expect(await token.totalSupply()).to.equal(ethers.BigNumber.from("1000000000000000000")).
  • More reliable: Several problems and minor bugs in Waffle's matchers are fixed in the Hardhat Chai Matchers.